The Payments API is the core of Shuttle — it creates payments, sets up recurring billing, and handles authorisations.
Creating a Payment
A payment request creates a contract and attempts the transaction in a single call. The response includes the payment, contract, and transaction details. Unless rejected prior to processing (e.g., validation failure), the API will return a result — either SUCCESS or DECLINED.
Actions
PAYMENT(default): charges the customer immediatelyAUTH: reserves funds without collecting them. You then capture or void the authorisation
3D Secure
If the gateway requires 3D Secure authentication, the response will include a redirect_url. Redirect the customer to this URL to complete authentication, then they'll be returned to your success_url or cancel_url. For hosted checkouts, 3DS is handled automatically.
Recurring Payments
Set frequency to any value other than ONEOFF to create a recurring payment. Shuttle will automatically generate charges and attempt payments on schedule. See Contracts for retry logic and management.
Status
| Status | Description |
|---|---|
SUCCESS | Payment was approved |
PENDING | Payment is still being processed. Some gateways (e.g., GoCardless) take days to confirm |
DECLINED | Payment was declined — see gateway_status for the reason |
REQAUTH | Payment requires an authorisation step (e.g., 3D Secure) that hasn't completed. Treat as abandoned after 1 hour |
INVALID_PAYMENT_METHOD | Payment attempted with an invalid or disconnected payment method |
UNRESOLVED | No conclusive result from the gateway. Do not retry — contact support |
UNATTRIBUTED | Payment succeeded but had an internal recording issue. Resolves to SUCCESS within hours |
Gateway Status
The gateway_status field categorises the processor's response:
| Status | Action |
|---|---|
APPROVED | Payment approved |
PENDING | Still processing |
DECLINED | User input issue — check details and retry |
DECLINED_CALL_BANK | Account issue (e.g., insufficient funds) — contact bank |
DECLINED_BLOCKED | Card stopped/blocked — try a different card |
DECLINED_ERROR | Technical issue (e.g., invalid merchant credentials) — contact support |
DECLINED_RETRY | Temporary issue (e.g., rate limit) — retry after a few seconds |
CANCELLED | Payment was pending but has since been withdrawn |
UNRESOLVED | No conclusive result — do not retry |
MANUAL | Payment was recorded manually, not processed via gateway |