Skip to content

Bank Account Requirements API

The Bank Account Requirements API returns the dynamic form schema required to collect bank account details for a given country, currency, and entity type. The schema is sourced from Airwallex and defines which fields are needed, their types, validation rules, and display labels.

Endpoints

Get Bank Account Requirements

Fetch the form schema for collecting bank account (beneficiary) details. This endpoint does not require a company context.

Endpoint

POST /api/v1/bank_account_requirements

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Request Body

Parameter Type Required Description
country_code string Yes ISO 3166-1 alpha-2 country code (e.g., US, GB)
currency_code string Yes ISO 4217 currency code (e.g., USD, EUR)
entity_type string Yes Entity type: COMPANY or PERSONAL
transfer_method string No Transfer method (e.g., LOCAL, SWIFT)
local_clearing_system string No Local clearing system (e.g., ACH, FEDWIRE)

Case Insensitive

All parameters are case-insensitive. For example, us and US are treated the same.

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/bank_account_requirements" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "currency_code": "USD",
    "entity_type": "COMPANY",
    "transfer_method": "LOCAL",
    "local_clearing_system": "ACH"
  }'

Success Response (200 OK)

{
  "data": {
    "condition": {
      "account_currency": "USD",
      "bank_country_code": "US",
      "entity_type": "COMPANY",
      "local_clearing_system": "ACH",
      "transfer_method": "LOCAL"
    },
    "fields": [
      {
        "enabled": true,
        "path": "beneficiary.entity_type",
        "required": true,
        "field": {
          "key": "entity_type",
          "label": "Recipient account type",
          "type": "RADIO",
          "options": [
            { "label": "Business", "value": "COMPANY" },
            { "label": "Personal", "value": "PERSONAL" }
          ],
          "default": "COMPANY",
          "refresh": true
        },
        "rule": {
          "type": "string",
          "pattern": "COMPANY|PERSONAL"
        }
      },
      {
        "enabled": true,
        "path": "beneficiary.bank_details.account_routing_type1",
        "required": true,
        "field": {
          "key": "account_routing_type1",
          "label": "Routing type",
          "type": "INPUT"
        },
        "rule": {
          "type": "string"
        }
      },
      {
        "enabled": true,
        "path": "beneficiary.bank_details.account_routing_value1",
        "required": true,
        "field": {
          "key": "account_routing_value1",
          "label": "Routing number",
          "type": "INPUT"
        },
        "rule": {
          "type": "string"
        }
      },
      {
        "enabled": true,
        "path": "beneficiary.bank_details.account_number",
        "required": true,
        "field": {
          "key": "account_number",
          "label": "Account number",
          "type": "INPUT"
        },
        "rule": {
          "type": "string"
        }
      },
      {
        "enabled": true,
        "path": "beneficiary.bank_details.account_name",
        "required": true,
        "field": {
          "key": "account_name",
          "label": "Account holder name",
          "type": "INPUT"
        },
        "rule": {
          "type": "string"
        }
      },
      {
        "enabled": true,
        "path": "beneficiary.address.street_address",
        "required": true,
        "field": {
          "key": "street_address",
          "label": "Street address",
          "type": "INPUT"
        },
        "rule": {
          "type": "string"
        }
      }
    ]
  }
}

Response is Truncated

The example above shows a subset of fields. The actual response includes all fields required for the given country/currency/transfer method combination.

Understanding the Schema

Each item in the fields array describes a form field:

Property Type Description
enabled boolean Whether the field should be displayed
path string Dot-notation path defining where the value goes in the request body
required boolean Whether the field is required
field.key string Unique field identifier
field.label string Display label for the field
field.type string Field type: INPUT, SELECT, RADIO, TRANSFER_METHOD
field.options array Available options for SELECT and RADIO types
field.default string Default value (if any)
field.refresh boolean If true, changing this field should trigger a new schema fetch
rule object Validation rules (type, pattern, min/max length)

Using the path Field

The path field tells you where to place each value in the awx_beneficiary_details object when creating a bank account. For example:

Schema path Maps to JSON
beneficiary.entity_type awx_beneficiary_details.beneficiary.entity_type
beneficiary.bank_details.account_number awx_beneficiary_details.beneficiary.bank_details.account_number
beneficiary.address.city awx_beneficiary_details.beneficiary.address.city

Handling refresh Fields

Some fields have "refresh": true. When the user changes the value of a refresh field (e.g., entity_type or bank_country_code), you should call this endpoint again with the new values to get an updated schema. The required fields may change based on the selected values.

Error Responses

400 Bad Request - Missing Parameter

{
  "errors": [
    {
      "field": "country_code",
      "message": "country_code is required"
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

422 Unprocessable Entity - Service Error

{
  "errors": [
    {
      "field": "base",
      "message": "Error message from Airwallex"
    }
  ]
}