SWIFT Payouts

The Payout using SWIFT solution provides services to send USD from a Cobre Balance to a beneficiary with a bank account outside the United States, using the SWIFT network. Payouts are executed automatically, without a manual step by the Cobre Ops team.

📘 For a product overview, see SWIFT Payouts.

SWIFT payouts use the same Counterparty and Money Movement model as every other payout, so they are created, tracked, and reconciled the same way as the rest of your payouts.

SWIFT limitations and routing behavior

Payouts using the SWIFT rail are subject to the following conditions:

Currency: USD is the only supported currency.

Destination countries: beneficiaries in any country can receive SWIFT payouts.

Minimum amount: the minimum amount allowed per transaction is USD 1.00.

The speed of a SWIFT payout depends on the beneficiary's bank and any intermediary banks involved.

If a Payout cannot be processed through SWIFT, Cobre will not automatically reroute the transaction. In such cases, the Money Movement transitions to the final failed status and funds are returned to your Cobre Balance.

We recommend validating the beneficiary's bank details, especially the BIC and account number, before submission to avoid failed transactions.

Supported counterparties

Payout via SWIFT supports the following destination types:

Destination Type	Counterparty Type	Rails
Business bank account anywhere in the world	`business`	`swift`

The Counterparty must have type set to business and rail set to swift in counterparty_bank_details. The geo field is the beneficiary's country and accepts any ISO 3166-1 alpha-3 country code (for example, col or usa). In addition to the beneficiary's identification and address, the Counterparty carries the details of the beneficiary's bank:

Field	Description
`metadata.counterparty_bank_details.rail`	Payment rail. Must be `swift`.
`metadata.counterparty_bank_details.bic`	SWIFT/BIC code of the beneficiary's bank. Required.
`metadata.counterparty_bank_details.account_number`	Beneficiary's account number.
`metadata.counterparty_bank_details.routing_number`	Routing number of the beneficiary's bank. Required; it can be an empty string.
`metadata.counterparty_bank_details.bank_name`	Name of the beneficiary's bank.
`metadata.counterparty_bank_details.bank_address`	Address of the beneficiary's bank (`street_line1`, `city`, `state`, `postal_code`, `country`).
`metadata.counterparty_bank_details.currency`	Payout currency. Only `USD` is supported.
`metadata.counterparty_address`	Address of the beneficiary (`street_line1`, `street_line2`, `city`, `state`, `postal_code`, `country`).
`metadata.counterparty_fullname`	Full name of the beneficiary.
`metadata.counterparty_id_type` and `metadata.counterparty_id_number`	Type and number of the beneficiary's identification.
`metadata.counterparty_incorporation_country`	Country where the beneficiary is incorporated.

See Managing Counterparties for the full field reference.

Supported providers

Cobre Balance Type	Provider ID	Rails
Cobre Balance USA	`pr_usa_cobre`	SWIFT

Valid source and destination combination

Source	Source type	Destination	Destination type
account_id	Cobre Balance with provider `pr_usa_cobre`	counterparty_id	Counterparty (geo: any ISO 3166-1 alpha-3 country code, type: `business`, rail: `swift`)

Money Movement type and metadata

Money Movements sent through this rail have type set to swift and currency set to usd.

Metadata field	Description
`description`	Description of the payout.
`category`	Category associated with the Money Movement. It can be left empty.
`swift_uetr`	Unique End-to-end Transaction Reference (UETR) of the SWIFT payment. It is not present when the Money Movement is created. It is returned in the Money Movement metadata and can be shared with the beneficiary's bank to trace the payment on the SWIFT network.

Authorization Workflow (optional)

Checker Approval is an optional solution that can be used within the Payout flow. It triggers an authorization workflow before the transaction is sent to the payment network. While approval is pending, the Money Movement remains in a pending_approval status until it is either approved or rejected. The approval process can be completed either through the Cobre Portal or programmatically via API.

Payout lifecycle

A Payout through SWIFT follows a simple lifecycle:

1. Create a beneficiary Counterparty
Create a counterparty of type business using the beneficiary's bank account information, including the BIC and account number, with the rail set to swift.

2. Create a Money Movement
Create a Money Movement using:

The account_id from which the funds will be debited, used as the source_id. The account must use the pr_usa_cobre provider.

The counterparty_id from the previous step as the destination_id. The counterparty must have type set to Business and rail set to swift, and its geography can be any ISO 3166-1 alpha-3 country code.

The metadata with a description, and optionally a category.

The external_id where you can send a reference from your system.

The amount provided in the smallest unit of the currency (e.g., $100.00 USD should be represented as 10000).

The checker_approval as true if you want to use our authorization flow.

3. Money Movement is processed
Once created, the Money Movement starts in the initiated status.

If all validations pass, the status changes to processing. At this point, the transaction is submitted automatically to the SWIFT network.

If an error occurs during validation or processing, the Money Movement transitions to the final failed status.

If the Money Movement is created with checker_approval = true, it first moves to the pending_approval status and will only transition to processing or canceled once the approval decision is made.

4. Funds are debited
Once the Money Movement transitions to the processing status, the funds are debited from the associated Cobre Balance and a swift_debit transaction is created.

5. Wait for the final outcome of the Money Movement.
The final status of a SWIFT Payout is either completed or failed.

If the Money Movement is completed, the beneficiary has successfully received the funds. Use the swift_uetr in the metadata to trace the payment with the beneficiary's bank.

If the Money Movement is failed, the funds are credited back to your Cobre Balance.

6. Receive status updates
Money Movement status changes are communicated via Webhooks.

Money Movement Idempotency

Money Movement creation supports idempotency.

Idempotency keys are valid for 24 hours.

Allowed Actions on SWIFT Payouts

🔑 Create

🔍 Retrieval

Description: Money Movement Creation.
What to expect after the action: Money Movement is created in Cobre in initiated status.
📘 Learn more:

🔗 Create a Money Movement

How to Get Started

Before you begin, we recommend reviewing the following considerations.

You need a funded Cobre Balance

To send funds using SWIFT, you must have an active Cobre Balance in the United States (provider pr_usa_cobre) with sufficient USD funds.

Create the beneficiary Counterparty

Before creating a Payout Money Movement, you must create a Counterparty with the beneficiary's bank account information, including the BIC and account number, with the rail set to swift. See Create a Counterparty.

Define the Payout configuration

Decide the amount (minimum USD 1.00), the description and optional category metadata, and whether the payout requires Checker Approval.

Implement Webhooks to track payment status

To stay informed about the status of Payout transactions, we strongly recommend implementing Webhooks. Webhooks notify your system when a payment is initiated, processed, completed, or failed. Also subscribe to the required events to receive notifications about transaction debits and credits.

See Notifications & Subscriptions for more details.

What to expect after using this API

Initiate the Payout

Once the Money Movement creation request is sent, it will be created with an initiated status.
Make sure your system is prepared to receive status updates as the Money Movement progresses through its lifecycle.

Track the transaction status

Monitor the Payout lifecycle using Webhooks or retrieval endpoints. The debit from your Cobre Balance is recorded as a swift_debit transaction, which you can retrieve through the Transactions endpoints and Cobre reports. Use the money_movement_id in the transaction metadata to link it to the SWIFT Money Movement.

Funds are delivered to the beneficiary

When the Payout is successful, funds are credited to the beneficiary's bank account abroad and the Money Movement status is updated to completed. If the Payout cannot be delivered, the status is updated to failed and the funds are returned to your Cobre Balance. Delivery time depends on the beneficiary's bank and any intermediary banks involved.

SWIFT Payouts

SWIFT limitations and routing behavior#

Supported counterparties#

Supported providers#

Valid source and destination combination#

Money Movement type and metadata#

Authorization Workflow (optional)#

Payout lifecycle#

Money Movement Idempotency#

Allowed Actions on SWIFT Payouts#

How to Get Started#

What to expect after using this API#