Creating a payment

POST /payments creates one payment or a batch of them from an account to saved payees. It returns 202 Accepted: the payments have been submitted, not necessarily sent. Approval policies and name checks happen after this call.

The request

Two things are required on every call:

1. An x-idempotent-key header containing a UUID v4 you generated. See Idempotency and safe retries.
2. A JSON body that is either a single payment object or an array of them.

curl -X POST 'https://customer-api.prod.xace.io/payments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotent-key: 6f1c2d8e-4b3a-4c9d-9e2f-1a2b3c4d5e6f' \
  -d '{
    "xaid": "11afa99b-9111-4111-8dab-f089295c1111",
    "payeeId": "c214543f-831c-4140-8315-c285bafc9233",
    "amount": "1250.00",
    "reference": "AFF-2026-09 Acme",
    "purpose": "SupplierPayment",
    "purposeCategory": "SupplierPayment"
  }'

Field rules

Send amount as a string. Sending a number is the most common 400 on this endpoint.

The response

{
  "status": "accepted",
  "message": "1 submitted, 0 rejected",
  "submittedCount": 1,
  "rejectedCount": 0,
  "requestId": "…",
  "submitted": [ { "xtid": "…", "xaid": "…", "payeeId": "…", "amount": "1250.00", "reference": "AFF-2026-09 Acme" } ],
  "rejected": []
}

Store requestId and every xtid. The xtid is how you track the payment through approval and into transactions.

Batches

Send an array to submit many payments in one call. Each item is validated on its own: valid items are submitted, invalid ones come back in rejected with an error. A batch with three good lines and one bad one returns 202 with rejectedCount: 1. Handle the rejected list; do not resubmit the whole batch.

What happens next

1. If an approval policy applies to API-created payments on that account, an approval request is created and the payment waits. See Tracking a payment through approval.
2. Once approved, or immediately if no policy applies, the payment is sent on the appropriate rail.
3. It appears in GET /account/{xaid}/transactions with its xtid, and a TransactionConfirmed webhook fires if you are subscribed.