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 Plan & Billing → Payouts. To manage a direct seller child storefront, a parent organization admin selects it from the account dropdown in Plan & Billing → Payouts or passes ?targetCustomerId=<child-id> through REST. The agent operation acts on the active organization and does not expose direct-child targeting. A child-only admin cannot create or replace payout destinations, including for its own account. A child without an account-specific payee uses the organization’s inherited payout configuration. 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. Organization admins set payees for a direct seller child account. Child-context principals cannot write payout payees.

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.
403 ACCESS_DENIED — the caller is not an account admin, or targetCustomerId is not a direct seller child of the active organization.

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