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 immediately
AUTH: 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