Step 3: Payments

Available Corridors

To see which corridors have been activated for your team, use the GET https://docs.walapay.io/reference/paymentscontroller_getcorridors#/ endpoint.

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.

All payments sent to businesses must include a document reference within the request (e.g., the ID of the invoice).

Statuses

Payments can have the following statuses:

Status	Definition
Awaiting Funds	Payment does not have a source account and is waiting for the end-user to send funds. Note that a payment with this status expires after a certain amount of time (see more below).
Pending	The transfer has the required funds and is ready to be initiated.
Processing	Payment instructions have been delivered to the sending bank. If a foreign currency exchange is involved, the trade will be executed before the bank can release the transfer.
Sent	The funds have been released and are on the way to the receiving bank.
Completed	The expected delivery date of this transfer has been met. If you cannot confirm receipt, please contact our Support team for more information. Note: This is triggered when we receive a notification from the recipient's bank telling us that they have received the funds. We do not have any visibility into when the recipient bank credits these funds to the recipient's account.
Canceled	The customer has reached out to our Support team and requested a cancellation; we stopped the transfer and did not transfer funds. No further action is required.
Failed	We were unable to start or complete the transfer. Our team has been alerted and will investigate the issue. Feel free to contact our Support team for more information.
Refunded	We have sent back the funds to to funding account. Please get in touch with our Support team for more details.
Scheduled	All required information has been collected and verified, and the payment will be initiated to meet your chosen delivery date. (Coming soon)
In Review	Under compliance review. We'll reach out with more information. (Coming soon)

Types

There are 4 types of payments:

Type	Definition
PAYIN	Funds are sent from an External Account to a Virtual Account (e.g., from an external bank account to a virtual bank account). Think of this as a deposit
PAYOUT	Funds are sent from a Virtual Account to an External Account (e.g., from a virtual bank account to an external digital asset wallet)
INTERNAL	Funds are sent from a Virtual Account to another Virtual Account (e.g., from a virtual bank account to a virtual digital asset wallet)
EXTERNAL	Funds are sent from an External Account to another External Account (e.g., from an external bank account to an external digital asset wallet).

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.

Payments statuses will be:

Successful payment: Pending → Processing → Sent → Completed
Unsuccessful payment: Pending → Processing → Sent → Failed → Refunded

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 (i.e., there is a time limit for the customer to send the funds). Exact cut offs can be found in the subpages (Fiat-to-Fiat, Fiat-to-Stablecoin, etc.)

Payments statuses will be:

Successful payment: Awaiting Funds → Pending → Processing → Sent → Completed
Unsuccessful payment: Awaiting Funds → Pending → Processing → Sent → Failed → Refunded

Quotes

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

A quote ID can be included in the payment to ensure a rate seen before the payment is made. To use this functionality, include the createQuote parameter in the rate endpoint to receive the quoteId, which you can then include in the payment itself.

Quotes can only be used within 1 minute of creation and cannot be used more than once.

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

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
The source.accountId's fundingInstructions is dummy data. Do not send any funds to the bank or wallet address provided
The exchange rates you see in Sandbox may be different than Production