Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.minisend.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Public — no API key needed. Safe to call from a frontend. On every call, this endpoint also expires stale pending sessions past their deadline and cross-checks settling sessions that have been in flight >2 minutes against the settlement provider.

​
Endpoint

GET https://merchant.minisend.xyz/api/merchant/checkout/{session_id}
No auth.

​
Path

​
session_id
string
required
Returned from POST /api/merchant/checkout. Starts with cs_.

​
Examples

curl https://merchant.minisend.xyz/api/merchant/checkout/cs_7f8a9b2c-1234-5678-abcd-ef0123456789

​
Response

{
  "session_id": "cs_7f8a9b2c-1234-5678-abcd-ef0123456789",
  "status": "completed",
  "amount_usdc": 25.00,
  "description": "Order #4821",
  "deposit_address": "0x1234567890abcdef1234567890abcdef12345678",
  "expires_at": "2026-04-13T14:30:00.000Z",
  "created_at": "2026-04-13T14:00:00.000Z",
  "amount_local": 3225.00,
  "exchange_rate": 129.00,
  "settlement_receipt": "SHQ1234ABC",
  "completed_at": "2026-04-13T14:08:22.000Z",
  "merchant": {
    "business_name": "My Store",
    "logo_url": null
  }
}
​
status
string
required
Current status. See lifecycle.
​
amount_usdc
number
required
USDC-equivalent. Customer may pay in USDC or USDT.
​
deposit_address
string
required
Accepts USDC (19 chains) and USDT (14 chains).
​
amount_local
number
Net local currency after the 1% fee. Present when status is "completed".
​
exchange_rate
number
USDC → local rate at settlement. Present when status is "completed".
​
settlement_receipt
string
Payout provider receipt (e.g., M-Pesa code). Present when status is "completed".
​
completed_at
string
ISO 8601. Present when status is "completed".
​
merchant
object
required
Display info.

​
Status lifecycle

pending → deposit_received → settling → completed
                                      → failed
pending → expired  (after 30 minutes)
StatusMeaning
pendingWaiting for the customer to send
deposit_receivedDetected on-chain; settlement initiated
settlingConversion + payout in progress
completedPayout delivered
failedFailed post-deposit — contact support
expiredNo deposit within 30 minutes

​
Polling

async function waitForPayment(sessionId, timeoutMs = 30 * 60 * 1000) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(
      `https://merchant.minisend.xyz/api/merchant/checkout/${sessionId}`
    );
    const session = await res.json();

    if (session.status === 'completed') return session;
    if (session.status === 'failed' || session.status === 'expired') {
      throw new Error(`Session ended: ${session.status}`);
    }

    await new Promise((r) => setTimeout(r, 3000));
  }

  throw new Error('Timed out');
}
Prefer webhooks over polling. Configure webhook_url in Settings to receive checkout.completed, checkout.failed, and checkout.expired events.