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:
- Third-party payments enabled — Your segregated account must have third-party payments
enabled. If not enabled, requests return 403 Forbidden. - Virtual account active — The source virtual account must be in ACTIVE status.
- API credentials — A valid Bearer token with permission to create virtual account payments on the
target segregated account. - 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"]
}| Status | Meaning |
|---|---|
| 200 | The supported beneficiary types were retrieved. |
| 403 | Third-party payments are not enabled. |
| 404 | The 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
typePOST /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.
type | Identifier fields |
|---|---|
IBAN_BIC | iban: the IBAN of the beneficiary. bic: the BIC of the beneficiary bank. |
ACCOUNT_BIC | accountNumber: the account number of the beneficiary. bic: the BIC of the beneficiary bank. |
ABA | accountNumber: the account number of the beneficiary. abaRoutingNumber: the 9-digit ABA wire routing number. |
Every beneficiary type also requires:
name— the name of the beneficiarycountry— the 2-letter ISO country code of the beneficiaryaddressLine1— the first line of the beneficiary addresscity— 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
IBAN_BIC"beneficiary": {
"type": "IBAN_BIC",
"name": "John Doe",
"iban": "DE53202208000099106929",
"bic": "MHSBDEHBXXX",
"country": "DE",
"addressLine1": "Friedrichstrasse 100",
"city": "Berlin",
"postcode": "10115"
}
Existing integrationsIf
typeis omitted and bothibanandbicare sent, the beneficiary is treated as
IBAN_BIC.ACCOUNT_BICandABAbeneficiaries must always includetype.
ACCOUNT_BIC
ACCOUNT_BIC"beneficiary": {
"type": "ACCOUNT_BIC",
"name": "John Doe",
"accountNumber": "12345678",
"bic": "MHSBDEHBXXX",
"country": "US",
"addressLine1": "1 Main Street",
"city": "New York"
}ABA
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 ofAUTO,SEPA,SEPA_INSTANT,TARGET2orSWIFT. Defaults to
AUTOwhen omitted. For non-EUR payments, useAUTOorSWIFT.reason— a predefined purpose code.nonce— a unique value to guard against duplicate payments.
Errors
| Status | When |
|---|---|
| 400 | The 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. |
| 403 | The segregated account is not enabled for third-party payments. |
| 404 | The 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 supportedGBP 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.
Updated 22 days ago