Get checkout session status

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

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

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

import requests

res = requests.get(
    f"https://merchant.minisend.xyz/api/merchant/checkout/{session_id}"
)
session = res.json()

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
  }
}

string

required

Current status. See lifecycle.

number

required

USDC-equivalent. Customer may pay in USDC or USDT.

string

required

Accepts USDC (19 chains) and USDT (14 chains).

number

Net local currency after the platform fee. Present when status is "completed".

number

The USDC-to-local exchange rate at settlement. Present when status is "completed".

string

Payout provider receipt (e.g., M-Pesa code). Present when status is "completed".

string

ISO 8601. Present when status is "completed".

string

Present on USDC sessions. Which chain this payment settles to.

object

Present on USDC sessions off Base. Tracks the bridge that moves USDC from Base to your chosen chain.

Show properties

string

required

not_required on Base, since nothing bridges. not_started before the payment lands, then pending while it’s bridging, completed once it arrives, or failed if it needs a hand. A failed forward doesn’t lose anything — the USDC just sits on Base instead.

string

required

Same as settlement_chain.

string

The destination-chain transaction. Only there once status is completed.

object

required

Display info.

Show properties

string

required

string | null

required

Status lifecycle

Status	Meaning
`pending`	Waiting for the customer to send
`deposit_received`	Detected on-chain; settlement initiated
`settling`	Conversion + payout in progress
`completed`	Payout delivered
`failed`	Failed post-deposit — contact support
`expired`	No 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.

completed means the payment landed, not that bridging finished. On a USDC session off Base, check forward.status separately, or listen for checkout.forwarded.

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Get checkout session status

Endpoint

Path

Examples

Response

Status lifecycle

Polling

​Endpoint

​Path

​Examples

​Response

​Status lifecycle

​Polling

Endpoint

Path

Examples

Response

Status lifecycle

Polling