> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Set payout payee > Register a payout bank account for one legal entity in one payout currency — for sellers paid through multiple legal entities `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](/v2/storefront/billing/tasks/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 ```bash theme={null} 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: ```json theme={null} { "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](/v2/reference/errors) for the full error contract. ## Related Confirm the masked payees on file Your default payout bank account How payouts work and why bank details are needed All billing operations