Get Transaction Status

Poll the status of an on-ramp or off-ramp transaction. Use the transactionId returned from a checkout response.

GEThttps://api.zenpayz.com/payment/api/v1/on-ramp/transactions/:transactionId

Bearer · API key

GEThttps://api.zenpayz.com/payment/api/v1/off-ramp/transactions/:transactionId

Bearer · API key

Request

Headers

Header	Description
x-request-id OPTIONAL	Custom request ID for tracing

Public Endpoint

This endpoint does not require authentication headers.

Path Parameters

Parameter	Type	Description
transactionId REQUIRED	string	Transaction ID from checkout response

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "completed",
    "transactionType": "buy",
    "inAmount": 100,
    "outAmount": 0.00112,
    "sourceCurrency": "usd",
    "targetCurrency": "btc_bitcoin",
    "onramp": "moonpay",
    "paymentMethod": "creditcard",
    "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "transactionHash": null,
    "statusDate": "2026-03-11T04:50:00.000Z"
  },
  "message": "Transaction retrieved"
}

Response Fields

Parameter	Type	Description
transactionId OPTIONAL	string	Unique transaction identifier
status OPTIONAL	string	Current status (see table below)
transactionType OPTIONAL	string	buy or sell
inAmount OPTIONAL	number	Amount in source currency
outAmount OPTIONAL	number	Amount in destination currency
sourceCurrency OPTIONAL	string	Source currency ID
targetCurrency OPTIONAL	string	Destination currency ID
onramp OPTIONAL	string	Provider that processed the transaction
paymentMethod OPTIONAL	string	Payment method used
walletAddress OPTIONAL	string	Crypto wallet address
transactionHash OPTIONAL	string	Blockchain transaction hash (when available)
statusDate OPTIONAL	string	ISO 8601 timestamp of last status update

Transaction Statuses

Status	Description
pending	Transaction created, awaiting user action
processing	Payment is being processed
completed	Transaction completed successfully
failed	Transaction failed
expired	Transaction expired
refunded	Transaction was refunded

Error Responses

Code	HTTP	Message
UNAUTHORIZED	401	Invalid transaction ID
RAMP_TRANSACTION_FAILED	500	Failed to get on-ramp transaction
OFFRAMP_STATUS_FAILED	500	Failed to get off-ramp transaction

Examples

cURL

# On-ramp transaction
curl "https://api.zenpayz.com/payment/api/v1/on-ramp/transactions/txn_abc123"

# Off-ramp transaction
curl "https://api.zenpayz.com/payment/api/v1/off-ramp/transactions/txn_def456"

JavaScript

// Poll until completed or failed
async function pollTransaction(transactionId, type = 'on-ramp') {
  const maxAttempts = 60;
  const delayMs = 5000;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.zenpayz.com/payment/api/v1/${type}/transactions/${transactionId}`
    );
    const { data } = await response.json();

    if (data.status === 'completed') {
      console.log(`Completed: ${data.inAmount} ${data.sourceCurrency} → ${data.outAmount} ${data.targetCurrency}`);
      console.log(`Provider: ${data.onramp}, Hash: ${data.transactionHash}`);
      return data;
    }

    if (data.status === 'failed' || data.status === 'expired') {
      throw new Error(`Transaction ${data.status}`);
    }

    await new Promise(resolve => setTimeout(resolve, delayMs));
  }

  throw new Error('Polling timeout');
}

await pollTransaction('txn_abc123');

Python

import requests
import time

def poll_transaction(transaction_id, ramp_type="on-ramp", max_attempts=60, delay=5):
    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.zenpayz.com/payment/api/v1/{ramp_type}/transactions/{transaction_id}"
        )
        data = response.json()["data"]

        if data["status"] == "completed":
            print(f"Completed: {data['inAmount']} {data['sourceCurrency']} → {data['outAmount']} {data['targetCurrency']}")
            print(f"Provider: {data['onramp']}, Hash: {data['transactionHash']}")
            return data

        if data["status"] in ("failed", "expired"):
            raise Exception(f"Transaction {data['status']}")

        time.sleep(delay)

    raise Exception("Polling timeout")

poll_transaction("txn_abc123")

Next Steps

• Buy Checkout -- Create a buy checkout
• Sell Checkout -- Create a sell checkout