Counterparty

In Braid’s ecosystem, a Counterparty represents the external entity (payee or payer) involved in a transaction. A counterparty can be an individual or business entity.

API Details

API to add a Counterparty

Key Concepts for Counterparties

1. Counterparty Profile:
   A Counterparty includes main details like name, email, phone, and three potential payment methods: ACH, Wire, and Braid Account. Only one payment method is required for the counterparty to be used in a transaction.
2. Levels of Association: Counterparties can be created with three levels of association and may be reused across multiple transactions if permissions allow.
   1. Account Level: A counterparty tied to a specific account can only transact with that account.
   2. Customer Level: A counterparty associated with a specific business or individual is private to that customer and accessible only within that entity.
   3. Product Level: A counterparty at the product level is accessible across all users, suitable for commonly shared entities like billers or IRS payments.

3. Payment Methods:
   A counterparty can be set up with one of the following payment methods:
   1. ACH: For transactions using the ACH network.
   2. Wire: For wire transfer transactions.
   3. FedNow: For FedNow transactions.

At least one of these payment methods must be provided for the counterparty to be transactable.

Wire Payment Scenarios

Scenario 1: Domestic Wire Transfer

Use Case: U.S. customer sending USD to another U.S. bank.

For a Domestic Wire Transfer Receiver Bank will be considered the beneficiary bank.

Important API Fields: beneficiaryAccountNumber and receiverRoutingNumber.

Scenario 2: International Wire with No Intermediary Bank

Use Case: U.S. sender wiring funds to a UK beneficiary where the Receiver FI (US) has direct correspondence with the beneficiary bank (UK).

Scenario 3: International Wire with Intermediary Bank
Use Case: U.S. sender wires funds to a UK bank, but requires a Canadian intermediary bank in between.

Creating international (SWIFT) wire counterparties

For international wire counterparties identified by a SWIFT or BIC code, use the Create a Counterparty V2 endpoint. The legacy Create a Counterparty endpoint requires a valid ABA routing number and does not support BIC-only wire counterparties, so BIC or SWIFT beneficiaries should be created through V2.

In V2, identify the beneficiary institution by its SWIFT or BIC code; a beneficiary ABA is not required:

• beneficiaryFiIdType: set to BIC
• beneficiaryFiIdNumber: the beneficiary bank's SWIFT or BIC code
• accountNumber: the beneficiary account number or IBAN

Note: When a correspondent (intermediary) bank is required, correspondentFiIdType must be ABA — a correspondent BIC is not supported. Braid attempts to resolve a US correspondent automatically from the beneficiary bank information; if that lookup is unsuccessful, supply the correspondent bank's ABA routing number.

Example request body for the Create a Counterparty V2 endpoint:

{
  "name": "Acme UK Ltd",
  "type": "BUSINESS",
  "associatedEntityType": "BUSINESS_CUSTOMER",
  "associatedEntityId": 12345,
  "address": {
    "type": "MAILING",
    "line1": "42 King William Street",
    "city": "London",
    "postalCode": "EC4N 7RF",
    "countryCode": "GB"
  },
  "paymentInstruments": [
    {
      "paymentInstrumentTypes": ["WIRE"],
      "accountNumber": "GB29NWBK60161331926819",
      "beneficiaryFiIdType": "BIC",
      "beneficiaryFiIdNumber": "LOYDGB2LXXX"
    }
  ]
}