Initiate a payment

Creates a payment between accounts using a supported payment rail.

POST/payments

Request

curl -X POST "<BASE_URL>/payments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "8d6907d9-f5db-47ed-a55d-f4a87e120d0c",
    "toAccountId": "16e4b355-a894-47c3-b21a-90a4218cf49c",
    "amountMinor": 2599,
    "currency": "USD",
    "rail": "internal"
  }'

Authorization

OAuth scope: payments.writeThe access token must carry this scope.
Action: initiatePayment

Headers

AuthorizationstringRequired
OAuth 2.0 client-credentials flow for machine workloads.
X-Request-IduuidOptional
UUID unique to this HTTP request. The gateway echoes a valid caller-supplied value or generates one when the header is omitted. The resulting value is returned in X-Request-Id and structured error responses.
Idempotency-KeystringRequired
Unique key that prevents duplicate payment creation during retries.
Content-TypestringRequired
Always application/json.

Request body

amountMinorintegerRequired
No description yet.
at least 1
currencystringRequired
No description yet.
pattern ^[A-Z]{3}$
fromAccountIduuidRequired
No description yet.
railenumRequired
Settlement route used to move funds between the source and destination accounts.
Allowed values
- ach
- sepa
- swift
- card
- internal
toAccountIduuidRequired
No description yet.

Response

Status 201. Payment created successfully.

amountMinorintegerRequired
No description yet.
at least 1
currencystringRequired
No description yet.
pattern ^[A-Z]{3}$
fromAccountIduuidRequired
No description yet.
iduuidRequired
No description yet.
railenumRequired
Settlement route used to move funds between the source and destination accounts.
Allowed values
- ach
- sepa
- swift
- card
- internal
toAccountIduuidRequired
No description yet.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400INVALID_ARGUMENTThe request is malformed.
401UNAUTHENTICATEDAuthentication failed.
403PERMISSION_DENIEDThe principal is not authorized for this operation.
409ALREADY_EXISTSThe resource or idempotency key conflicts with existing state.
422FAILED_PRECONDITIONA business precondition prevents the operation.
429RESOURCE_EXHAUSTEDA rate or concurrency limit was exceeded.
503UNAVAILABLEThe service is temporarily unavailable.