Shuttle Pay Connector Reference

This reference covers the Shuttle-specific parameters, response fields, and API operations available through the Twilio Pay Connector. These apply to both IVR and Agent Assist integrations.

Request Parameters

Pass these parameters to customize payment processing. In IVR integrations, use <Parameter> elements within the <Pay> verb. In Agent Assist, include them as a JSON string in the parameter field.

Transaction Control

Customer Information

These parameters identify the customer and are stored against the Shuttle account.

account_first_name and account_last_name are combined and sent to the payment gateway as the cardholder name.

Billing Address

The cardholder's billing address. These are the only parameters passed to the payment gateway for AVS (address verification) checks.

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/payment_complete"
  chargeAmount="49.99">
  <Parameter name="account_first_name" value="Jane"/>
  <Parameter name="account_last_name" value="Doe"/>
  <Parameter name="billing_line1" value="123 Main Street"/>
  <Parameter name="billing_line2" value="Apt 4B"/>
  <Parameter name="billing_line4" value="Springfield"/>
  <Parameter name="billing_line5" value="62704"/>
  <Parameter name="billing_line6" value="IL"/>
  <Parameter name="billing_country" value="US"/>
</Pay>

Parameter names are case sensitive. Use lowercase exactly as shown above. Billing_Line1 or BILLING_LINE1 are ignored.

A billing address is not the same as an account address. Shuttle stores an address against the customer's account separately from the billing address on a payment. An account address is only used to pre-fill address fields on later checkouts and payment links for that customer - it is never sent to the payment gateway and is never used for AVS. If you need the gateway to receive an address, you must pass it as billing_* on the payment itself. There is no account address parameter on the Pay Connector.

If your <Pay> verb collects a postal code from the caller (postalCode="true"), that value takes precedence over billing_line5.

Payment Reference

Recurring Payments

ACH-Specific

Response Fields

These fields are returned in the action callback (IVR) or statusCallback webhook (Agent Assist).

Twilio Fields

Shuttle Fields

Card Fields

ACH Fields

Payment Status Values

Check PayConnector_payment_status to determine the transaction outcome:

Important: Always check PayConnector_payment_status. Twilio may return Result: "success" even when the payment failed or credentials are invalid.

Decline Types

The PayConnector_gateway_status field provides specific decline reasons:

Example Responses

Successful Card Payment (with save_card)

{
  "Result": "success",
  "PaymentConfirmationCode": "pay_31660_10007",
  "PayConnector_account": "acc_20648_10002",
  "PayConnector_contract": "co_20648_10002",
  "PayConnector_gateway_reference": "pay_56242536421653621",
  "PayConnector_gateway_status": "APPROVED",
  "PayConnector_gateway_token": "tok_1234567890abcdef",
  "PayConnector_payment_method": "pm_20648_10002",
  "PayConnector_payment_status": "SUCCESS",
  "PayConnector_reference": "REF-00010002",
  "PayConnector_transaction": "tr_20648_10002",
  "PaymentCardNumber": "xxxxxxxxxxxx4242",
  "PaymentCardType": "visa",
  "ExpirationDate": "1223"
}

Successful Tokenization

{
  "Result": "success",
  "PaymentToken": "pm_20648_10003",
  "PayConnector_account": "acc_20648_10003",
  "PayConnector_gateway": "gw_31660_10002",
  "PayConnector_gateway_token": "tok_9876543210fedcba",
  "PayConnector_payment_method": "pm_20648_10003",
  "PaymentCardNumber": "xxxxxxxxxxxx4242",
  "PaymentCardType": "visa",
  "ExpirationDate": "1225"
}

Successful ACH Payment

{
  "Result": "success",
  "PaymentConfirmationCode": "pay_31660_10007",
  "PayConnector_gateway_reference": "pay_56242536421653621",
  "PayConnector_gateway_status": "APPROVED",
  "PayConnector_payment_status": "SUCCESS",
  "PaymentMethod": "ach-debit",
  "BankAccountType": "consumer-checking",
  "BankRoutingNumber": "110000000",
  "BankAccountNumber": "xxxxxxxxxx89"
}

Declined Payment

{
  "Result": "payment-connector-error",
  "PayErrorCode": "64008",
  "PaymentError": "Payment Gateway rejected charge creation.",
  "PayConnector_gateway_status": "DECLINED",
  "PayConnector_gateway_message": "Invalid CVC",
  "PayConnector_payment_status": "DECLINED",
  "PayConnector_reference": "BOLT-00010004",
  "PaymentCardNumber": "xxxxxxxxxxxx4242",
  "PaymentCardType": "visa"
}

Invalid Credentials (Silent Failure)

Warning: Twilio returns this as "success" with no Shuttle data. Always verify PayConnector_payment_status exists.

{
  "Result": "success",
  "PaymentConfirmationCode": "",
  "PaymentToken": "",
  "PaymentCardNumber": "xxxxxxxxxxxx4242",
  "PaymentCardType": "visa"
}

Webhooks

Configure webhooks in your Shuttle instance settings for reliable payment tracking. Essential for:

• Disconnected calls during payment
• Gateway timeouts
• Held transactions requiring review
• Scheduled/recurring payment updates

Webhook Events

Each webhook contains reference IDs. Use the API to retrieve full details.

Shuttle API

Use the Shuttle API for post-payment operations like refunds, captures, and charging saved cards.

Authentication

Base URL: https://api.shuttleglobal.com/c/api/instances/{instance_key}
Header: Authorization: Basic {your_api_key}

Find credentials in the merchant portal under your application > Settings.

Operations

Retrieve Payment

GET /payments/{payment_id}

Refund

POST /payments/{payment_id}/refund
{"amount": "19.99"}

Capture Authorization

POST /payments/{payment_id}/capture
{"amount": "99.99"}

Void Authorization

POST /payments/{payment_id}/void

Charge Saved Card

POST /payments
{
  "payment_method_id": "pm_20648_10002",
  "amount": "49.99",
  "currency": "USD"
}

Update Recurring Schedule

PUT /contracts/{contract_id}
{"amount": "29.99"}

Cancel Recurring

POST /contracts/{contract_id}/cancel

Best Practices

1. Always use alt_key - Include your internal reference for reconciliation
2. Include customer data - Use account_* parameters for better tracking, and billing_* if your gateway performs AVS checks
3. Check PayConnector_payment_status - Don't rely on Twilio's Result field
4. Configure webhooks - Essential for reliable payment tracking
5. Use metadata - Pass business context through metadata_* parameters
6. Handle all statuses - Implement flows for pending, declined, and error states

Troubleshooting

"Invalid credentials" with Result: success

• Verify PayConnector_payment_status exists in response
• Check your instance key and secret key in connector config

Postal code errors

• Set postalCode="false" for non-US/CA customers
• Or pass known postal codes directly: postalCode="12345"

Billing address not reaching the gateway

• Check the parameter names are billing_*, lowercase. Account parameters (account_*) do not carry an address and unrecognised parameter names are silently ignored
• On Adyen, pass billing_line1, billing_line2, billing_line4, billing_line5 and billing_country together. If any one of them is missing, no address is sent at all
• Include billing_line6 for US, Canadian and Brazilian addresses - the state or province is required for AVS in those countries

ACH failures

• Always include AVSName parameter
• Ensure customer name matches bank account holder

Slow gateway responses

• Configure <Prompt for="payment-processing"> messages (IVR)
• Implement webhook handlers for async results