> ## 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 details

> Save the bank account Interchange pays your storefront into — beneficiary, account number or IBAN, bank identifier, and payout currency

`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

```bash theme={null}
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:

```json theme={null}
{
  "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](/v2/storefront/billing/tasks/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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Billing tasks" href="/v2/storefront/billing/tasks" icon="list-check">
    All billing operations
  </Card>

  <Card title="Get billing config" href="/v2/storefront/billing/tasks/get-billing-config" icon="gear">
    Confirm the masked details on file
  </Card>

  <Card title="Billing overview" href="/v2/storefront/billing/overview" icon="credit-card">
    How payouts work and why bank details are needed
  </Card>

  <Card title="Get readiness" href="/v2/storefront/tasks/get-readiness" icon="circle-check">
    The `billing_setup` check this satisfies
  </Card>
</CardGroup>