Overview Coming Soon
International payments are coming soon. This preview gives you an early look at the expected experience so you can begin planning your integration.
As we prepare for launch, API fields, scopes, statuses, webhook events, and other details may evolve. Review the final documentation before moving your integration to production.
International payments let your end-users move USD from their Unit bank account to recipients in 100+ countries, delivered in the destination currency via the SWIFT network.
The flow:
- Save a counterparty
- Create a quote
- Submit a payment
Available for business and sole proprietorship customers.
See the API, Webhook Events, and Resources pages for endpoint details, event payloads, and JSON:API schemas.
International Counterparties
An international counterparty is the recipient of an international payment.
You must create a counterparty in order to send a payment.
Counterparty is created under a Customer.
You can create multiple counterparties and reuse them across payments.
More counterparty types will follow as we add international payment rails.
See Create SWIFT Counterparty and SWIFT Counterparty for the full schema.
Quotes
A quote locks in the amounts, fees, and exchange rate (for non-USD currencies) of an international payment.
Create the payment with the quote to apply its terms. Each quote can be used once.
See Create Quote and Get Quote in the API reference, and Quote Statuses for statuses and expiry.
International Payments
An international payment is a transfer of funds to a recipient in another country.
To initiate an international payment, an unused, non-expired quote is required.
See International Payment for the full attribute schema and example payload.
Foreign currency quotes expire 15 minutes after creation.
If you create a payment after the quote's expiresAt, the payment will be rejected with QuoteExpired.
Quote Statuses
When you create a quote, it will be created with a New status. Quotes are single-use — once used to create a payment, they cannot be reused.
| Status | Description |
|---|---|
New | The quote was created and is available to use. |
Used | The quote was used by a payment. |
Expired | The quote expired and cannot be used to create a payment. |
International Payment Statuses
When you create an international payment, it will be created with a Pending status. You may track a payment's progress using the status attribute or listening to relevant webhooks, such as payment.sent.
The possible status values are listed below and you should be prepared to receive all statuses:
| Status | Description |
|---|---|
Pending | The payment was created on the Unit ledger and the source account was debited. The payment is being processed. |
PendingReview | The payment is pending review. Additional information is required before it can continue processing. |
Rejected | The payment was rejected and reason is populated (see Rejections & Returns for more details). |
Sent | The payment was sent to the counterparty's bank. This is the final state for successful payments. |
Returned | The payment was sent but returned by the counterparty's bank and reason is populated (see Rejections & Returns for more details). |