Skip to main content
PUT
/
billing
/
payout-details
Set payout details (admin)
curl --request PUT \
  --url https://api.interchange.io/api/v2/storefront/billing/payout-details \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "beneficiaryName": "<string>",
  "addressLine1": "<string>",
  "city": "<string>",
  "postalCode": "<string>",
  "countryCode": "US",
  "bankIdentifierValue": "<string>",
  "currency": "USD"
}
'
import requests

url = "https://api.interchange.io/api/v2/storefront/billing/payout-details"

payload = {
    "beneficiaryName": "<string>",
    "addressLine1": "<string>",
    "city": "<string>",
    "postalCode": "<string>",
    "countryCode": "US",
    "bankIdentifierValue": "<string>",
    "currency": "USD"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    beneficiaryName: '<string>',
    addressLine1: '<string>',
    city: '<string>',
    postalCode: '<string>',
    countryCode: 'US',
    bankIdentifierValue: '<string>',
    currency: 'USD'
  })
};

fetch('https://api.interchange.io/api/v2/storefront/billing/payout-details', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "billing": {
    "platformFeePercent": 123,
    "fees": [
      {
        "name": "<string>",
        "feePercent": 50,
        "description": "<string>"
      }
    ],
    "currency": "<string>",
    "country": "<string>",
    "defaultNetDays": 123,
    "payoutDetails": {
      "beneficiaryName": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "region": "<string>",
      "postalCode": "<string>",
      "countryCode": "<string>",
      "accountNumberLast4": "<string>",
      "bankIdentifierValue": "<string>",
      "completedAt": "2023-11-07T05:31:56Z"
    },
    "inherited": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}
{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}
{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}
{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json
​
beneficiaryName
string
required

Legal name of the payout beneficiary — the account holder the bank pays, exactly as it appears on the bank account.

Required string length: 1 - 255
​
addressLine1
string
required

Beneficiary street address, line 1.

Required string length: 1 - 255
​
city
string
required

Beneficiary city.

Required string length: 1 - 128
​
postalCode
string
required

Beneficiary postal/ZIP code.

Required string length: 1 - 32
​
countryCode
string
required

Beneficiary country as an ISO 3166-1 alpha-2 code (e.g. "US", "GB").

Pattern: ^[A-Z]{2}$
Example:

"US"

​
bankIdentifierType
enum<string>
required

Which bank identifier system bankIdentifierValue uses: FEDWIRE_ABA (US Fedwire/ABA routing number, 9 digits), CHIPS_ABA (CHIPS ABA number, 9 digits), SWIFT_BIC (SWIFT/BIC code, 8 or 11 characters), or BANK_CODE (a local/domestic bank code for banks without a SWIFT-BIC).

Available options:
FEDWIRE_ABA,
CHIPS_ABA,
SWIFT_BIC,
BANK_CODE
​
bankIdentifierValue
string
required

The bank identifier itself, matching bankIdentifierType: a 9-digit Fedwire/ABA routing number, a 9-digit CHIPS ABA number, an 8/11-character SWIFT-BIC, or a local bank code (1–34 letters/digits/dashes).

Required string length: 1 - 34
​
currency
string
required

Payout currency as a 3-letter uppercase ISO 4217 code — the currency Scope3 pays this account out in.

Pattern: ^[A-Z]{3}$
Example:

"USD"

​
addressLine2
string

Beneficiary street address, line 2 (optional).

Maximum string length: 255
​
region
string

Beneficiary state/province/region (optional).

Maximum string length: 128
​
accountNumber
string

Bank account number OR IBAN (6–34 alphanumeric characters; spaces are stripped). Never returned in full by the API — reads expose only the last 4 characters. Required the first time payout details are set; may be omitted on later updates to keep the stored account number unchanged.

Response

Set payout details (admin)

​
billing
object
required

Storefront billing configuration. Storefront billing setup is optional. Add payout bank details so Scope3 can clear payments and pay you out — otherwise your Storefront will be limited to external agreements only and you will bill the buyer directly.