Resources Coming Soon

Early preview

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

Crossborder Counterparty

A crossborder 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 Crossborder routing.
accountType	string	Either Individual or Corporate.
address Required	object	Recipient Crossborder 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 crossborder 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"
        }
      }
    }
  }
}

Crossborder routing

routing groups the recipient's bank details by network. Only swift is supported today; more networks will follow as we add crossborder 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.

Crossborder 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.

---

Crossborder Quote

Prerequisites

A Crossborder Counterparty must exist before a quote can be created.

A crossborder quote is a JSON resource with type quote that locks in the terms for a single crossborder 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 crossborder 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"
        }
      }
    }
  }
}

---

Crossborder Payment

Prerequisites

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

A crossborder payment is a payment resource with type crossborderPayment, 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 crossborder payments; schema remains nullable for backward compatibility.
purpose	string	The purpose of the payment. See Crossborder 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 crossborder counterparty (swiftCounterparty) receiving the funds.
transaction	JSON:API Relationship	The ledger transaction (type originatedCrossborderTransaction) debited from the source account for the payment amount.

Example crossborder payment resource:

{
  "data": {
    "type": "crossborderPayment",
    "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": "originatedCrossborderTransaction",
          "id": "6001"
        }
      }
    }
  }
}