Set payout details

PUT /api/v2/storefront/billing/payout-details Saves the bank account Interchange uses to pay you. Payouts are made by bank transfer in your payout currency, executed by Interchange finance — there is no payment processor. Payout details on file are required before Interchange can disburse accrued funds. Missing details never block activation or transacting: media buys remain Interchange-cleared (agent) and funds continue to accrue. Seller-cleared settlement is not yet configurable for normal Seller Accounts. Organization-admin only. A child-account admin cannot create or replace a payout destination. Parent organization admins manage a direct child Seller Account with the REST query parameter ?targetCustomerId=<child-id>. The operation is also available to agents as set_payout_details for the active organization. In Plan & Billing → Payouts, a parent admin selects the organization or a direct child Seller Account from the account dropdown. The agent operation does not expose direct-child targeting today. accountNumber accepts a bank account number or an IBAN. Exactly one bank identifier is set via the bankIdentifierType + bankIdentifierValue pair. Submitting again replaces the details on file; omitting accountNumber on a resubmit keeps the stored account number (it is write-only and never prefilled).

Request

curl -X PUT https://api.interchange.io/api/v2/storefront/billing/payout-details \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryName": "Meridian Media Group Inc.",
    "addressLine1": "500 Harbor Blvd",
    "city": "Seattle",
    "region": "WA",
    "postalCode": "98101",
    "countryCode": "US",
    "accountNumber": "000123456789",
    "bankIdentifierType": "FEDWIRE_ABA",
    "bankIdentifierValue": "021000021",
    "currency": "USD"
  }'

Parameters

Field	Type	Required	Notes
`beneficiaryName`	string	Yes	Account holder’s legal name, exactly as it appears on the bank account (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. `US`, `DE`)
`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 details are 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` (e.g. `021000021`)
`currency`	string	Yes	ISO 4217 payout currency, uppercase (e.g. `USD`, `EUR`) — the currency Interchange pays this account in
`targetCustomerId`	number	No	Query param. Organization admins set details for a direct child Seller Account. Child-context principals cannot write payout details.

Response

Returns the full updated billing configuration with masked payout details:

{
  "billing": {
    "onboardingStatus": "complete",
    "platformFeePercent": 12.5,
    "fees": [
      { "name": "Ad serving", "description": "Third-party ad serving", "feePercent": 2 }
    ],
    "currency": "USD",
    "country": "US",
    "defaultNetDays": 30,
    "payoutDetails": {
      "beneficiaryName": "Meridian Media Group Inc.",
      "addressLine1": "500 Harbor Blvd",
      "addressLine2": null,
      "city": "Seattle",
      "region": "WA",
      "postalCode": "98101",
      "countryCode": "US",
      "accountNumberLast4": "6789",
      "bankIdentifierType": "FEDWIRE_ABA",
      "bankIdentifierValue": "021000021",
      "completedAt": "2026-07-01T09:30:00Z"
    },
    "inherited": false,
    "createdAt": "2026-04-25T12:00:00Z",
    "updatedAt": "2026-07-01T09:30:00Z"
  }
}

The account number is write-only: it is encrypted at the application layer (AES-256-GCM) before storage, so the database never holds a plaintext account number, and it is never returned after save — reads expose accountNumberLast4 only. onboardingStatus is complete once payout details are on file. The same shape is returned by Get billing config and the get_billing_info operation.

Errors

400 VALIDATION_ERROR — malformed accountNumber (must be 6–34 letters/digits), a bankIdentifierValue that doesn’t match its bankIdentifierType (e.g. a routing number that isn’t 9 digits), a lowercase or non-ISO countryCode/currency, or a missing required field.

See Errors for the full error contract.

Billing tasks

All billing operations

Get billing config

Confirm the masked details on file

Billing overview

How payouts work and why bank details are needed

Get readiness

The billing_setup check this satisfies

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Billing tasks

Get billing config

Billing overview

Get readiness

​Request

​Parameters

​Response

​Errors

​Related

Billing tasks

Get billing config

Billing overview

Get readiness

Request

Parameters

Response

Errors

Related