​
Overview

A payee is an external bank account recipient you can pay. You create a payee once with its bank details, then reference it by id whenever you initiate a payment. Payees are reusable, so the bank details and any compliance checks live with the payee rather than being re-supplied per payment.

List payees

Page through every payee you’ve created.

Create a payee

Add an external recipient with its bank details.

​
Payee object

​
id
string
Unique Balansas identifier (UUID). Reference this when initiating a payment.
​
fr_payee_id
string
Banking partner payee ID (reference only).
​
payee_name
string
Payee / beneficiary name (1–200 characters).
​
type
string
PERSON or BUSINESS.
​
currency
string
EUR, GBP, or USD.
​
account_number
string
Bank account number or IBAN.
​
status
string
Payee lifecycle status. See Status values.
​
created_at
string
ISO 8601 timestamp.

​
Creating a payee

The create request needs the name, type, currency, address, and currency-shaped bank details.
​
name
string
required
1–200 characters. For PERSON payees tied to an end user, this must match the end user’s registered name (see Compliance for end users).
​
type
string
required
PERSON or BUSINESS.
​
currency
string
required
USD, EUR, or GBP.
​
address
object
required
line1, city, postalCode, country (2-letter ISO) required; line2 and stateRegion optional.
​
bankDetails
object
required
Bank details — fields vary by currency, see below.
​
endUserId
string
UUID. Link the payee to an end user.
​
umbrellaLinkId
string
UUID. Provision under a Balansas-managed master business in PPA Mode.

​
Bank details by currency

  • iban (max 34 chars), bic (max 11 chars), optional accountHolderName.
  • sortCode (max 10 chars), accountNumber (max 50 chars), optional accountHolderName.
  • routingNumber (ABA, max 9 chars), accountNumber (max 50 chars), accountType (CHECKING or SAVINGS). The payment scheme is chosen at payment time.
  • The ACH/wire fields above plus bic, bankName, bankAddressLine1, bankAddressCity, bankAddressPostalCode, and bankAddressCountry (2-letter ISO).
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/payees \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme Supplies Ltd",
        "type": "BUSINESS",
        "currency": "EUR",
        "address": {
          "line1": "1 Market St",
          "city": "Dublin",
          "postalCode": "D02 XY00",
          "country": "IE"
        },
        "bankDetails": {
          "iban": "IE29AIBK93115212345678",
          "bic": "AIBKIE2D"
        }
      }'

​
Status values

StatusMeaning
activeApproved and ready to receive payments.
processingBeing verified by the banking provider.
compliance_reviewNeeds manual review (usually a name mismatch for an end user).
blockedBlocked; cannot receive payments.
closedClosed; terminal.

​
Compliance for end users

When you create a PERSON payee for an end user, the payee name must match the end user’s registered name. Names are validated case-insensitively and allow middle initials; a mismatch lands the payee in compliance_review. For an end user named “John Michael Smith”:
  • Valid: “John Smith”, “John M Smith”, “Smith, John”
  • Invalid: “Acme Corp”, “Jane Doe”

​
Using payees in payments

Once a payee is active, initiate an outgoing payment by referencing its id. The currency, bank details, and destination all come from the payee, so the payment request just specifies the source account, amount, and scheme.

Payments

See how payees are consumed when moving money.