pay | SignalWire

Collect and process a credit card payment during the call. Generates a SWML pay verb that walks the caller through entering card details by DTMF, then submits to your payment connector endpoint.

Parameters

payment_connector_url

strRequired

URL of your payment processing endpoint. SignalWire sends the collected card data to this URL for processing.

input_method

strDefaults to dtmf

How the caller provides card details. The SWML pay verb accepts only "dtmf": the caller enters digits on the keypad.

status_url

str | NoneDefaults to None

URL to receive payment status change webhook notifications.

payment_method

strDefaults to credit-card

Payment method type. Currently only "credit-card" is supported.

timeout

intDefaults to 5

Seconds to wait for the next DTMF digit before timing out.

max_attempts

intDefaults to 1

Number of retry attempts if payment collection fails.

security_code

boolDefaults to True

Whether to prompt the caller for the card’s security code (CVV).

postal_code

bool | strDefaults to True

Whether to prompt for the billing postal code. Pass True to prompt, False to skip, or a string with the actual postal code to use without prompting.

min_postal_code_length

intDefaults to 0

Minimum number of digits required for the postal code.

token_type

strDefaults to reusable

Payment token type.

"one-time" — single-use token
"reusable" — token can be charged again later

charge_amount

str | NoneDefaults to None

Amount to charge as a decimal string (e.g., "49.99").

currency

strDefaults to usd

ISO 4217 currency code (e.g., "usd", "eur").

language

strDefaults to en-US

Language for TTS payment prompts (e.g., "en-US", "es-MX").

voice

strDefaults to woman

TTS voice for payment prompts (e.g., "woman", "man").

description

str | NoneDefaults to None

Custom description for the payment transaction.

valid_card_types

strDefaults to visa mastercard amex

Space-separated list of accepted card types.

parameters

list[dict[str, str]] | NoneDefaults to None

Additional name/value pairs to send to the payment connector. Use create_payment_parameter() to build entries.

prompts

list[dict[str, Any]] | NoneDefaults to None

Custom prompt configurations to override default payment prompts. Use create_payment_prompt() to build entries.

ai_response

str | NoneDefaults to 'The payment status is ${pay_result}...'

AI response template after payment completes. The ${pay_result} variable is substituted with the payment outcome. Set to None to disable.

Returns

FunctionResult — self, for chaining.

Example

from signalwire import AgentBase
from signalwire import FunctionResult
agent = AgentBase(name="my-agent", route="/agent")
agent.set_prompt_text("You are a helpful assistant.")
@agent.tool(name="collect_payment", description="Collect a credit card payment")
def collect_payment(args, raw_data):
    amount = args.get("amount")
    return (
        FunctionResult("I'll collect your payment information now.")
        .pay(
            payment_connector_url="https://api.example.com/payment",
            charge_amount=amount,
            currency="usd",
            security_code=True,
            postal_code=True
        )
    )
agent.serve()