Set payout payee (admin)

curl --request PUT \
  --url https://api.interchange.io/api/v2/storefront/billing/payees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityName": "<string>",
  "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/payees"

payload = {
    "entityName": "<string>",
    "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({
    entityName: '<string>',
    beneficiaryName: '<string>',
    addressLine1: '<string>',
    city: '<string>',
    postalCode: '<string>',
    countryCode: 'US',
    bankIdentifierValue: '<string>',
    currency: 'USD'
  })
};

fetch('https://api.interchange.io/api/v2/storefront/billing/payees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payee": {
    "beneficiaryName": "<string>",
    "addressLine1": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>",
    "accountNumberLast4": "<string>",
    "bankIdentifierValue": "<string>",
    "completedAt": "2023-11-07T05:31:56Z",
    "id": 0,
    "entityName": "<string>",
    "currency": "<string>",
    "isPrimary": 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": {}
  }
}

PUT

billing

payees

Set payout payee (admin)

curl --request PUT \
  --url https://api.interchange.io/api/v2/storefront/billing/payees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityName": "<string>",
  "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/payees"

payload = {
    "entityName": "<string>",
    "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({
    entityName: '<string>',
    beneficiaryName: '<string>',
    addressLine1: '<string>',
    city: '<string>',
    postalCode: '<string>',
    countryCode: 'US',
    bankIdentifierValue: '<string>',
    currency: 'USD'
  })
};

fetch('https://api.interchange.io/api/v2/storefront/billing/payees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "payee": {
    "beneficiaryName": "<string>",
    "addressLine1": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>",
    "accountNumberLast4": "<string>",
    "bankIdentifierValue": "<string>",
    "completedAt": "2023-11-07T05:31:56Z",
    "id": 0,
    "entityName": "<string>",
    "currency": "<string>",
    "isPrimary": 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

Query Parameters

targetCustomerId

string

Direct child customer to read or update from an authorized parent billing organization

Pattern: ^[1-9][0-9]*$

Body

application/json

entityName

string

required

Label for the legal payout entity this bank account belongs to (e.g. "Acme Media India Pvt Ltd"). Together with the payout currency it identifies the payee: one bank account per entity per currency.

Required string length: 1 - 255

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.

isPrimary

boolean

Set true to make this the customer's PRIMARY payout entity (the one returned as payoutDetails on GET /billing), demoting any other primary payee. Omit to leave the current primary/non-primary status unchanged. Exactly one payee per customer is primary: a customer's FIRST payee always becomes the primary regardless of this field.

Response

Set payout payee (admin)

payee

object

required

A payout payee — the bank account for one legal payout entity in one payout currency (masked: the account number is reduced to its last 4 characters).

Show child attributes

⌘I