Transactions

Understanding Transactions

UnblockPay's API enables seamless conversion between fiat currencies and stablecoins. Every transaction involves a sender and a receiver — which can be either a fiat source (bank account) or a crypto source (blockchain wallet).

The following transaction types are supported:

Fiat to Stablecoin (Pay-in) Stablecoin to Fiat (Payout) Stablecoin to Stablecoin (Wallet Transfer) Fiat to Fiat

For payment methods where UnblockPay cannot pull funds directly (such as wire transfers or crypto transfers), we provide sender_deposit_instructions with deposit addresses where the customer — or you acting on their behalf — initiates the transfer. Once the deposit is received, funds move to the specified receiver automatically, with no additional API calls required.

We support multiple stablecoins and fiat payment rails.

Transaction statuses

A payout transaction can be in one of the following status:

Status	Description
`awaiting_deposit`	UnblockPay is waiting to receive funds from the customer before processing the transfer. This state occurs only when awaiting customer deposits (such as crypto deposits).
`processing`	This indicates that UnblockPay has received your funds and is processing the payout to your customer.
`completed`	The payout has been completed successfully. The funds have been delivered to the specified destination.
`failed`	UnblockPay attempted the payment but received a failure notification. The funds have been returned to UnblockPay and will be refunded to the sender.
`refunded`	The funds have been returned to the original sender's account.
`cancelled`	The payout has been cancelled. Payouts can only be cancelled when in the `awaiting_deposit` state.
`error`	There was a problem preventing UnblockPay from processing this transfer. Manual intervention may be required to resolve the issue. Please contact our support team if you haven't already been contacted about this transfer.

Please note that a payout will always progress from awaiting_deposit → processing → completed . It can never go backwards.

A transaction can only be set to cancelled status from awaiting_deposit status by making a request to our PUT /transactions/{id} endpoint.

Sandbox mock IDs

To see a payout status in the sandbox environment, we have mocked payouts transactions to facilitate. You can easily test these scenarios by hitting our GET v1/transactions/{id} endpoint with the following IDs:

Status	Mocked transaction ID
`awaiting_deposit`	`00000000-0000-0000-0000-000000000000`
`processing`	`11111111-1111-1111-1111-111111111111`
`completed`	`22222222-2222-2222-2222-222222222222`
`failed`	`33333333-3333-3333-3333-333333333333`
`refunded`	`44444444-4444-4444-4444-444444444444`
`cancelled`	`55555555-5555-5555-5555-555555555555`
`error`	`66666666-6666-6666-6666-666666666666`

Transactions API endpoints

Here are the endpoints you'll need to list or get details a transaction:

GET v1/transactions/{id} — Get details and current status of a specific transaction
GET v1/transactions — List all transactions
PUT v1/transactions/{id} — Cancel a transaction (only available for awaiting_deposit status)

For the full schema and request/response details, see the API Reference.

Quick Start