Shuttle Pay connector reference

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

Request parameters

Pass these parameters to customise 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

Parameter	Description	Values
action	Transaction type	AUTH (pre-authorisation), PAYMENT (capture funds)
save_card	Save the card for future use	true, false

Customer information

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

Parameter	Description
account_crm_key	Your customer identifier
account_first_name	Customer first name
account_last_name	Customer last name
account_email	Customer email
account_phone	Customer phone

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.

Parameter	Description
billing_line1	Street address
billing_line2	Address line 2 (apartment, unit, house name or number)
billing_line3	Address line 3
billing_line4	City / town
billing_line5	ZIP / postcode
billing_line6	State / province, as an ISO 3166-2 subdivision code (e.g. CA for California)
billing_country	Country, as an ISO 3166-1 alpha-2 code (e.g. US)

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/payment_complete"
  chargeAmount="49.99"
  timeout="30"
  maxAttempts="3">
  <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 them exactly as shown: Billing_Line1 or BILLING_LINE1 is ignored. The only exceptions are AVSName, and on Telnyx currency and bank_account_type, which are matched whatever their case.

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 Shuttle Pay connector.

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

Payment reference

Parameter	Description
alt_key	Your payment reference ID (invoice number, order ID, etc.)
payment_method_code	Unique payment method identifier
metadata_{key}	Custom metadata fields (e.g., metadata_plan, metadata_source)

Recurring payments

Parameter	Description	Format
scheduled_date	Schedule payment for later	YYYY-MM-DDTHH:MI:SS
frequency	Recurring interval	MONTHLY, FORTNIGHTLY, WEEKLY
occurrences	Number of recurring payments	Integer
start_date	First instalment date	YYYY-MM-DDTHH:MI:SS

ACH-specific

ACH payments need both of these parameters. Without bank_account_type the payment is rejected before it reaches your gateway.

Parameter	Description
bank_account_type	The type of bank account: checking, savings or businessChecking
AVSName	Account holder name

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/payment_complete"
  chargeAmount="49.99"
  paymentMethod="ach-debit"
  timeout="30"
  maxAttempts="3">
  <Parameter name="bank_account_type" value="checking"/>
  <Parameter name="AVSName" value="John Smith"/>
</Pay>

Response fields

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

Twilio fields

Field	Description
Result	Twilio status code
PayErrorCode	Twilio error code if applicable
PaymentError	Error message or decline reason
PaymentConfirmationCode	Shuttle payment ID
PaymentToken	Shuttle payment method ID (tokenisation)

Shuttle fields

Field	Description
PayConnector_payment_status	Primary status - always check this
PayConnector_gateway_status	Gateway response (APPROVED, DECLINED, etc.)
PayConnector_gateway_message	Detailed gateway message
PayConnector_reference	Shuttle’s reference for the payment (for example REF-00010002). This is not your alt_key
PayConnector_gateway_reference	Gateway transaction ID
PayConnector_gateway_token	Gateway token for saved card
PayConnector_account	Shuttle account ID
PayConnector_contract	Recurring contract ID
PayConnector_charge	Shuttle charge ID: the contract’s most recent charge
PayConnector_payment_method	Saved payment method ID
PayConnector_transaction	Shuttle transaction ID
PayConnector_gateway	Gateway identifier
PayConnector_auth_expires	When the authorisation expires, for an AUTH payment
PayConnector_nonce	Twilio’s transaction_id for the connector request, which Shuttle uses as the payment’s idempotency key. Returned on every response, errors included

Card fields

Field	Description
PaymentCardNumber	Masked card number
PaymentCardType	Card brand (visa, mastercard, etc.)
ExpirationDate	Card expiry (MMYY format)
SecurityCode	Masked CVV
PaymentCardPostalCode	AVS postal code

ACH fields

Field	Description
PaymentMethod	ach-debit for ACH payments
BankAccountType	Account type (consumer-checking, etc.)
BankRoutingNumber	Bank routing number
BankAccountNumber	Masked account number

Payment status values

Check PayConnector_payment_status to determine the transaction outcome:

Status	Meaning	Action
SUCCESS	Payment completed	Provision service
UNATTRIBUTED	Payment completed (legacy)	Provision service
PENDING	Processing	Await webhook
UNRESOLVED	Requires review	Await webhook
DECLINED	Payment failed	Retry or cancel
REQAUTH	Authentication required	Retry

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:

Status	Meaning	Customer action
DECLINED	Generic decline	Check details and retry
DECLINED_CALL_BANK	Bank intervention needed	Contact bank (e.g., insufficient funds)
DECLINED_BLOCKED	Card blocked	Try different card
DECLINED_ERROR	Technical issue	Contact support
DECLINED_RETRY	Temporary failure	Retry later

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_charge": "cg_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",
  "PayConnector_nonce": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "PaymentCardNumber": "xxxxxxxxxxxx4242",
  "PaymentCardType": "visa",
  "ExpirationDate": "1223"
}

Successful tokenisation

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

Shuttle webhooks give you reliable payment tracking, separately from the carrier’s callbacks. They are essential for:

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

Webhook events

Event	Description
PAYMENT.SUCCESS	Payment completed
PAYMENT.FAILED	Payment declined or failed
CAPTURE.SUCCESS	Authorisation captured
CAPTURE.FAILED	Capture failed
REFUND.SUCCESS	Refund processed

Each webhook contains reference IDs. Use the API to retrieve full details. For setting up webhooks, and for retries (by default a webhook that fails isn’t retried: you set retries on the webhook target), see Webhooks. For every event, see the webhook events reference.

Shuttle API

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

Authentication

Base URL: https://app.shuttleglobal.com/c/api/instances/{instance_key}

Use HTTP Basic authentication with your secret key as the username and a blank password. A platform finds its API keys on its application’s Developer tab: see Authentication for platforms. A merchant integrating its own account: see Authentication for merchants.

Operations

{payment_id} is the Shuttle payment ID, returned as PaymentConfirmationCode.

Retrieve a payment (reference)

GET /payments/{payment_id}

Refund a payment (reference). reason is required; leave out amount to refund everything not yet refunded.

POST /payments/{payment_id}/refund
{"refund": {"amount": "19.99", "reason": "Customer request"}}

Capture an authorisation (reference). Leave out amount to capture the full authorised amount.

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

Void an authorisation (reference)

POST /payments/{payment_id}/void

Charge a saved card (reference), using the Shuttle payment method ID from PayConnector_payment_method

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

Update a recurring payment (reference). Changing amount replaces the contract with a new one: see the reference for what each field does.

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

Cancel a recurring payment (reference). The body takes the optional write_off, cancel_retries and strict flags.

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

• Result: payment-connector-error with no PayConnector_payment_status and no transaction in Shuttle usually means bank_account_type is missing or not one of checking, savings or businessChecking
• Always include bank_account_type and AVSName parameters
• Ensure customer name matches bank account holder

Slow gateway responses

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