Third-Party Payments

Overview

Third-party payments (3PP) allow you to send outbound payments from a virtual account to a
one-time external beneficiary. The beneficiary details are provided in each payment request.

A beneficiary can be identified in one of three ways. The ways available to you depend on your
segregated account, so check which beneficiary types your account accepts before sending a payment.

Prerequisites

Before integrating, confirm the following with your BCB account manager:

  1. Third-party payments enabled — Your segregated account must have third-party payments
    enabled. If not enabled, requests return 403 Forbidden.
  2. Virtual account active — The source virtual account must be in ACTIVE status.
  3. API credentials — A valid Bearer token with permission to create virtual account payments on the
    target segregated account.
  4. IP whitelist (if configured) — Requests must originate from an allowed IP address.

1. Find which beneficiary types you can use

GET /v1/accounts/{accountId}/third-party-payment-capabilities

Lists the third-party beneficiary identifier types accepted by the segregated account.

{
  "allowedBeneficiaryTypes": ["IBAN_BIC", "ACCOUNT_BIC", "ABA"]
}
StatusMeaning
200The supported beneficiary types were retrieved.
403Third-party payments are not enabled.
404The account is unknown.

This list depends on the account, not on the payment currency. A type in the list can still be
rejected if the payment currency does not match the account currency.

2. Send the payment with the matching type

POST /v1/accounts/{accountId}/virtual/{virtualAccountId}/third-party-payment

Sends a payment from the virtual account identified by its unique id (UUID) to a one-time third
party beneficiary. Set beneficiary.type to one of the values returned in allowedBeneficiaryTypes.

typeIdentifier fields
IBAN_BICiban: the IBAN of the beneficiary. bic: the BIC of the beneficiary bank.
ACCOUNT_BICaccountNumber: the account number of the beneficiary. bic: the BIC of the beneficiary bank.
ABAaccountNumber: the account number of the beneficiary. abaRoutingNumber: the 9-digit ABA wire routing number.

Every beneficiary type also requires:

  • name — the name of the beneficiary
  • country — the 2-letter ISO country code of the beneficiary
  • addressLine1 — the first line of the beneficiary address
  • city — the beneficiary city

Optional on every type: addressLine2, addressLine3, region (state, county or province) and
postcode (postcode or zip code). Address lines are passed on as the beneficiary's postal address
lines; empty lines are dropped.

IBAN_BIC

"beneficiary": {
  "type": "IBAN_BIC",
  "name": "John Doe",
  "iban": "DE53202208000099106929",
  "bic": "MHSBDEHBXXX",
  "country": "DE",
  "addressLine1": "Friedrichstrasse 100",
  "city": "Berlin",
  "postcode": "10115"
}
📘

Existing integrations

If type is omitted and both iban and bic are sent, the beneficiary is treated as
IBAN_BIC. ACCOUNT_BIC and ABA beneficiaries must always include type.

ACCOUNT_BIC

"beneficiary": {
  "type": "ACCOUNT_BIC",
  "name": "John Doe",
  "accountNumber": "12345678",
  "bic": "MHSBDEHBXXX",
  "country": "US",
  "addressLine1": "1 Main Street",
  "city": "New York"
}

ABA

"beneficiary": {
  "type": "ABA",
  "name": "John Doe",
  "accountNumber": "12345678",
  "abaRoutingNumber": "021000021",
  "country": "US",
  "addressLine1": "1 Main Street",
  "addressLine2": "Suite 4",
  "city": "New York"
}

abaRoutingNumber must be exactly 9 digits and is the wire routing number. ACH routing is not supported.

Full example

{
  "currency": "USD",
  "amount": "1.12",
  "reference": "payment-ref",
  "nonce": "1234567890123456",
  "reason": "INTC",
  "preferredScheme": "SWIFT",
  "beneficiary": {
    "type": "ABA",
    "name": "John Doe",
    "accountNumber": "12345678",
    "abaRoutingNumber": "021000021",
    "country": "US",
    "addressLine1": "1 Main Street",
    "city": "New York"
  }
}

A created payment returns 201 with a transactionId and end2EndId.

Payment fields

  • currency — the 3-letter currency code for the payment. GBP is not supported. The currency must
    match the currency of the account being paid from.
  • preferredScheme — one of AUTO, SEPA, SEPA_INSTANT, TARGET2 or SWIFT. Defaults to
    AUTO when omitted. For non-EUR payments, use AUTO or SWIFT.
  • reason — a predefined purpose code.
  • nonce — a unique value to guard against duplicate payments.

Errors

StatusWhen
400The request was in an incorrect format. This includes a type that is not in allowedBeneficiaryTypes, identifier fields that do not match the type, an invalid IBAN, BIC or ABA routing number, or a GBP currency.
403The segregated account is not enabled for third-party payments.
404The accountId or virtual account is unknown.

If the type is not allowed for the account, the error message looks like:

Beneficiary type ABA is not supported for segregated account (123)
🚧

Not supported

GBP sort code with account number, IBAN without a BIC, and ACH routing are not supported for
third-party payments.


Try the capabilities endpoint and
make a third-party payment in the API reference.