Guides

External Accounts

External Bank Accounts

These accounts are existing bank accounts that belong to your customers (e.g., an HSBC bank account that an Individual has for their own personal use). They are not created or managed by Walapay.

Creation

📘

Rails Parameter

Certain countries have multiple payment rails and not all rails require the same information or not all banks accept all rails. For countries like Brazil, the two available rails (PIX and TED) require different fields, so you can specify which rail you would like to create the account for by using the rails parameter.

curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/accounts/<customerId>' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
    "type": "EXTERNAL_BANK_ACCOUNT",
    "currencyCode": "USD",
    "isThirdParty": true, // true means the account does not belong to the customer
    "rails": ["ACH"], // optional (see API reference for details)
    "bank": {
        "name": "U.S. Bank",
        "accountNumber": "123456789",
        "routingNumber": "021000089",
        "type": "CHECKING",
        "address": {
            "streetLine1": "425 Walnut Street",
            "city": "Cincinnati",
            "stateRegionOrProvince": "OH",
            "postalCode": "45202",
            "countryCode": "US"
        }
    },
    "accountHolder": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "address": {
            "streetLine1": "123 Main Street",
            "city": "Cincinnati",
            "stateRegionOrProvince": "OH",
            "postalCode": "45202",
            "countryCode": "US"
        },
        "type": "INDIVIDUAL"
    }
}'
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/accounts/<customerId>' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
    "type": "EXTERNAL_BANK_ACCOUNT",
    "currencyCode": "PHP",
    "isThirdParty": true,
    "bank": {
        "name": "Bank Of Philippines Islands",
        "accountNumber": "1234567890",
        "type": "SAVING",
        "address": {
            "streetLine1": "Ayala Avenue",
            "city": "Makati",
            "stateRegionOrProvince": "Metro Manila",
            "postalCode": "1226",
            "countryCode": "PH"
        }
    },
    "accountHolder": {
        "firstName": "Juan",
        "lastName": "Dela Cruz",
        "email": "[email protected]",
        "address": {
            "streetLine1": "456 Quezon Street",
            "city": "Quezon City",
            "stateRegionOrProvince": "Metro Manila",
            "postalCode": "1100",
            "countryCode": "PH"
        },
        "type": "INDIVIDUAL"
    }
}'

Requirements by Region

A few notes:

  1. Account Holder Address: The address cannot be a PO Box or PMB (Private Mailbox). This will cause issues when attempting to send a payment
  2. First/Last or Business Name: If the account holder is an individual, you will always need to provide their first and last name. If the account holder is a business, you will always need to provide the business name
  3. Account Type: If the country you're sending money to doesn't use the concept of Checking vs. Savings accounts, we recommend you default to Checking
  4. Bank Name: Some countries require the bank name. In a subset of these countries, they even require it to be spelled exactly. When this is the case, please use the enum returned in the GET endpoint below; otherwise, free-form entry is allowed
📘

API Endpoint

We recommend you use the https://docs.walapay.io/reference/accountscontroller_getexternalaccountrequirements#/ endpoint to get the most up-to-date requirements (which may also differ by bank partner). Note that this endpoint will only return fields that are country/currency dependent; fields that are always required (as discussed in the notes above or as marked in the API reference) will not be included

Local Payments

This table shows only the fields that are not already marked as required in the API Reference or discussed in the notes above.

Bank CountryRequired Fields
United Arab Emirates (AED), Andorra (EUR), Austria (EUR), Belgium (EUR), Bulgaria (EUR), Switzerland (CHF), Cyprus (EUR), Czech Republic (CZK), Denmark (DKK), Estonia (EUR), Spain (EUR), Finland (EUR), France (EUR), Germany (EUR), Greece (EUR), Hungary (EUR), Croatia (EUR), Ireland (IE), Iceland (IS), Italy (EUR), Latvia (EUR), Liechtenstein (EUR), Lithuania (EUR), Luxembourg (EUR), Malta (EUR), Monaco (EUR), Netherlands (EUR), Norway (NOK), Portugal (EUR), Romania (RON), Slovakia (EUR), Slovenia (EUR), Saudi Arabia (SAR), Turkey (TRY), Poland (PLN)
  • IBAN
Australia (AUD)
  • BSB Number
  • Account Number
  • Account Holder Street Line 1
  • Account Holder City
  • Account Holder Postal Code
  • Account Holder State

Argentina (ARS)

Account Holder Tax Number:
  • Argentina's primary tax identification number is the CUIT (Clave Única de Identificación Tributaria). It is a unique 11-digit alphanumeric code
  • Account Number
  • Account Holder Tax Number
  • Account Holder Phone Number
  • Account Holder Street Line 1
Bangladesh (BDT)
  • Bank Code
  • Bank Name
  • Account Number
Bolivia (BOB)
  • Account Number
  • Tax Number (Business only)
  • Bank Name
Brazil (BRL)
  • PIX Code (PIX rail)
  • Bank Name (TED rail)
  • Account Number (TED rail)
  • Branch Code (TED rail)
  • Account Holder Tax Number (TED rail)
Canada (CAD)
  • Transit Number
  • Bank Code
  • Account Number
Chile (CLP)
  • Account Number
  • Account Holder Tax Number
  • Account Holder City
  • Bank Name
China (CNY)
  • Account Number
  • CNAPS Code
  • ID Number
Colombia (COP)
  • Account Number
  • Account Holder Tax Number
  • Account Holder Phone Number
  • Account Holder Street Line 1
  • Account Holder City
  • Bank Name

Costa Rica (CRC)

Account Holder Tax Number options:
  • Citizens: Uses the Cédula de Identidad, which is a 9-digit numeric format
  • Foreign Residents: Uses the DIMEX (Documento de Identidad Migratorio para Extranjeros), which has 11 or 12 numeric digits
  • Foreigners (Non-Resident): Uses the NITE (Número de Identificación Tributaria Especial), which is a 10-digit code
  • Businesses & Corporations: Uses your Cédula Jurídica, which is a 10-digit numeric or alphanumeric sequence
  • IBAN
  • Account Holder Phone
  • Bank Name
  • Account Holder Tax Number

Dominican Republic (DOP), Ecuador (USD)

Account Holder Tax Number:
  • Ecuador: 10 digit numeric found on the user's national ID

  • Account Number

  • Account Holder Tax Number

  • Account Holder Phone

  • Bank Name

Egypt (EGP)
  • IBAN
  • Account Holder Street Line 1
El Salvador (USD), Guatemala (GTQ), Honduras (HNL), Malaysia (MYR), Singapore (SGD)
  • Account Number
  • Account Holder Phone Number
  • Bank Name
South Africa (ZAR)

  • Account Number

  • Account Holder Phone Number

  • Account Holder Street Line 1

  • Bank Name

Ghana (GHS), Indonesia (IDR), Kenya (KES), South Korea (KRW), Philippines (PHP), Thailand (THB), Tanzania (TZS), Vietnam (VND)
  • Account Number
  • Bank Name
Hong Kong (HKD)
  • Account Number
  • Account Holder Street Line 1
  • SWIFT BIC
India (INR)
  • IFSC Code
  • Account Number
Jamaica (JMD)
  • Bank Code
  • Bank Name
  • Account Holder Street Line 1
  • Account Holder City
  • Account Number
  • Account Holder Phone Number
Japan (JPY)

  • Bank Code

  • Branch Code

  • Bank Name

  • Account Holder Street Line 1

  • Account Number

  • Account Holder Phone

Mexico (MXN)
  • CLABE Number
New Zealand (NZD)

  • Bank Code

  • Bank Name

  • Account Number

Nigeria (NGN)
  • NUBAN Code
  • Bank Name
Israel (ILS), Jordan (JOD), Pakistan (PKR)
  • IBAN
  • Bank Name

Peru (PEN)

Account Number:
  • A Peruvian bank account format requires the 20-digit CCI (Código de Cuenta Interbancario) for interbank transfers, which includes the bank's identification code and the 12-digit account number
Account Holder Tax Number:
  • The Tax Number is the 8-digit DNI (Documento Nacional de Identidad) for individuals and 11-digit RUC for businesses
  • Account Number
  • Account Holder Tax Number
  • Bank Name
Sri Lanka (LKR)
  • Bank Name
  • Account Number
  • Account Holder Street Line 1 (B2B only)
  • Account Holder Phone Number (B2B only)
  • Account Holder Tax Number (B2B only)
Sri Lanka (USD)
  • Bank Name
  • Account Number
  • Account Holder Street Line 1 (B2B only)
  • Account Holder Phone Number (B2B only)
  • Account Holder Tax Number (B2B only)
  • SWIFT BIC (B2B only)
Qatar (QAR)
  • IBAN
  • Account Holder Street Line 1
  • Account Holder Tax Number
  • Bank Name
Sweden (SEK)

  • IBAN

  • Account Holder Street Line 1 (B2B only)

  • Account Holder City (B2B only)

  • Account Holder Tax Number (B2B only)

United Kingdom (GBP)
  • Account Number
  • Sort Code
  • Account Holder Street Line 1
  • Account Holder City
  • Account Holder Tax Number (B2B only)
United States (USD)
  • Routing Number
  • Account Number
  • Account Holder Street Line 1
  • Account Holder City
  • Account Holder State
  • Account Holder Postal Code

SWIFT Payments

For SWIFT payments, you need to pass in the iban field for countries that accept IBAN or the accountNumber+ bicSwift combo for all other countries. The account holder address is also required.

External Digital Asset Wallets

These accounts are not created and managed by Walapay, but are instead existing digital asset wallets that belong to your customers (e.g., a MetaMask wallet for Ethereum that an Individual has for their own personal use).

Creation

📘

Network Selection

Note that in Sandbox, all chains will be converted to their testnet equivalent:

  • Polygon --> Polygon Amoy
  • Ethereum --> Ethereum Sepolia
  • Base --> Base Sepolia
  • Solana --> Solana Devnet
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/accounts/<customerId>' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
    "type": "EXTERNAL_DIGITAL_ASSET_WALLET",
    "isThirdParty": true,
    "currencyCode": "USDC",
    "digitalAssetWallet": {
        "address": "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
        "chain": "ETHEREUM"
    },
    "accountHolder": {
        "firstName": "Joseph",
        "lastName": "Fajagut",
        "address": {
            "countryCode": "PH" // Required for compliance with the Travel Rule
        },
        "type": "INDIVIDUAL"
    }
}'