`<Pay>`

The <Pay> verb is used to collect payment information and send it to a payment connector during a call.

`<Pay>` Attributes

<Pay> supports the following attributes that change its behavior:

Attribute	Allowed Values	Default Value
action	relative or absolute URL	none
bankAccountType	`consumer-checking`, `consumer-savings`, `commercial-checking`	`consumer-checking`
chargeAmount	number >= 0	`0`
currency	`usd`	`usd`
description	string	none
input	`dtmf`	`dtmf`
history	`disable`, `compact`, `full`	`disable`
language	`en-AU`, `en-IN`, `en-GB`, `en-US`, `es-ES`, `es-US`, `es-MX`, `fr-CA`, `fr-FR`, `de-DE`, `it-IT`	`en-US`
maxAttempts	`1`, `2`, `3`	`2`
method	`GET`, `POST`	`POST`
minPostalCodeLength	integer > 0	none
output	alphanumeric name	none
paymentConnector	string	`Default`
paymentMethod	`credit-card`, `ach-debit`	`credit-card`
postalCode	`true`, `false`	`true`
securityCode	`true`, `false`	`true`
statusCallback	relative or absolute URL	none
statusCallbackMethod	`GET`, `POST`	`POST`
timeout	integer > 0	`5`
tokenType	`one-time`, `reusable`	`reusable`
validCardTypes	`visa`, `mastercard`, `amex`, `maestro`, `discover`, `jcb`, `diners-club`, `enroute`	`visa mastercard amex`

action

The action attribute accepts an absolute or relative URL as its argument. When the caller finished entering digits (or the timeout is reached), Voxtelesys will make an HTTP request to this URL.

After <Pay> ends and Voxtelesys sends its request to your action URL, the current call will continue using the VoXML you send back from that URL. Because of this, any VoXML verbs that occur after your <Pay> are unreachable if action is provided.

If you do not provide an action parameter, Voxtelesys will continue onto the next verb in the current VoXML document.

See additional parameters sent on the action webhook.

bankAccountType

The bankAccountType is the type of ACH bank account to send to the payment connector. Only applies if paymentMethod is ach-debit. This value defaults to consumer-checking.

chargeAmount

The decimal amount that the credit card or ACH account should be charged immediately. If chargeAmount is 0 or omitted, then the payment information will instead be tokenized so that the payment method can be charged later.

When paymentMethod is ach-debit, the chargeAmount must be 0 or absent because immediate payments for ACH bank accounts are currently not supported.

currency

The currency attributes is the currency to use for the transaction. Currently, only usd is supported.

description

The description attribute is an optional description that provides additional details for the payment. This description is sent to the payment connector along with the rest of the payment information.

input

The input attribute specifies which inputs Voxtelesys should accept when collecting payment information. Currently, only DTMF input is supported.

To ensure PCI-compliance, DTMF input collected within <Pay> is excluded from HTTP callbacks and logs.

history

The history attribute determines if the <Pay> verb should be logged in the history array of the CDR. The default is to not log.

For <Pay>, the compact and full values log the following payload to the history array respectively.

compact

{
  "payload": {
    "input": "dtmf",
    "action": "/next",
    "output": "pay"
  }
}

full

{
  "payload": {
    "input": "dtmf",
    "action": "/next",
    "timeout": "5",
    "bankAccountType": "consumer-checking",
    "validCardTypes": "visa mastercard amex",
    "postalCode": "true",
    "securityCode": "true",
    "minPostalCodeLength": "5",
    "method": "POST",
    "chargeAmount": "1.00",
    "tokenType": "reusable",
    "currency": "usd",
    "description": "Test payment",
    "language": "en-US",
    "maxAttempts": "1",
    "paymentConnector": "Default",
    "paymentMethod": "credit-card",
    "statusCallback": "http://example.com",
    "statusCallbackMethod": "POST"
  }
}

The <Pay> verb will also generate an element in the history array with the final status of <Pay>, if either compact or full is used.

{
  "payload": {
    "status": "completed"
  }
}

All input collected with the <Pay> verb is omitted from the history payload.

language

The language attribute specifies the language in which each prompt should be spoken.

This value defaults to en-US.

Acceptables values include: en-AU, en-IN, en-GB, en-US, es-ES, es-US, es-MX, fr-CA, fr-FR, de-DE, and it-IT.

maxAttempts

The maxAttempts attribute specifies the maximum number of attempts that should be allowed before ending execution of the <Pay> verb. The default value is 2, which means that each prompt is allowed one retry if an invalid input is received.

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

minPostalCodeLength

The minPostalCodeLength attribute specifies the minimum length allowed for the postal code collected during the call. Only applies when postalCode is true.

output

The output attribute accepts an alphanumeric variable name, up to 50 characters. The final status of <Pay> is saved to this variable via the <output>.status variable.

paymentConnector

The paymentConnector attribute specifies which payment connector to send the payment information to. The value of this attribute must match the name of a payment connector on the customer's account The default value for paymentConnector is Default. If the value of paymentConnector does not match the name of a payment connector on the account, then the call will hang up when the <Pay> verb is reached.

paymentMethod

The paymentMethod attribute specifies the type of payment information that should be collected during the call. The valid values for paymentMethod include credit-card and ach-debit, and the default is credit-card.

If paymentMethod is credit-card, then the following fields will be collected in this order:

Credit card number
Expiration date
Postal code (if postalCode is true)
Security code (if securityCode is true)

If paymentMethod is ach-debit, then the following fields will be collected in this order:

Bank routing number
Bank account number

Currently, ach-debit only supports the creation of one-time tokens. Immediate payments and reusable tokens are not allowed for ach-debit.

timeout

The timeout allows you to set the limit (in seconds) that Voxtelesys will wait for the caller to press another digit before it proceeds to the next prompt.

For example, if timeout is 3, Voxtelesys waits three seconds for the caller to press another key before validating the input and either retrying or proceeding to the next prompt.

postalCode

The postalCode attribute determines whether to collect a postal code during the call. If postalCode is false, then the postal code will not be collected. Defaults to true.

securityCode

The securityCode attribute determines whether to collect the credit card's security code during the call. If securityCode is false, then the security code will not be collected. Defaults to true.

statusCallback

The statusCallback attribute accepts a relative or absolute URL. If a statusCallback is given, then an HTTP request will be sent to the specified URL for each prompt that is executed in the <Pay> verb.

See additional parameters sent on the status webhook.

statusCallbackMethod

The statusCallbackMethod attribute specifies which HTTP method to use when sending a callback to the statusCallback URL. The default is POST.

tokenType

The tokenType attribute indicates that type of token that should be created using the payment information collected during the call. Valid values include one-time and reusable. This attribute only applies when chargeAmount is 0 or omitted.

When paymentMethod is ach-debit, the tokenType must be one-time because reusable tokens are currently not supported for ACH bank accounts.

validCardTypes

The validCardTypes is a space-delimited list of credit card types that are allowed. The valid credit card types are visa, mastercard, amex, maestro, discover, jcb, diners-club, enroute, and the default value is visa mastercard amex. This attribute only applies when paymentMethod is credit-card.

`<Pay>` Nouns

You may choose to nest the following nouns within <Pay>:

`<Pay>` Webhooks

`action` Webhook

If you specify an action URL, Voxtelesys will send a webhook with the following additional parameters:

Parameter	Description
`Result`	The result of the `<Pay>` verb.
`PaymentMethod`	The type of payment method that is collected.
`PaymentCardType`	The type of credit card provided during the call, if applicable.
`PaymentCardNumber`	The credit card number collected during the call, with all but the last four digits redacted (e.g. `xxxxxxxxxxxx1234`).
`SecurityCode`	The credit card security code collected during the call, fully redacted (e.g. `xxxx`).
`ExpirationDate`	The credit card expiration date collected during the call, with the format `MMYYYY`.
`BankAccountNumber`	The ACH bank account number collected during the call, with all but the last two digits redacted (e.g. `xxxxxxxxxx12`)
`BankRoutingNumber`	The ACH bank routing number collected during the call.
`BankAccountType`	The type of ACH bank account collected.
`ProfileId`	The ID of the customer on the payment connector, if applicable.
`PaymentToken`	The ID of the token that was created with the payment information, if applicable.
`PaymentConfirmationCode`	The ID of the payment that was created, if applicable.
`ConnectorError`	The error code received by the payment connector, if applicable.
`PaymentError`	The error message received by the payment connector, if applicable.

The possible values for Result are:

Value	Description
`success`	The payment or tokenization was successfully processed by the paymenty gateway.
`too-many-failed-attempts`	The maximum number of attempts was reached without receiving valid input.
`payment-connector-error`	The payment connector responded with an error.
`caller-interrupted-with-star`	The `*` digit was pressed during the `<Pay>` verb execution and the process was aborted.
`internal-error`	An internal error was encountered.

`status` Webhook

If you specify a statusCallback URL, Voxtelesys will send a webhook with the following additional parameters:

Parameter	Description
`For`	The current stage of execution.
`ErrorType`	The type of error that occurred, if applicable.
`Attempt`	The number of the current attempt.
`PaymentMethod`	The type of payment method that is collected.
`PaymentCardType`	The type of credit card provided during the call, if applicable.
`PaymentCardNumber`	The credit card number collected during the call, with all but the last four digits redacted (e.g. `xxxxxxxxxxxx1234`).
`SecurityCode`	The credit card security code collected during the call, fully redacted (e.g. `xxxx`).
`ExpirationDate`	The credit card expiration date collected during the call, with the format `MMYYYY`.
`BankAccountNumber`	The ACH bank account number collected during the call, with all but the last two digits redacted (e.g. `xxxxxxxxxx12`)
`BankRoutingNumber`	The ACH bank routing number collected during the call, with all but the last two digits redacted (e.g. `xxxxxxx12`)
`BankAccountType`	The type of ACH bank account collected.

The possible values for For are:

Value	Description
`payment-card-number`	The credit card number is being collected.
`expiration-date`	The credit card expiration date is being collected.
`security-code`	The credit card security code is being collected.
`postal-code`	The postal code is being collected.
`bank-routing-number`	The ACH bank routing number being collected.
`bank-account-number`	The ACH bank account number is being collected.
`payment-processing`	The payment information is being sent to the payment connector.

The possible values for ErrorType are:

Value	Description
`input-timeout`	The `timeout` was reached before input was received.
`invalid-card-number`	The credit card number is invalid.
`invalid-security-code`	The credit card security code is invalid.
`invalid-card-type`	The credit card type is not allowed.
`invalid-date`	The credit card expiration date is invalid.
`invalid-postal-code`	The postal code is invalid.
`invalid-bank-routing-number`	The ACH bank routing number is invalid.
`invalid-bank-account-number`	The ACH bank account number is invalid.
`input-matching-failed`	The inputs did not match when `requireMatchingInputs` was used.
`max-attempts`	Failed to collect payment information since the maximum number of attempts was reached.
`internal-error`	An internal error occurred.

`<Pay>` Examples

Simple Usage

Prompt the caller to enter their credit card, and charge the credit card $10.00 using the test payment connector.

<Response>
  <Pay action="/next" chargeAmount="10.00" paymentConnector="test"/>
</Response>

<Pay> Attributes​

action​

bankAccountType​

chargeAmount​

currency​

description​

input​

history​

language​

maxAttempts​

method​

minPostalCodeLength​

output​

paymentConnector​

paymentMethod​

timeout​

postalCode​

securityCode​

statusCallback​

statusCallbackMethod​

tokenType​

validCardTypes​

<Pay> Nouns​

<Pay> Webhooks​

action Webhook​

status Webhook​

<Pay> Examples​

Simple Usage​