Pay

Overview

The <Pay> verb enables secure payment processing during voice calls. When implemented in your voice application, it handles the complete payment flow including data collection, validation, and processing through your configured payment gateway.

The <Pay> verb also has two nouns that are embedded within it:

• <Parameter>: Pass custom parameters to your payment processor.
• <Prompt>: Customize the prompts used during payment collection.

Core functionality

• Secure payment information collection
• Real-time payment processing
• Payment method tokenization
• Multi-currency support
• Automated retry handling
• Status tracking via webhooks

Transaction types

The <Pay> verb supports two primary transaction types: immediate charges and tokenization.

Immediate charges

When you need to process a payment right away, use an immediate charge transaction. This collects the payment details and processes the transaction in one step.

To execute an immediate charge:

<Pay chargeAmount="25.00"/>

Setting any positive value for chargeAmount initiates an immediate charge transaction.

Tokenization

Tokenization allows you to securely store payment information for future use. Instead of processing a payment, it generates a secure token that represents the payment method. This is particularly useful for:

• Subscription services
• Recurring billing

To tokenize payment information:

<Pay chargeAmount="0"/>

You can also omit the chargeAmount attribute entirely.

Your payment connector creates the token with your payment processor and returns it as token_id. SignalWire passes it to your action URL as PaymentToken, and you can use it for future transactions without asking the customer to re-enter their payment details. See the tokenization example for the full flow.

Attributes

Webhook request parameters

paymentConnectorUrl request parameters

When all payment details have been collected from the caller, SignalWire sends a POST request with a JSON body to your paymentConnectorUrl. Charges and tokenization send the same fields. SignalWire signs the request, so see securing your payment connector to verify it.

Example

{
  "transaction_id": "8c9d14d5-52ae-4e2e-b880-a14e6e1cda7d",
  "method": "credit-card",
  "cardnumber": "4242424242424242",
  "cvv": "123",
  "postal_code": "12345",
  "description": "renew plan",
  "chargeAmount": "123.45",
  "token_type": "reusable",
  "expiry_month": "01",
  "expiry_year": "38",
  "currency_code": "usd",
  "parameters": [
    { "custom1": "value1" }
  ]
}

action request parameters

When a transaction is completed, SignalWire will POST to your action URL. The body of the request will contain the standard request parameters as well as the following parameters:

Result values

statusCallback request parameters

When a status change occurs, the following parameters are sent to your statusCallback URL:

For values

To find out whether the payment succeeded, check PayResult on the action request.

Error types

Webhook response

paymentConnectorUrl response

The response from your paymentConnectorUrl is used to inform if the transaction was successful or not.

Successful transaction

When a transaction is successful, the webhook should respond with one of the following formats (depending on the transaction type):

{
  "charge_id":"charge_id",
  "error_code":null,
  "error_message":null
}

SignalWire passes charge_id to your action URL as PaymentConfirmationCode. When chargeAmount is zero or omitted, it passes token_id as PaymentToken.

Unsuccessful transaction

When a transaction is unsuccessful (declined by the payment processor), the webhook should respond with the following format:

{
  "charge_id": null,
  "error_code": "some error code",
  "error_message": "some error message"
}

action response

When a transaction is completed, SignalWire will POST to your action URL. The response should return valid cXML for the next step in your application.

Example

<Response>
  <Say>Thank you for your payment. Your transaction has been completed.</Say>
  <Hangup/>
</Response>

Language support

The language attribute controls the language of automated prompts during payment collection.

Credit card payments

All credit card payments support the following languages:

English variants

• en-AU (Australian English)
• en-CA (Canadian English)
• en-GB (British English)
• en-IN (Indian English)
• en-US (American English)

Additional languages

• es-ES (European Spanish)
• es-MX (Mexican Spanish)
• fr-CA (Canadian French)
• fr-FR (European French)
• de-DE (German)
• it-IT (Italian)

Examples

Simple payment collection:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your payment information</Say>
    <Pay chargeAmount="20.45"/>
</Response>

Payment with status tracking:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your payment information</Say>
    <Pay 
        chargeAmount="20.45"
        action="https://your-callback-url.example.com/pay"
        statusCallback="https://your-callback-url.example.com/status"
    />
</Response>

Basic tokenization:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your card information to save for future use</Say>
    <Pay 
        tokenType="reusable"
        chargeAmount="0"
    />
</Response>

Tokenization with validation:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your card information</Say>
    <Pay 
        tokenType="reusable"
        chargeAmount="0"
        validCardTypes="visa mastercard"
        securityCode="true"
        postalCode="true"
    />
</Response>

Tokenize a card end to end

This <Pay> saves a card without charging it:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your card information to save for future use</Say>
    <Pay
        chargeAmount="0"
        tokenType="reusable"
        paymentConnectorUrl="https://pay.example.com/connector"
        action="https://example.com/pay-result"
    />
</Response>

SignalWire collects the card details and sends them to your payment connector with "chargeAmount": "0" and "token_type": "reusable". Your connector saves the card with your payment processor and replies with the processor’s token:

{
  "token_id": "pm_1234567890",
  "error_code": null,
  "error_message": null
}

SignalWire then sends your action URL PayResult=success and PaymentToken=pm_1234567890. Store the token to charge the card later through your payment processor.

Custom retry logic:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Please enter your payment information</Say>
    <Pay 
        chargeAmount="75.00"
        maxAttempts="3"
        timeout="10"
    />
</Response>

International payment:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Por favor, ingrese su información de pago</Say>
    <Pay 
        chargeAmount="100.00"
        currency="mxn"
        language="es-MX"
        description="Mexican peso transaction"
    />
</Response>

Example with custom parameters and prompts

<Response>
<Pay chargeAmount="123.45" paymentConnectorUrl="https://example.com/accept-payment" description="renew plan">
  <Parameter name="custom1" value="value1"/>
  <Prompt for="payment-card-number" attempt="1"><Say>Let's collect your payment information. Please enter your credit card number</Say></Prompt>
  <Prompt for="payment-card-number" attempt="2 3"><Say>Please enter your credit card number</Say></Prompt>
  <Prompt for="security-code" cardType="amex"><Say>Please enter your credit card's security code. It's the 4 digits located on the front of your card. </Say></Prompt>
</Pay>
</Response>

Securing your payment connector

Requests to your paymentConnectorUrl carry the X-SignalWire-Signature and X-SignalWire-SHA256-Signature headers, keyed with your project’s Signing Key. They don’t come from a published IP range, so verify the signature and reject any request that doesn’t match. The connector request is signed like a JSON webhook, not like your action and statusCallback requests: X-SignalWire-Signature is the lowercase hex HMAC-SHA1 of the connector URL, with any credentials removed, followed by the raw JSON body. The form-parameter validation you use for other cXML webhooks won’t match it. SignalWire normalizes the URL before signing it: the scheme is lowercased, . and .. path segments are resolved, and a URL without a path gets /, so https://example.com is signed as https://example.com/.

For a second layer, put credentials in the connector URL. Credentials such as https://payuser:<LONG_RANDOM_SECRET>@pay.example.com/connector are sent as a standard Basic Authorization header and aren’t part of the signed URL, so your connector can check both. A long random token in the URL path works too, and it is part of the signed URL.