Get checkout session status

No API key needed, so it’s safe to call from a browser or app. Each time you call it, we also bring the session up to date. A pending session past its deadline is marked expired, and a session that has been settling for more than 2 minutes is checked with our payout partner.

Endpoint

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

Path

string

required

The ID you got back 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",
  "redirect_url": "https://yourstore.com/orders/4821/thanks?session_id=cs_7f8a9b2c-1234-5678-abcd-ef0123456789&status=completed",
  "merchant": {
    "business_name": "My Store",
    "logo_url": null
  }
}

string

required

Where the session is now. See status values.

number

required

The amount in USDC. Your customer can pay it in USDC or USDT.

string

required

Takes USDC or USDT on any of six networks.

number

What you received in local currency, after the platform fee. Only once status is "completed".

number

How much local currency 1 USDC was worth at payout. Only once status is "completed".

string

The payout receipt, such as an M-Pesa code. Only once status is "completed".

string

Date and time it completed, ISO 8601. Only once status is "completed".

string

Only on USDC sessions. The network this payment ends up on.

string | null

The full return URL, with session_id and status already added, or null if you didn’t set one. The status inside it always matches the status field above. See sending the customer back.

object

Only on USDC sessions going to a network other than Base. Tracks the move of your USDC from Base to the network you chose.

Show properties

string

required

not_required on Base, since nothing needs moving. Otherwise not_started before the payment arrives, pending while it’s moving, completed once it’s there, or failed if it needs our help. A failed move doesn’t lose anything. The USDC just stays on Base.

string

required

Same as settlement_chain.

string

The transaction ID on the destination network. Only once status is completed.

object

required

Your business details, for showing on a page.

Show properties

string

required

string | null

required

Status values

Status	What it means
`pending`	Waiting for your customer to pay
`deposit_received`	We’ve seen the payment and are getting it ready to convert
`settling`	Converting the money and sending your payout
`completed`	You’ve been paid
`failed`	The payment arrived but we couldn’t finish paying you out. Contact support
`expired`	Nothing was paid within 30 minutes

Checking repeatedly

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');
}

Webhooks are usually easier than checking over and over. Add your URL under Dashboard → Webhooks to get checkout.completed, checkout.failed, and checkout.expired sent to you.

completed means the payment arrived, not that your USDC has finished moving to another network. On a USDC session going somewhere other than Base, check forward.status too, or wait for checkout.forwarded.

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Get checkout session status

Endpoint

Path

Examples

Response

Status values

Checking repeatedly

​Endpoint

​Path

​Examples

​Response

​Status values

​Checking repeatedly

Endpoint

Path

Examples

Response

Status values

Checking repeatedly