Skip to main content
The GET /payments status endpoint can be polled to retrieve the full scope and current status of a payment using its unique payment_id. This endpoint supports fiat onramps, centralized exchange withdrawals, and cross-chain swaps initiated through the API or the Payments SDK widget. During the payment lifecycle, the status response provides essential funding information. Once a payment is funded, the predefined onchain steps execute automatically. Note that the JSON response object returned by GET /payments and POST /payments/confirm share the same structure and both represent the payment’s current status.

​
Funding a payment

A payment is initiated onchain once the OTW deposit address on the specified network holds a token balance greater than or equal to the input amount set in the quote. Sending tokens to this deposit address is referred to as a deposit. Any address can perform the deposit to fund the payment. Once a fiat-to-crypto onramp, centralized exchange withdrawal, or cross-chain swap is confirmed using the POST /payments/confirm endpoint, the API returns a payment status object with a status of PENDING. Once a payment is pending, it can be funded. Funding must occur before the quote expires. The payment expires if it is not funded before the initiate_fund_by datetime detailed in the status object.

​
Funding an onramp vs funding a swap

Fiat onramps are funded onchain automatically by the provider once a user completes the checkout on the provider’s page. A swap must be funded by transferring tokens to the deposit address onchain. For most use cases of swaps, the user transfers the input token to the deposit address from their own wallet. However any wallet may fund a payment. Developers can find the specific details for funding a payment by viewing the next_instruction object.

​
Next instruction

The JSON response object returned from the status and confirm endpoints contains a next_instruction object while the payment status is PENDING. This object details the next instruction required to execute the payment. Type The next_instruction.type value can be ONRAMP for fiat onramp payments or TRANSFER_IN for swaps. Funding page URL for fiat onramps The next_instruction.funding_page_url value is a unique URL. The URL redirects to a fiat onramp provider’s checkout page (i.e. Stripe, Moonpay). On this page, the user confirms their fiat payment information. Deposit information The next_instruction.deposit_info value is an array of objects. This information is used to fund a payment.
  • deposit_token The token to send to the deposit address in ${chain}:${token_address} format.
  • deposit_amount The amount of the token to send to the deposit address.
  • deposit_address The onchain deposit address (OTW).
  • deposit_chain Name of the chain on which to perform the deposit.
Example next_instruction.deposit_info: 
[{
  "deposit_token": "base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "deposit_amount": "53.26",
  "deposit_address": "0x39bd1CfcF898A3a3d1e6EFD33e1F65499e6326a9",
  "deposit_chain": "base"
}]
Pitfalls Note that EVM wallets have identical addresses on every EVM chain. The deposit is required to be done only on the chain specified in the deposit information. Depositing to the OTW address on the wrong chain will not execute a payment and is to be avoided.

​
Payment Statuses

The status property in the JSON response object is a string indicating the present status of the payment. Each of the following statuses can be returned for an onramp or swap payment.

​
Pending

The PENDING status is the inital state of a confirmed payment. This state indicates that the payment is ready to be funded. The specified onchain steps begin executing once the OTW (deposit address) is issued the proper amount of tokens on the proper chain. See funding a payment above for more details and funding examples below.

​
Expired

The EXPIRED status indicates that the payment was not funded before the initiate_fund_by datetime detailed in the status response object. A payment can be safely abandoned if it becomes EXPIRED, before it is funded, in favor of a new quote. If an EXPIRED payment is funded, the owner wallet address can retry the payment with a new quote or withdraw the assets from the OTW to the owner address. Withdrawal requires creation of an EIP-712 signature which the API can use to execute the transfer. For more information on withdrawals and payment recoveries see the Payment API Errors & Recoveries guide.

​
Complete

The COMPLETE status indicates that a payment has successfully reached the originally intended final onchain step detailed in the route object of the status response. There are no other possible states for the payment to change to once it has reached COMPLETE.

​
Withdrawn

The WITHDRAWN status indicates that the funding amount deposited to the OTW has been successfully transferred out of the deposit address following execution of a withdrawal request. There are no other possible states for the payment to change to once it has reached WITHDRAWN.

​
Tainted

The TAINTED status indicates that an onchain address associated with a payment request is recognized as a sanctioned address. Tainted payments cannot be completed or retried.

​
Funding Examples

Both fiat onramps and swaps are funded in the same manner. Each unique payment has a unique onchain deposit address that begins execution of the payment steps once it is funded. Any subsequent onchain actions are performed automatically using predefined workflows. The user does not need to be mindful of gas tokens, bridges, or swaps that occur during the payment lifecycle. The result of a payment is that a destination wallet address holds, at minimum, the quoted amount of a destination token.

​
Swap

After the user indicates their input token amount, chooses a quote, and the payment is confirmed, the deposit can be performed. An app can prompt the user to transfer tokens in their wallet to the deposit address. Also, any funder wallet can perform the deposit.

​
Fiat onramp

Just like a swap, the user indicates the amount that they want to spend, chooses a quote, and the funding process begins. The user provides payment details via the next instruction’s funding_page_url. Once the checkout is completed, the onramp provider automatically funds the deposit address on the proper chain.