Resources

SWIFT Counterparty

Creates a SWIFT counterparty for a specific customer.

Attributes

Name	Type	Description
type	string	Either Business or Person.
name	string	The account holder's name (individual or business). Up to 255 characters.
bic	string	BIC (SWIFT Bank Identifier Code) of the recipient's bank. 8 or 11 alphanumeric characters.
accountNumber	string	Recipient bank account number or IBAN (International Bank Account Number). 1-34 alphanumeric characters (uppercase letters and digits only).
country	string	ISO 3166-1 alpha-2 destination country code.
currency	string	ISO 4217 destination currency (e.g. EUR, GBP).
address Required	object	Recipient International address. country 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 SWIFT counterparty resource:

{
  "data": {
    "type": "swiftCounterparty",
    "id": "200",
    "attributes": {
      "type": "Person",
      "name": "Hans Mueller",
      "bic": "COBADEFFXXX",
      "accountNumber": "DE89370400440532013000",
      "country": "DE",
      "currency": "EUR",
      "address": {
        "country": "DE",
        "street": "Friedrichstrasse 123",
        "city": "Berlin",
        "postalCode": "10117"
      },
      "tags": {
        "label": "EU supplier"
      },
      "createdAt": "2024-01-15T10:02:00.000Z",
      "updatedAt": "2024-01-15T10:02:00.000Z"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1000"
        }
      }
    }
  }
}

International address

Name	Type	Description
country	string	ISO 3166-1 alpha-2 country code.
street	string	The street name and number. 1-255 characters.
city	string	City. 1-50 characters.
state	string	State or province. For US and CA addresses, two letters representing the state (US) or province (CA). 1-50 characters.
postalCode	string	Postal code. 1-15 characters.

---

Quote

Prerequisites

A SWIFT 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 Statuses.
sourceCurrency	string	ISO 4217 source currency. Always USD.
destinationCurrency	string	ISO 4217 destination currency code. Matches the related counterparty's currency.
destinationAmount	integer	Amount the counterparty will receive, in the destination currency's minor unit (e.g. cents for EUR).
exchangeRate	string	The FX rate applied. Absent for USD→USD quotes.
sourceAmount	integer	The amount (in cents), before fees.
feeAmount	integer	The fee (in cents) for the payment.
totalAmount	integer	Total USD cents debited from the source account when the payment is created (principal and fees).
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,
      "feeAmount": 1750,
      "totalAmount": 12600,
      "expiresAt": "2024-01-15T10:20:00.000Z",
      "createdAt": "2024-01-15T10:05:00.000Z"
    },
    "relationships": {
      "counterparty": {
        "data": {
          "type": "swiftCounterparty",
          "id": "200"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "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, Sent, 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 Credit.
sourceAmount	integer	USD cents of converted principal (equals the quote's sourceAmount). The account is debited per the quote's totalAmount.
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. One of Salary, PersonalSavings, PersonalWealth, RetirementFunds, BusinessOwner, LoanFacility, PersonalAccount, CorporateAccount.
reason Optional	string	Present when status is Rejected or Returned. See Rejection reasons and Return reasons for possible values.
description Optional	string	Payment description (maximum of 255 characters).
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 International Payment Transaction debited from the source account for the payment amount.

Example international payment resource:

{
  "data": {
    "type": "internationalPayment",
    "id": "400",
    "attributes": {
      "status": "Pending",
      "direction": "Credit",
      "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": "businessCustomer",
            "id": "1000"
          }
        ]
      },
      "transaction": {
        "data": {
          "type": "originatedInternationalTransaction",
          "id": "6001"
        }
      }
    }
  }
}

---

International Payment Transaction

Name	Type	Description
id	string	Identifier of the transaction resource.
type	string	Type of the transaction resource. The value is always originatedInternationalTransaction.
attributes	JSON Object	JSON object representing the transaction data.
relationships	JSON:API Relationships	Describes relationships between the transaction resource and other resources (account, customer and payment).

Attributes

Name	Type	Description
createdAt	RFC3339 Date string	The date the transaction was created. Common to all transaction types.
direction	string	The direction in which the funds flow. Common to all transaction types. Always Debit.
amount	integer	The amount (cents) of the transaction. Common to all transaction types.
balance	integer	The account balance (cents) after the transaction. Common to all transaction types.
summary	string	Summary of the transaction. Common to all transaction types.
tags	object	See Tags. Inherited from the payment tags (see Tag Inheritance).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account of the customer.
customer	Optional, JSON:API Relationship	The Customer the deposit account belongs to. This relationship is only available if the account belongs to a single customer, business or individual.
customers	Optional, Array of JSON:API Relationship	The list of Customers the deposit account belongs to. This relationship is only available if the account belongs to multiple individual customers.
payment	JSON:API Relationship	The International Payment belonging to this transaction.

Example OriginatedInternationalTransaction resource:

{
  "data": {
    "type": "originatedInternationalTransaction",
    "id": "6001",
    "attributes": {
      "createdAt": "2024-01-15T10:10:00.000Z",
      "direction": "Debit",
      "amount": 10850,
      "balance": 500,
      "summary": "International payment to Hans Mueller",
      "tags": {
        "invoice_id": "INV-2024-0115"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "5000"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1000"
        }
      },
      "payment": {
        "data": {
          "type": "internationalPayment",
          "id": "400"
        }
      }
    }
  }
}