Create a new payment

post

https://sandbox-api.walapay.io/v1/payments/{customerId}

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

customerId

string

required

The ID of the customer that the payment is being made on behalf of

Body Params

referenceId

string

Optional reference ID (must be a valid UUID v4 or CUID). If provided, this will be used as the internal payment ID.

quoteId

string

Optional quote ID. If provided, the payment will use the rates and amounts from the quote. The quote must be used within 2 minutes of creation.

returnAddress

string

Optional return address. If provided, the payment will be returned to this address if it fails or is expired. Only available for stablecoin-sourced payments. For more information on refunds, see the documentation.

source

object

required

Source payment details.

destination

object

required

Destination payment details.

comment

string

Optional comment for the payment; this is internal to your team and not visible to the recipient.

reference

string

A payment reference message or remittance information to be included in a transaction (e.g., SWIFT, domestic wire, ACH payments).

For all rails, this field cannot have special characters. Only letters, numbers, spaces, dashes, and colons are allowed. It also should not mention crypto or digital assets (e.g., "USDC payout", "BTC settlement", "wallet top up", "ERC20 transfer").

paymentReason

string

enum

required

Reason for the payment. This is not visible to the beneficiary but is very important for compliance purposes, so please be sure to choose the reason that best fits the payment.

developerFee

object

The developer fee represents the amount you wish to reserve for your own account. 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: (sourceAmount - 1) * (1 - 0.01), where sourceAmount 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.

IMPORTANT: 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.

files

array of files

For compliance purposes only (please refer to the documentation for more information); recipient will not see these files.

Array of files related to the payment in data URI format.

Following the data-uri scheme i.e. data:image/[type];base64,[base_64_encoded_file_contents]

Minimum size: 200px x 200px.
Maximum file size: 5MB.

Valid file types: .pdf, .jpeg, .jpg, .png

originatingIp

string

The IP address (IPv4) the payment originates from (i.e. the party the payment is created on behalf of). Used for sanctions compliance screening; when omitted, the IP of the API caller is screened instead.

configurations

object

Optional configurations for the payment.

Headers

x-idempotency-key

string

required

Idempotency key; must be a valid UUID.

Responses

400

Bad request.

403

Forbidden - user does not have permission to create payment.

404

Customer not found.

201The payment has been successfully created.