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

Depending on the country, when an external bank account is created, it may require a very short (~10 seconds) validation by our banking provider before it is useable. In this scenario, the response of the request will include a status of PENDING for the account. Through the use of our webhooks, you will receive an update when the account has been APPROVED; at which point, you will be able to send payments to this account.

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
    "bank": {
      "name": "U.S. Bank",
      "accountNumber": "123456789",
      "routingNumber": "021000089",
      "type": "CHECKING",
      "address": {
        "streetLine1": "425 Walnut Street",
        "city": "Cincinnati",
        "stateOrProvince": "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": "Union Bank of the Philippines",
      "accountNumber": "1234567890",
      "type": "SAVING",
      "address": {
        "streetLine1": "Ayala Avenue",
        "city": "Makati",
        "stateOrProvince": "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

The sections below will show you the country-specific requirements for both local and SWIFT payments. Note that only the active corridors outlined in the countries & rails page are included.

Fields required to receive Local payments

This table shows only the fields that are not already marked as required in the API Reference. A few notes:

1. Account Holder email: Emails are required for all countries. However, this is purely for record keeping purposes. Emails will not be sent to the account holder. If you do not have the account holder's email, you may put an email that belongs to the sender (i.e., your customer)
2. Account Holder address: The address cannot be a PO Box or PMB. This will cause issues when attempting to send a payment.
3. First/Last or Business name: If the account holder is an individual, you will always need to provide the first and last name. If the account holder is a business, you will always need to provide the business name
4. Bank names: Some countries require the bank name to be spelled exactly. Please use the following document to see which countries have this requirement. If you do not find a country on this list, it means the bank name does not need a specific spelling (i.e., it won't matter if you write "Citibank NA" or "Citi", as long as it's obvious to a human what bank you're referring to)

📘

API Endpoint

If you would like to receive this data by API, please use the /payments/requirements/external-bank-accounts endpoint. We recommend you use this for the most up-to-date requirements and for the following scenarios:

1. If the table below has the country marked as having differences between providers, the endpoint will return the details for the provider assigned to you
2. If the country in question has more than one accepted currency (USD in CN), the endpoint will return the correct details depending on which currency code you input
3. If the bank country code and account holder country code do not match (the below table assumes these are the same), the endpoint will return the correct details no matter the combination (i.e., China-based bank account with a Nigerian account holder)

Fields required to receive International Wires (SWIFT)

When you send an international wire, you'll need all the information for a local transfer (see above), plus:

1. SWIFT/BIC code: A unique identifier for the recipient's bank (8-11 characters).
2. IBAN number (not all countries, see list below): An international bank account number (up to 34 characters).

A SWIFT code ensures the transfer reaches the correct bank. An IBAN identifies the specific account within that bank. Countries that do not require an IBAN will use another field as the account specifier (e.g., CLABE in Mexico).

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,
    "digitalAssetWallet": {
      "address": "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
      "chain": "ETHEREUM"
    },
    "accountHolder": {
      "firstName": "Joseph",
      "lastName": "Fajagut",
      "address": {
        "countryCode": "PH"
      },
      "type": "INDIVIDUAL"
    }
  }'

Account Holder Country Code

We require the account holder country code for two reasons:

1. To abide by the Travel Rule. The Travel Rule requires financial institutions to share basic information about their customers when sending funds over a certain amount.
2. To ensure onramps work as expected. If you are trying to onramp stablecoins to a digital asset wallet, it is very important that the account holder country code matches the currency of the payin (e.g., BR for BRL).