POST /api/v1/orders/{order}/pay

Request

Field	In	Rule
`order`	Path parameter	Required numeric ID owned by the authenticated customer. Foreign and missing IDs return 404.
`gateway`	JSON body	Required registered gateway ID string; max 40.
`return_url, cancel_url`	JSON body	Required URLs; max 500 each. Origins must be allowed by the installation; credentials and fragments are rejected.
`idempotency_key`	JSON body	Nullable string; max 64. Keep separate from the checkout key.
`Idempotency-Key`	Header	Optional fallback only if idempotency_key is absent from the body.

cURL

curl --request POST "https://shop.example.test/api/v1/orders/$ORDER_ID/pay" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"gateway":"<registered-gateway-id>","return_url":"https://shop.example.test/payment-return","cancel_url":"https://shop.example.test/payment-cancel","idempotency_key":"example-payment-01"}'

Response200

Success: 200

Response shape (notation, not a captured response)

schema

{ data: { attempt_id: integer, status: string, redirect_url: string|null, payment_status: string|null } }

Full response schema

Common errors

HTTP status	Meaning
`401`	unauthenticated: missing or invalid authentication.
`403`	unauthorized, insufficient_scope or ip_not_allowed: check account context, required ability and token IP policy.
`404`	not_found: missing, inactive or foreign-owned resource.
`422`	validation_error: invalid input or unmet domain requirements. Payment initiation can also return payment_failed.
`429`	rate_limited: back off before retrying, especially writes.

Error envelope and global caveats

Start a gateway payment attempt

POST`/api/v1/orders/{order}/pay`

Success: 200

Common errors

Search documentation