api

Transactions API

The Transactions API covers the complete payment lifecycle: creating checkout sessions, querying transaction status, and verifying blockchain confirmations.

Updated: 3/9/2026

The Transactions API covers the complete payment lifecycle: creating checkout sessions, querying transaction status, and verifying blockchain confirmations.

Payment Flow Overview

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│ Your Server │───>│ Create       │───>│ Customer     │───>│ Blockchain    │
│             │    │ Checkout     │    │ Pays on      │    │ Confirms      │
│ POST api.php│    │ Session      │    │ Payment Page │    │ Transaction   │
└─────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
                         │                                        │
                         │ payment_url                             │
                         ▼                                        ▼
                   ┌──────────────┐                         ┌───────────────┐
                   │ Redirect     │                         │ Webhook POST  │
                   │ Customer     │                         │ to Your Server│
                   │ to pay.php   │                         │               │
                   └──────────────┘                         └───────────────┘

Your server calls create-checkout-session with the payment amount and currency.
You receive a payment_url and redirect the customer to it.
The customer selects a cryptocurrency, scans the QR code, and sends payment.
QuantaPay monitors the blockchain and waits for confirmations.
Once confirmed, QuantaPay sends a webhook to your server and/or redirects the customer.

create-checkout-session

Create a new payment session. Returns a payment URL to redirect your customer to.

Request

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=create-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "price=49.99" \
  -d "currency=USD"

Parameters

Parameter	Type	Required	Description
`price`	number	Yes	Payment amount in the specified currency.
`currency`	string	Yes	ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`).
`order_id`	string	No	Your internal order ID for reference.
`redirect`	string	No	URL to redirect the customer after successful payment.
`cancel_url`	string	No	URL to redirect the customer if they cancel.
`note`	string	No	Internal note attached to the transaction.
`items`	JSON string	No	Array of line items (see below).
`customer`	JSON string	No	Customer information object.
`signature`	string	No	HMAC-SHA256 signature for tamper protection.
`timestamp`	integer	No	Unix timestamp (required if signature is provided).
`external_reference`	string	No	Encrypted reference from WordPress plugin.
`plugin`	string	No	Source plugin identifier (e.g., `woo`, `edd`).

Items Format

[
  {
    "name": "Product Name",
    "qty": 2,
    "price": 24.99,
    "image": "https://example.com/product.jpg"
  }
]

Maximum 50 items per session.
name: Max 200 characters.
image: Must be HTTP or HTTPS URL, max 500 characters.

Response

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "payment_url": "https://cloud.quantapay.app/pay.php?session=cs_a1b2c3d4e5f6a1b2c3d4",
    "expires_at": "2026-03-08T11:00:00+00:00"
  }
}

session_id: Unique session identifier (format: cs_ + 24 hex characters).
payment_url: URL to redirect the customer to complete payment.
expires_at: ISO 8601 timestamp. Sessions expire after 60 minutes.

Error Responses

Message	Cause
`Missing required fields: price, currency`	`price` is 0/missing or `currency` is empty.
`Invalid signature`	HMAC signature verification failed.
`Request expired`	Timestamp is more than 5 minutes from server time.
`Failed to create checkout session`	Database error.

get-checkout-session

Query the current status of a checkout session.

Request

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "session_id=cs_a1b2c3d4e5f6a1b2c3d4"

Parameters

Parameter	Type	Required	Description
`session_id`	string	Yes	The checkout session ID (starts with `cs_`).

Response

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "status": "paid",
    "price": 49.99,
    "currency": "usd",
    "order_id": "ORD-12345",
    "created_at": "2026-03-08T10:00:00+00:00",
    "expires_at": "2026-03-08T11:00:00+00:00",
    "paid_at": "2026-03-08T10:15:23+00:00"
  }
}

Session Statuses

Status	Description
`active`	Session is open and waiting for payment.
`paid`	Payment has been received and confirmed on the blockchain.
`expired`	Session expired without receiving payment (after 60 minutes).
`cancelled`	Session was cancelled before payment was received.

get-transactions

Query a paginated list of transactions. Useful for reconciliation and reporting.

Request

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transactions" \
  -d "api-key=YOUR_API_KEY" \
  -d "pagination=0"

Parameters

All parameters are optional:

Parameter	Type	Description
`pagination`	integer	Page number (0-indexed). Each page returns up to 100 transactions.
`search`	string	Search by transaction ID, hash, amount, or description.
`status`	string	Filter by status: `C` (completed), `P` (pending), `X` (underpaid), `E` (expired).
`cryptocurrency`	string	Filter by cryptocurrency code (e.g., `btc`, `eth`).
`date_range`	array	Date range filter as a two-element array: `date_range[0]=2026-01-01&date_range[1]=2026-03-01`.
`checkout_id`	string	Filter by checkout/payment button ID.

Response

Returns an array of transaction objects:

{
  "success": true,
  "response": [
    {
      "id": "123",
      "title": "Payment #ORD-12345",
      "description": "",
      "from": "0xCustomerAddress...",
      "to": "0xYourAddress...",
      "hash": "0xTransactionHash...",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "",
      "creation_time": "2026-03-08 10:00:00",
      "status": "C",
      "webhook": "1",
      "vat": ""
    }
  ]
}

Transaction Statuses

Code	Status	Description
`C`	Completed	Payment confirmed on the blockchain.
`P`	Pending	Waiting for payment or blockchain confirmation.
`X`	Underpaid	Payment received but amount was less than required.
`E`	Expired	Payment window expired without sufficient payment.
`R`	Refunded	Payment has been refunded.

get-transaction

Get details of a single transaction by ID.

Request

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction_id=123"

Parameters

Parameter	Type	Required	Description
`transaction_id`	integer	Yes	The transaction ID.

Response

Returns a single transaction object (same format as get-transactions).

check-transaction

Manually trigger a blockchain confirmation check for a specific transaction.

Request

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=check-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction=TRANSACTION_JSON"

Parameters

Parameter	Type	Required	Description
`transaction`	JSON string	Yes	The transaction object to check (as returned by `get-transaction`).

Response

Returns the updated transaction object with current confirmation status. If the required number of confirmations is reached, the transaction status changes to C (completed).

Note: This function is typically not needed in normal operation. QuantaPay automatically checks confirmations via its cron system. Use this only if you need to force an immediate check.