Transfers can fail for different reasons, and each kind of failure needs a different response. This guide shows you how to decide what to do on your backend, what the account holder sees in the SDK, and how to handle timeouts and duplicates safely.

Before you begin

Before you start, make sure you have the following in place:

• Submit transfers from your backend. See Your backend's responsibilities.

Four kinds of failure

Most errors fall into one of four kinds. Use the kind to decide your next step.

For the specific codes, see Error codes.

Timeouts

Creating a transfer with Create Transfer usually takes 4-5 seconds. If it runs longer than 60 seconds, the API returns 504 Gateway Timeout. The response is an error, but the transfer is still being processed and may still go through, so don't treat it as a failure.

Instead, check the transfer's progress with Get Transfer Progress by Quote History ID (GET /v1/transfers/progress/{quoteHistoryId}). Use the same quoteHistoryId from the SDK payload that you sent to Create Transfer.

curl --request GET \
     --url https://sandbox-api.readyremit.com/v1/transfers/progress/464be703-ef4b-4aec-bc3b-fa49ef9ad44d \
     --header 'accept: application/json'

The response has two properties, transferId and transferRecordStatus:

{
  "transferId": null,
  "transferRecordStatus": "Initializing"
}

transferId stays null until the transfer is created. transferRecordStatus is one of:

• NotInProgress: transfer creation hasn't started, usually because Create Transfer wasn't called.
• Initializing: transfer creation is in progress.
• Failed: the transfer failed while being initialized. Create a new transfer.
• Completed: the transfer was initiated.

After a 504 Gateway Timeout, poll once per second for 60 seconds, or until the status is Failed or Completed.

🚧

Note

Completed means the transfer was initiated in PayMitto, not that funds were delivered. Use this endpoint only after a timeout. Once you have a transferId, get the transfer's actual status from Get Transfer or the Transfer status updates webhook.

Duplicates

Each quote can be used for one transfer. If you send Create Transfer again with the same quoteHistoryId, the API returns TransferDuplicatedByQuote. This protects the account holder from being charged twice, so check progress rather than resubmitting after a timeout.

What the account holder sees

When your backend can't create the transfer, call window.rremit.failed(error) with a code and message. See the Snippet API reference.

The Web SDK returns the account holder to the Review transfer screen and shows an inline banner with a reference code. From there they can go Back to change details, or select Send transfer to try again. For some errors, such as a duplicate transfer, the SDK shows a general message instead of the one you pass.

Keep your messages short and written for the account holder, and log the reference code so your support team can match it to your backend logs.

After a transfer is created

Once you have a transferId, a transfer can still fail or be canceled later. Track it with transfer status updates, and trigger refunds from the status event rather than from the Create Transfer response.

Next steps

Once you've finished here, these pages are good places to go next:

• Error codes: every code, its cause, and how to resolve it.
• Test case simulation: trigger these errors in the Sandbox.
• Go-live checklist: everything to confirm before production.