A successful response can carry a warnings array next to data. A warning never changes the result of the request; log it and act on it if you want. It has the same code, message and param fields as an error, without type. warnings is only present when there is at least one.
"message": "An existing payer with this bank account was used. Its stored account name differs from the one sent and was kept; it is used for payment matching.",
"param": "payer.accountName"
}
],
"requestId": "req_..."
}
code
Returned by
Meaning
payer_name_differs
POST /v1/payins, POST /v1/payouts with an inline payer
An existing payer with the same bank and account number was used, and its stored name (param: payer.accountName) or English name (payer.accountNameEn) differs from the one you sent. The stored name was kept because it is used to match transfers; change it with PATCH /v1/payers/{id} if needed
If POST /v1/payins, POST /v1/payouts or POST /v1/withdrawals times out, you do not know whether it was created. Send an Idempotency-Key header with every create so you can simply send it again:
Use a new unique key (for example a UUID) for each payment, and the same key when you retry that payment. Keys are 8-255 characters of A-Z a-z 0-9 _ - : ..
A retry with the same key and the same request within 24 hours returns the original response with the header Idempotent-Replayed: true; nothing is created again.
The same key with a different request (another body or query string) returns 422 idempotency_key_reused.
While the first request is still running, a retry returns 409 idempotency_request_in_progress. Wait a moment and retry.
If the first request failed with an error, the key is released and the retry runs as a new request.
The header is optional. Without it, search by reference before sending again, e.g. GET /v1/payouts?reference=withdraw-20001, and use a unique reference for every payment.
