Step 3: Payments

Available Corridors

To see which corridors have been activated for your team, use the GET corridors endpoint or see the team section of the Walapay dashboard.

When opening a new corridor, it is common for the first few payments to be checked by our banking partner's compliance team, which may delay these payments momentarily. This security audit is relaxed once these initial payments are validated and processed.

Types

There are 5 types of payments:

Statuses

Payments of type PAYOUT, EXTERNAL, and INTERNAL can have the following statuses:

Two important notes:

1. Completed status: If the payment is to a bank account, we do not have visibility passed the receiving bank accepting the funds. If a customer cannot see their funds for a completed payment, they should contact their bank to understand why the funds have not yet been credited to their account.
2. Expired status: All payments created without a source.accountId in the payload will start with the AWAITING_FUNDS status. If the payment is not funded within 3 days of creation, it will be marked as EXPIRED (and any funds sent to it will expire). This is done for general housekeeping (so very old, unused payments do not stay open forever).

Funding

There are two ways payments can be funded. For detailed request/response examples of these two types of funding, visit the subpages (Fiat-to-Fiat, Fiat-to-Stablecoin, etc.).

With Source Account

The payment can include a source.accountId parameter in the payload that must be a virtual bank account or a virtual digital asset wallet. The starting status of a payment is PENDING, and the funds will be automatically pulled from this account. This scenario is best if you do not have your own banking or wallet provider.

Without Source Account

If the payment does not include a source.accountId, then the payment will have a starting status of AWAITING_FUNDS and the funds must be sent by the customer to the provided bank account or wallet address provided in the funding instructions object of the response. Note that payments created using this method will only be active for a short period of time (see quotes section below for more details). Exact cut offs can be found in the subpages (Fiat-to-Fiat, Fiat-to-Stablecoin, etc.)

FX

Source / Destination

By default, a payment guarantees a specific source and destination amount upon creation:

1. If you create a payment with 100 USDC as the source.amount / source.currencyCode and PHP as the destination.currencyCode, the POST /payments response will include the destination.amount of PHP the beneficiary will receive: 5838
2. If you instead create the payment with 5838 PHP as the destination.amount / destination.currencyCode, then the response will include 100 USDC as the source.amount and source.currencyCode

This allows you to know exactly how much will be required to send the payment and how much will arrive to the recipient. A limitation, however, is that you won't know what the source / destination amount pair will be until after you've created the payment. The solution is to create a quotes beforehand...

Quotes

If you need to be able to show the source and destination amount (and the exchange rate between the two currencies) to your user before the payment request is actually sent (e.g., they're on your app UI and want to know how much PHP they'll get if they send 100 USDC), include the createQuote parameter in the rate endpoint to receive a quoteId. Once a quote is created, you have 1 minute to include it in a POST /payments request (and it cannot be used for more than 1 payment).

📘

Quotes cannot be used for payments that have a source currency of MXN.

Developer Fees

📘

Developer Fees are only active for Stablecoin-to-Fiat and Stablecoin-to-Stablecoin payments.

To add your own fees on payments, you can use the developerFee object within the Payment payload. These fees will accumulate and can be sent to your account of choice (contact Walapay support to set this up) on a monthly basis.

This fee can be combination of a fixed amount and a variable percentage. Note that the fixed fee is always deducted before the variable fee is applied. Example: $1 Fixed with 0.01 variable fee will result in: (source.amount - 1) * (1 - 0.01), where the source.amount already includes the Walapay fees.

The fee is denominated in the source currency if that is a fiat currency, or in the fiat currency to which the source currency is pegged. If you are using a quote, the developer fee will be set to the quote's developer fee; you cannot set this field if you are using a quote.

Sandbox Behavior

1. Payments sent in Sandbox will not actually send to the intended account; the status will go straight to PROCESSING for payments with source.accountId and remain at AWAITING_FUNDS for payments without a source.accountId
2. The source.accountId's fundingInstructions is dummy data. Do not send any funds to the bank or wallet address provided
3. The exchange rates you see in Sandbox may be different than Production