Overview [READ FIRST]

To integrate Walapay's API into your codebase, there are three key concepts to understand:

1. What are Customers and Associated Persons?
2. What are Accounts?
3. What are Payments?

1. What are Customers and Associated Persons?

Customers and Associated Persons are the building blocks that allow you to represent and manage your users in the Walapay ecosystem. We provide any type of setup you require for your users, whether they are individuals or businesses with multiple legal entities.

Definitions

Customers: A customer is the actual individual or business that must go through Walapay's KYC/KYB process to access the APIs (unless you have a reliance agreement set up).

Associated Persons: These are the individuals who own at least 25% of a business or have sufficient control within the company to make transaction decisions. They will also need to go through KYC.

Examples

1. Global C2C Remittance Application: Imagine your team is building an application that allows individual users to send money to other individuals across the world. When a user signs up for your app, you will create a Customer for them in Walapay that includes all the user's information required for KYC verification.

2. Global B2B Payments Application: Imagine your team is building an application that allows international businesses of any size and structure to pay other businesses across the world. When you are onboarding a new business onto your platform, you would create 1 or more Customers in Walapay (e.g., if the business is a global conglomerate with a branch in the US, the UK, and Japan, you would create a Customer for all three). For each Customer, 1 or more Associated Persons will have to be linked to it.

2. What are Accounts?

While the Customer represents the actual person or business you onboard into the Walapay ecosystem, Accounts are the actual structures that hold their money. These come in two flavors: External and Virtual.

Virtual Accounts

These accounts are created and managed by Walapay on behalf of your Customer (the account is under the customer's name). This means that you can start receiving and holding money on behalf of a Customer without requiring them to have any type of pre-existing fiat or digital asset account.

Virtual Bank Account (Fiat): These come in 10 different currencies (USD, EUR, GBP, CAD, AUD, NZD, SGD, HKD, CNH, and MXN). Virtual Banks Accounts can be used to collect money via bank transfer (local rails and wires), hold funds, and make payments from. They are dedicated to the Customer and named as such.

Virtual E-wallet Account (Fiat) - Coming Soon: Provided by Walapay, allowing Customers to hold, send, and receive fiat currency. They offer enhanced flexibility for small transactions and seamless integrations with local payment rails.

Virtual Digital Asset Wallet (Stablecoins): These wallets enable Customers to collect and hold stablecoins (e.g., USDC, USDT), as well as convert stablecoins into other currencies, without ever needing to worry about private keys and digital signatures. You may open one Virtual Digital Asset Wallet per blockchain type (ie. EVM, Solana, etc.).

External Accounts

These accounts are not managed by Walapay. Instead, they are pre-existing accounts that are owned by your Customer.

External Bank Account (Fiat): Traditional bank accounts (e.g., Citibank, HSBC, BNP Paribas) that are not provided by Walapay but are integrated into the system for seamless fund transfers.

External E-wallet Account (Fiat): Third-party e-wallets, such as G-Cash, PayPal, or Alipay.

External Digital Asset Wallet (Stablecoins): Third-party cryptocurrency wallets like MetaMask or Coinbase Wallet for Ethereum and Phantom for Solana. These wallets require the Customer to manage their own private keys and security.

Examples

1. Global C2C Remittance Application: Building on the example from the previous section, imagine one of your users (John) needs to send money to someone that has not downloaded your app (his grandfather in the Philippines, who isn't even sure what a smartphone is). John can input his grandfather's bank account details to create an External Bank Account. This account will be linked to John's Customer object, but is marked as being owned by a third party (John's grandfather).

2. Global B2B Payments Application: Building on the example from the previous section, imagine one of your business users just opened a branch in Mexico and needs to be able to collect MXN. You can open a Virtual Bank Account for them and associate it to their Customer object. With that, they can start receiving payments from any of their Mexican clients.

3. What are Payments?

Your users (i.e., Customers) are onboarded and Virtual / External Accounts have been created. There's only one thing left to do...start moving money! There are three main questions to ask yourself when creating a payment:

1. Are funds being pulled automatically (through Virtual Accounts) or will they require the user to initiate a transfer from their External Account? If the former, you will include an Account ID in the source object of the Create Payment request. If the latter, you won't include an Account ID and the response object will include funding instructions to be shared with your user.

2. Are funds being sent to an Account a Customer owns (First Party) or will they go to an Account they don't own (Third party)? This has implications on available coverage. The destination of a payment is always represented by an Account ID (i.e., the ID of the Virtual or External Account).

3. How will funds be converted?
   1. Fiat to Fiat (e.g., USD to PHP)
   2. Fiat to Stablecoin (e.g., MXN to USDC)
   3. Stablecoin to Fiat (e.g., USDT to VND)
   4. Stablecoin to Stablecoin (e.g., USDC to EURC)

Examples

1. Global C2C Remittance Application: John is ready to send money to his grandfather's bank account. When John signed up for your application, a Virtual Bank Account was created for him and he has some money there. On your UI, he selects his grandfather's bank account and sends $100, which needs to be converted in PHP. The Create Payment request will include $100 as the source amount and John's Virtual Bank Account as the source Account ID. Funds will be automatically pulled from this account, converted to PHP, and sent to his grandfather's External Bank Account.

2. Global B2B Payments Application: The Mexican entity that belongs to one of your business users needs to send money to a supplier in Indonesia. They don't have a Virtual or External Bank Account that holds IDR. They do, however, have an External Digital Asset Wallet with USDC in it. So, they create an External Bank Account to represent their supplier's bank account, and then they send a Create Payment request that does not include a source Account ID. In the response of the API, they receive funding instructions for where to send the USDC they have. They send their stablecoins to this deposit address, it gets converted to IDR, and lands in the supplier's bank account.