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

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
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"

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