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:

1
<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:

1
<Pay chargeAmount="0"/>

You can also omit the chargeAmount attribute entirely:

Attributes

Webhook request parameters

paymentConnectorUrl request parameters

When a transaction is completed, SignalWire will POST to your paymentConnectorUrl URL. Based on the transaction type, the body of the request will contain the below parameters:

1
{
2
  "transaction_id":"id",
3
  "method":"credit-card",
4
  "cardnumber":"1234123412341234",
5
  "cvv":"123",
6
  "postal_code":"12345",
7
  "description":"renew plan",
8
  "chargeAmount":123.45,
9
  "expiry_month":"01",
10
  "expiry_year":"38",
11
  "currency_code":"USD",
12
  "parameters":{
13
    "custom1":"value1"
14
  }
15
}

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:

Status callback events

For values

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):

1
{
2
  "charge_id":"charge_id",
3
  "error_code":null,
4
  "error_message":null
5
}

Unsuccessful transaction

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

1
{
2
  "charge_id": null,
3
  "error_code": "some error code",
4
  "error_message": "some error message"
5
}

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

1
<Response>
2
  <Say>Thank you for your payment. Your transaction has been completed.</Say>
3
  <Hangup/>
4
</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:

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

Payment with status tracking:

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

Basic tokenization:

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

Tokenization with validation:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Say>Please enter your card information</Say>
4
    <Pay 
5
        tokenType="reusable"
6
        chargeAmount="0"
7
        validCardTypes="visa mastercard"
8
        securityCode="true"
9
        postalCode="true"
10
    />
11
</Response>

Custom retry logic:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Say>Please enter your payment information</Say>
4
    <Pay 
5
        chargeAmount="75.00"
6
        maxAttempts="3"
7
        timeout="10"
8
    />
9
</Response>

International payment:

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

Example with custom parameters and prompts

1
<Response>
2
<Pay chargeAmount="123.45" paymentConnectorUrl="https://example.com/accept-payment" description="renew plan">
3
  <Parameter name="custom1" value="value1"/>
4
  <Prompt name="payment-card-number" attempt="1"><Say>Let's collect your payment information. Please enter your credit card number</Say></Prompt>
5
  <Prompt name="payment-card-number" attempt="2 3"><Say>Please enter your credit card number</Say></Prompt>
6
  <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>
7
</Pay>
8
</Pay>
9
</Response>

Security best practices

1. Always use HTTPS for callback URLs
2. Implement webhook validation
3. Monitor payment status callbacks
4. Handle errors gracefully
5. Store tokens securely
6. Use appropriate timeout values
7. Implement proper error handling
8. Validate all inputs
9. Monitor transaction patterns
10. Keep payment connector configurations secure