# 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 a

This reference covers the Shuttle-specific parameters, response fields and API operations available through the Shuttle Pay connector. These apply to both [IVR](/merchants/twilio/integration-guide/) and [Agent Assist](/merchants/twilio/agent-assist-guide/) 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`) |

```xml
<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 |

```xml
<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)

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

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

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

```json
{
  "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.

```json
{
  "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](/merchants/reference/webhooks/). For every event, see the [webhook events reference](/merchants/reference/webhook-events/).

## 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](/platforms/reference/authentication/). A merchant integrating its own account: see [Authentication for merchants](/merchants/reference/api-keys/).

### Operations

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

**Retrieve a payment** ([reference](/merchants/reference/operations/getpayment/))
```
GET /payments/{payment_id}
```

**Refund a payment** ([reference](/merchants/reference/operations/refundpayment/)). `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](/merchants/reference/operations/capturepayment/)). Leave out `amount` to capture the full authorised amount.
```
POST /payments/{payment_id}/capture
{"amount": "99.99"}
```

**Void an authorisation** ([reference](/merchants/reference/operations/voidpayment/))
```
POST /payments/{payment_id}/void
```

**Charge a saved card** ([reference](/merchants/reference/operations/createpayment/)), 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](/merchants/reference/operations/updatecontract/)). 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](/merchants/reference/operations/cancelcontract/)). 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