Skip to main content
PUT /api/v2/storefront/billing/payout-details Saves the bank account Scope3 pays your storefront into. Payouts are made by bank transfer in your payout currency, executed by Scope3 finance — there is no payment processor. Payout details on file are required for Scope3-cleared (agent) billing on media buys; without them you bill the buyer directly. 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

FieldTypeRequiredNotes
beneficiaryNamestringYesAccount holder’s legal name, exactly as it appears on the bank account (1–255)
addressLine1stringYesBeneficiary street address, line 1
addressLine2stringNoBeneficiary street address, line 2
citystringYesBeneficiary city
regionstringNoState/province/region
postalCodestringYesPostal/ZIP code
countryCodestringYesISO 3166-1 alpha-2, uppercase (e.g. US, DE)
accountNumberstringFirst setBank 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
bankIdentifierTypeenumYesFEDWIRE_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)
bankIdentifierValuestringYesThe identifier itself, matching bankIdentifierType (e.g. 021000021)
currencystringYesISO 4217 payout currency, uppercase (e.g. USD, EUR) — the currency Scope3 pays this account in
targetCustomerIdnumberNoQuery 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