Set payout payee

PUT /api/v2/storefront/billing/payees Saves the payout bank account for one legal payout entity in one payout currency. Use this when your organization is paid through more than one legal entity (for example an India entity and a Brazil entity) — each entity gets its own bank account per payout currency. Your default payout details (set via Set payout details) are unaffected. Admin-only. Also available to agents as the set_payout_payee operation, or in the UI under Settings → Billing → Payout entities. Upserts by entityName + currency: submitting the same pair again updates that payee; a new pair creates a new payee. One bank account clears one payout currency, so an entity paid in two currencies has two payees. The beneficiaryName must match the account holder — the legal entity itself.

Request

curl -X PUT https://api.interchange.io/api/v2/storefront/billing/payees \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityName": "Meridian Media India Pvt Ltd",
    "beneficiaryName": "Meridian Media India Pvt Ltd",
    "addressLine1": "1 MG Road",
    "city": "Bengaluru",
    "postalCode": "560001",
    "countryCode": "IN",
    "accountNumber": "000123456789",
    "bankIdentifierType": "SWIFT_BIC",
    "bankIdentifierValue": "HDFCINBB",
    "currency": "INR"
  }'

Parameters

Field	Type	Required	Notes
`entityName`	string	Yes	Label for the legal payout entity this account belongs to (1–255). Part of the payee’s identity, together with `currency`
`beneficiaryName`	string	Yes	Account holder’s legal name, exactly as it appears on the bank account — the legal entity itself (1–255)
`addressLine1`	string	Yes	Beneficiary street address, line 1
`addressLine2`	string	No	Beneficiary street address, line 2
`city`	string	Yes	Beneficiary city
`region`	string	No	State/province/region
`postalCode`	string	Yes	Postal/ZIP code
`countryCode`	string	Yes	ISO 3166-1 alpha-2, uppercase (e.g. `IN`, `BR`)
`accountNumber`	string	First set	Bank account number or IBAN — 6–34 letters/digits, spaces stripped. Write-only: reads return the last 4 characters. Required the first time the payee is set; omit on later updates to keep the stored value
`bankIdentifierType`	enum	Yes	`FEDWIRE_ABA` (9-digit US routing number), `CHIPS_ABA` (9-digit CHIPS ABA), `SWIFT_BIC` (8/11-character SWIFT-BIC), or `BANK_CODE` (local bank code)
`bankIdentifierValue`	string	Yes	The identifier itself, matching `bankIdentifierType`
`currency`	string	Yes	ISO 4217 payout currency, uppercase (e.g. `INR`, `BRL`) — the currency Interchange pays this account in. Part of the payee’s identity, together with `entityName`
`targetCustomerId`	number	No	Query param. Parent customers set payees for a child account

Response

Returns the masked payee:

{
  "payee": {
    "id": 12,
    "entityName": "Meridian Media India Pvt Ltd",
    "currency": "INR",
    "beneficiaryName": "Meridian Media India Pvt Ltd",
    "addressLine1": "1 MG Road",
    "addressLine2": null,
    "city": "Bengaluru",
    "region": null,
    "postalCode": "560001",
    "countryCode": "IN",
    "accountNumberLast4": "6789",
    "bankIdentifierType": "SWIFT_BIC",
    "bankIdentifierValue": "HDFCINBB",
    "completedAt": "2026-07-09T09:30:00Z",
    "createdAt": "2026-07-09T09:30:00Z",
    "updatedAt": "2026-07-09T09:30:00Z"
  }
}

The account number is write-only: it is encrypted at the application layer (AES-256-GCM) before storage and never returned after save — reads expose accountNumberLast4 only. To remove a payee, contact Interchange support (removal is finance-mediated as a bank-detail change control).

Errors

400 VALIDATION_ERROR — missing entityName, malformed accountNumber (must be 6–34 letters/digits), a bankIdentifierValue that doesn’t match its bankIdentifierType, a lowercase or non-ISO countryCode/currency, or an omitted accountNumber when the payee has none on file yet.

See Errors for the full error contract.

List payout payees

Confirm the masked payees on file

Set payout details

Your default payout bank account

Billing overview

How payouts work and why bank details are needed

Billing tasks

All billing operations

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Parameters

Response

Errors

List payout payees

Set payout details

Billing overview

Billing tasks

​Request

​Parameters

​Response

​Errors

​Related

List payout payees

Set payout details

Billing overview

Billing tasks

Request

Parameters

Response

Errors

Related