Payments

Payments and capture

How payments attach to orders, when to use manual capture, and how to capture all or part of an authorised amount.

A payment is one attempt to collect money for an order. When the shopper confirms checkout, International Orders creates a payment, routes it to a local acquirer where one is available, and reports the result.

This is preview documentation for a prototype. Endpoints, fields and keys are illustrative.

How payments relate to orders

An order can have several payments if earlier attempts fail. Only one payment can succeed. The order's latest_payment field always points to the most recent attempt.

Payment status	Meaning
`processing`	Submitted to the network, waiting for a response
`requires_action`	The shopper must authenticate, for example with 3-D Secure
`authorized`	Funds are held on the shopper's account
`captured`	Funds are collected and will settle to you
`failed`	Declined or abandoned. The shopper can try again

Automatic and manual capture

By default, orders use capture_method: "automatic". The payment is authorised and captured in one step, and the order moves straight to paid.

Use manual capture when you only want to collect money once you know you can ship, for example for made-to-order goods or when stock is uncertain.

curl https://api.international-orders.com/v1/orders \
  -u sk_test_51Hx...: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "amount": 8400,
    "capture_method": "manual",
    "shipping": { "country": "GB" }
  }'

When the shopper confirms, the order moves to authorized and you receive a payment.authorized event.

Capture a payment

Capture the order when you're ready to ship:

curl -X POST https://api.international-orders.com/v1/orders/ord_7Hc2kQ9xL4mP/capture \
  -u sk_test_51Hx...: \
  -H "Idempotency-Key: capture-ord_7Hc2kQ9xL4mP"

{
  "id": "pay_3Jd8nT2wK6rV",
  "object": "payment",
  "order": "ord_7Hc2kQ9xL4mP",
  "status": "captured",
  "amount": 8400,
  "amount_captured": 8400,
  "currency": "GBP",
  "method": { "type": "card", "brand": "visa", "last4": "4242", "country": "GB" },
  "captured_at": "2026-10-01T10:02:51Z"
}

Partial capture

If you can only ship part of the order, pass amount to capture less than was authorised. The remainder is released to the shopper automatically.

curl -X POST https://api.international-orders.com/v1/orders/ord_7Hc2kQ9xL4mP/capture \
  -u sk_test_51Hx...: \
  -d amount=5200

You can capture once per payment. To ship in several parts, create a separate order for each shipment.

Authorisation windows

An authorisation doesn't last forever. If you don't capture in time, the hold expires and the order returns to requires_payment.

Method	Typical hold
Cards (most networks)	7 days
Cards, some travel and lodging merchants	Up to 30 days
Wallets backed by cards	Same as the underlying card
Bank transfers and vouchers	Manual capture not supported

We send a payment.authorization_expiring reminder 24 hours before a hold expires.

Failed payments

When a payment fails, you receive payment.failed with a failure_code, such as card_declined or insufficient_funds. The order stays in requires_payment and the shopper can try again with the same client_secret. Show them the failure_message, which is written for shoppers and localised to their language.

You can trigger every outcome with test cards.