Resources Coming Soon

Early preview

International payments are coming soon. This preview gives you an early look at the expected experience so you can begin planning your integration.

International Counterparty

An international counterparty is a counterparty resource with JSON:API type swiftCounterparty, created and managed through the /counterparties endpoints.

Attributes

Name	Type	Description
destinationCurrency	string	ISO (International Organization for Standardization) 4217 destination currency (e.g. `EUR`, `GBP`).
destinationCountry	string	ISO 3166-1 alpha-2 destination country code.
name	string	Full name of the recipient.
routing Required	object	Recipient routing details. See Routing.
accountType	string	Either `Individual` or `Corporate`.
address Required	object	Recipient International address. `countryCode` is required within the object.
email Optional	string	Recipient email address.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was last updated.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The end-customer who registered this counterparty.

Example international counterparty (swiftCounterparty) resource:
{
  "data": {
    "type": "swiftCounterparty",
    "id": "200",
    "attributes": {
      "destinationCurrency": "EUR",
      "destinationCountry": "DE",
      "name": "Hans Mueller",
      "routing": {
        "swift": {
          "bic": "COBADEFFXXX",
          "accountNumber": "DE89370400440532013000"
        }
      },
      "accountType": "Individual",
      "address": {
        "countryCode": "DE"
      },
      "tags": {
        "label": "EU supplier"
      },
      "createdAt": "2024-01-15T10:02:00.000Z",
      "updatedAt": "2024-01-15T10:02:00.000Z"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "1000"
        }
      }
    }
  }
}

Routing

routing groups the recipient's bank details by network. Only swift is supported today; more networks will follow as we add international payment rails.

Name	Type	Description
swift.bic	string	SWIFT (Society for Worldwide Interbank Financial Telecommunication) Bank Identifier Code (BIC) of the recipient's bank.
swift.accountNumber	string	Recipient bank account number or IBAN.

International address

address is required on counterparty create. Only countryCode is required within the object; other fields are optional.

Name	Type	Description
countryCode	string	ISO 3166-1 alpha-2 country code.
street Optional	string	First line of the address.
street2 Optional	string	Second line of the address.
city Optional	string	City.
state Optional	string	State or province. For US and CA addresses, two letters representing the state (US) or province (CA).
postalCode Optional	string	Postal code.

Quote

Prerequisites

An International Counterparty must exist before a quote can be created.

A quote is a JSON resource with type quote that locks in the terms for a single international payment. When the payment involves currency conversion, the quote includes the applicable exchange rate.

Attributes

Name	Type	Description
status	string	One of `New`, `Used`, or `Expired`. See Quote Lifecycle.
sourceCurrency	string	ISO 4217 source currency. Always `USD`.
destinationCurrency	string	ISO 4217 destination currency code.
destinationAmount	integer	Amount to be received by the counterparty, in the destination currency's minor unit (e.g. cents for EUR).
exchangeRate	string	The FX rate applied (source currency per 1 destination currency). `"1"` for USD→USD quotes.
sourceAmount	integer	Amount in USD cents debited from the source account for the converted principal.
totalAmount	integer	Total amount debited from the source account in USD cents. Equals `sourceAmount`.
expiresAt Optional	RFC3339 Date string	For foreign-currency quotes, the timestamp after which the locked rate expires. Absent for USD→USD quotes.
createdAt	RFC3339 Date string	The date the resource was created.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The customer for whom the quote was created.
counterparty	JSON:API Relationship	The international counterparty that will receive the payment created from this quote.

Example quote resource:
{
  "data": {
    "type": "quote",
    "id": "300",
    "attributes": {
      "status": "New",
      "sourceCurrency": "USD",
      "destinationCurrency": "EUR",
      "destinationAmount": 10000,
      "exchangeRate": "1.085",
      "sourceAmount": 10850,
      "totalAmount": 10850,
      "expiresAt": "2024-01-15T10:20:00.000Z",
      "createdAt": "2024-01-15T10:05:00.000Z"
    },
    "relationships": {
      "counterparty": {
        "data": {
          "type": "swiftCounterparty",
          "id": "200"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "1000"
        }
      }
    }
  }
}

International Payment

Prerequisites

A non-expired Quote (status New) must exist before a payment can be submitted.

An international payment is a payment resource with type internationalPayment, created and managed through the /payments endpoints.

Attributes

Name	Type	Description
status	string	Payment status. One of `Pending`, `PendingReview`, `Initiated`, `Sent`, `Completed`, `Rejected`, `Returned`. A payment in `PendingReview` requires additional information before processing can continue; after the information is submitted, the status returns to `Pending`.
direction	string	Always `Debit` (funds leave the source account).
sourceAmount	integer	Amount debited from the source account in USD cents (equals the quote's `sourceAmount`).
sourceCurrency	string	ISO 4217 source currency. Always `USD`.
destinationAmount	integer	Amount received by the counterparty in the destination currency's minor unit.
destinationCurrency	string	ISO 4217 destination currency code.
destinationCountry	string	ISO 3166-1 alpha-2 destination country code. Returned on international payments; schema remains nullable for backward compatibility.
purpose	string	The purpose of the payment. See International Payment Purpose Code for possible values.
sourceOfFunds	string	Describes the origin of the funds. Example values: `Salary`, `PersonalSavings`, `PersonalWealth`, `RetirementFunds`, `BusinessOwner`, `LoanFacility`, `PersonalAccount`, `CorporateAccount`.
rejectionReason Optional	string	Present when `status` is `Rejected`. See Rejection reasons for possible values.
returnReason Optional	string	Present when `status` is `Returned`. See Return reasons for possible values.
description Optional	string	Payment description.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was last updated.

Relationships

Name	Type	Description
account	JSON:API Relationship	The source deposit account debited for this payment.
customers	Array of JSON:API Relationship	The customer(s) associated with the source account.
quote	JSON:API Relationship	The `quote` used to create this payment.
counterparty	JSON:API Relationship	The international counterparty (`swiftCounterparty`) receiving the funds.
transaction	JSON:API Relationship	The ledger transaction (`type` `originatedInternationalTransaction`) debited from the source account for the payment amount.

Example international payment resource:
{
  "data": {
    "type": "internationalPayment",
    "id": "400",
    "attributes": {
      "status": "Pending",
      "direction": "Debit",
      "sourceAmount": 10850,
      "sourceCurrency": "USD",
      "destinationAmount": 10000,
      "destinationCurrency": "EUR",
      "destinationCountry": "DE",
      "purpose": "Travel",
      "sourceOfFunds": "PersonalSavings",
      "description": "Travel expenses for trip to Berlin",
      "createdAt": "2024-01-15T10:10:00.000Z",
      "updatedAt": "2024-01-15T10:10:00.000Z"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "5000"
        }
      },
      "counterparty": {
        "data": {
          "type": "swiftCounterparty",
          "id": "200"
        }
      },
      "quote": {
        "data": {
          "type": "quote",
          "id": "300"
        }
      },
      "customers": {
        "data": [
          {
            "type": "individualCustomer",
            "id": "1000"
          }
        ]
      },
      "transaction": {
        "data": {
          "type": "originatedInternationalTransaction",
          "id": "6001"
        }
      }
    }
  }
}

International Counterparty​

Attributes​

Relationships​

Routing​

International address​

Quote​

Attributes​

Relationships​

International Payment​

Attributes​

Relationships​

International Counterparty

Attributes

Relationships

Routing

International address

Quote

Attributes

Relationships

International Payment

Attributes

Relationships