Transaction Types & Statuses

Mercuryo transactions are composed of multiple linked operations. Each operation type has its own lifecycle. This page describes all transaction types, their statuses, and how they relate to each other.

How Transactions Are Identified

In Callbacks

Transactions are identified by the combination of type + payment_method fields.

`type`	`payment_method`	Description
`buy`	`card`	Purchase with a payment card
`buy`	`mobile_pay`	Purchase with Apple Pay or Google Pay
`buy`	`invoice`	Invoice Payment (APM, e.g., Revolut Pay)
`sell`	`card`	Sell to external card
`withdraw`	—	Crypto sent to user's wallet
`deposit`	—	Crypto received by Mercuryo

In API Polling

When using GET /v1.6/sdk-partner/transactions, transactions are returned as objects where the key is the type:

{
  "data": [
    {
      "buy": {
        "id": "0de85a1545a175145",
        "transaction_id": "0de85a15474d42563"
      }
    }
  ]
}

API polling type names:

Type	Description
`buy`	Purchase with card
`mobile_pay`	Purchase with Apple Pay / Google Pay
`buy_acquirer`	Invoice Payment (APM)
`sell`	Sell crypto for fiat
`withdraw`	Send crypto to user wallet
`deposit`	Receive crypto to Mercuryo wallet

Card Payment (Buy with Card)

Triggered when a user purchases crypto with a bank card.
On success, automatically creates a withdraw transaction to send crypto to the user.

Identify: Callback: type=buy, payment_method=card | API: type=buy

Status	Type	Description
`new`	Intermediate	Payment data entered, awaiting processing
`pending`	Intermediate	Card verification and 3D Secure in progress
`order_scheduled`	Intermediate	Payment authorized, awaiting KYC verification
`descriptor_failed`	Intermediate	Card verification check failed
`failed_exchange`	Intermediate	Exchange request failed
`paid`	Final	Transaction successfully completed
`order_failed`	Final	Declined by card issuer / acquirer
`cancelled`	Final	Cancelled (funds returned if charged)

State transitions:

From	To	Trigger
`new`	`pending`	card verification started
`new`	`order_failed`	bank system error
`pending`	`order_scheduled`	payment authorized, KYC required
`pending`	`descriptor_failed`	card verification check failed
`pending`	`failed_exchange`	exchange error
`pending`	`order_failed`	payment rejected
`pending`	`cancelled`	system cancelled
`order_scheduled`	`paid`	KYC passed or not required
`order_scheduled`	`failed_exchange`	exchange error
`order_scheduled`	`cancelled`	system cancelled
`descriptor_failed`	`cancelled`	system cancelled
`failed_exchange`	`cancelled`	system cancelled

Mobile Payment (Apple Pay / Google Pay)

Streamlined purchase flow using mobile payment systems.
On success, automatically creates a withdraw transaction.

Identify: Callback: type=buy, payment_method=mobile_pay | API: type=mobile_pay

Status	Type	Description
`new`	Intermediate	Payment data entered, awaiting processing
`pending`	Intermediate	Payment verification and processing
`order_scheduled`	Intermediate	Payment authorized, awaiting KYC
`failed_exchange`	Intermediate	Exchange request failed
`paid`	Final	Successfully completed
`order_failed`	Final	Declined by payment provider
`cancelled`	Final	Cancelled (funds returned if charged)

State transitions:

From	To	Trigger
`new`	`pending`	payment processing started
`new`	`order_failed`	bank system error
`pending`	`order_scheduled`	order queued
`pending`	`failed_exchange`	exchange error
`pending`	`order_failed`	payment rejected
`pending`	`cancelled`	system cancelled
`order_scheduled`	`paid`	KYC passed or not required
`order_scheduled`	`failed_exchange`	exchange error
`order_scheduled`	`cancelled`	system cancelled
`failed_exchange`	`cancelled`	system cancelled

Invoice Payment (APM)

Alternative payment methods (e.g., Revolut Pay, bank transfer).
On success, automatically creates a withdraw transaction.

Note: Status names differ between Callbacks and API Polling for this type.

Identify: Callback: type=buy, payment_method=invoice | API: type=buy_acquirer

Callback Statuses

Status	Type	Description
`payment_initiated`	Intermediate	Payment request created, redirect URL sent to user
`refund_in_progress`	Intermediate	Refund being processed
`completed`	Final	Successfully completed
`failed`	Final	Processing error
`cancelled`	Final	Cancelled (usually due to timeout)
`refunded`	Final	Money successfully refunded

State transitions (callbacks):

From	To	Trigger
`payment_initiated`	`completed`	successfully processed
`payment_initiated`	`failed`	processing error
`payment_initiated`	`cancelled`	system cancelled
`payment_initiated`	`refund_in_progress`	refund initiated
`refund_in_progress`	`refunded`	refund completed

API Polling Statuses

Status	Type	Description
`new`	Intermediate	Transaction created
`payment_received`	Intermediate	Provider received user's payment
`refund_in_progress`	Intermediate	Refund being processed
`completed`	Final	Successfully completed
`failed`	Final	Processing error
`cancelled`	Final	Cancelled
`refunded`	Final	Refunded

State transitions (API polling):

From	To	Trigger
`new`	`payment_received`	user completed payment
`new`	`failed`	processing error
`new`	`cancelled`	system cancelled
`payment_received`	`completed`	successfully processed
`payment_received`	`refund_in_progress`	refund initiated
`payment_received`	`cancelled`	system cancelled
`refund_in_progress`	`refunded`	refund completed

Sell

User sells crypto to receive fiat to their payment card.

Identify: Callback: type=sell | API: type=sell

Creates sell → user sends crypto → creates deposit → updates sell for payout. On failure: creates withdraw to return crypto.

Status	Type	Description
`new`	Intermediate	Sell request created (Phase 1: payout address shown; Phase 2: crypto received, preparing payout)
`pending`	Intermediate	Payout processing started
`succeeded`	Final	Payout completed
`failed`	Final	Payout failed (crypto returned to user)
`cancelled`	Final	Cancelled (crypto returned to user)

State transitions:

From	To	Trigger
`new`	`pending`	processing started
`pending`	`succeeded`	payout completed
`pending`	`failed`	processing error
`pending`	`cancelled`	system cancelled

Deposit

Service transaction created automatically when a user sends crypto for a sell operation.

Identify: Callback: type=deposit | API: type=deposit

Status	Type	Description
`pending`	Intermediate	Awaiting blockchain confirmations
`completed`	Final	Deposit confirmed

State transitions:

From	To	Trigger
`pending`	`completed`	deposit verified

Withdraw

Service transaction created automatically in two cases:

After a successful buy (including buy+spend) — to send purchased crypto to the user's wallet.
After a failed sell (any variant) — to return crypto to the user.

Identify: Callback: type=withdraw | API: type=withdraw

Status	Type	Description
`new`	Intermediate	Withdrawal created, awaiting processing
`pending`	Intermediate	Verification in progress
`completed`	Final	Crypto successfully sent to blockchain
`failed`	Final	Withdrawal failed
`cancelled`	Final	Cancelled by system

State transitions:

From	To	Trigger
`new`	`pending`	processing started
`pending`	`completed`	successfully processed
`pending`	`failed`	processing error
`pending`	`cancelled`	system cancelled

Transaction Relationships

On-Ramp (buy / mobile_pay / buy_acquirer)
  └─ On success → creates withdraw (send crypto to user)

Off-Ramp (sell, payment_method=card)
  ├─ Phase 1: sell created (payout address shown)
  ├─ Phase 2: deposit created (user sends crypto)
  ├─ Phase 3: sell updated for payout
  └─ On failure → creates withdraw (return crypto to user)

For Spend Card transaction types (buy+spend, fiat_deposit+spend_card_topup, sell+spend_card_topup, sell+spend_card_open), see Spend Card → Transaction Types.

Callbacks & Webhooks

User Pre-Authorization