Set payout details

PUT /api/v2/storefront/billing/payout-details Saves the bank account Interchange pays your storefront into. 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 for Interchange-cleared (agent) settlement. Seller-cleared settlement is not yet configurable for normal storefronts. Admin-only. Also available to agents as the set_payout_details operation, or in the UI under Settings → Billing. 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. Organizations set details for a managed account

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

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

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