Webhook events

Here’s every event we send for checkout sessions, what’s in each one, and how to handle them.

Event	Sent when
`checkout.pending`	We’ve seen the payment and are working on it
`checkout.completed`	You’ve been paid. The money is yours
`checkout.failed`	The payment arrived but we couldn’t finish paying you out
`checkout.expired`	Nothing was paid within 30 minutes
`checkout.forwarded`	If you keep USDC: it arrived on the network you chose
`settlement.forward_failed`	If you keep USDC: moving it to your chosen network got stuck
`settlement.swap_failed`	If you keep USDC: converting a USDT payment to USDC got stuck

checkout.pending

Sent once, as soon as we see the payment arrive. It isn’t a confirmation. It’s an early signal so your customer isn’t left staring at a blank screen while we convert or move the money.

{
  "event": "checkout.pending",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "amount_expected_usdc": 25.00,
  "amount_received_usdc": 25.00,
  "deposit_chain": "ARB",
  "deposit_tx_hash": "0x9f2c...",
  "deposit_token": "USDC",
  "settlement_mode": "fiat",
  "status": "deposit_received",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always checkout.pending.

string

The network the payment came in on.

string

The blockchain transaction ID of the payment.

string

USDC or USDT, whichever your customer paid with.

string

required

Always deposit_received.

This is not checkout.completed. The payment could still fail. Tell your customer “we’ve seen it, hang on”, but don’t hand over goods on this alone.

checkout.completed

You’ve been paid and the money is yours, either as local currency in your account or as USDC in your Minisend wallet.

{
  "event": "checkout.completed",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "amount_expected_usdc": 25.00,
  "amount_received_usdc": 25.00,
  "amount_matched": true,
  "deposit_chain": "BASE",
  "deposit_tx_hash": "0x9f2c...",
  "deposit_token": "USDC",
  "settlement_mode": "fiat",
  "amount_local": 3225.00,
  "currency": "KES",
  "exchange_rate": 129.00,
  "receipt": "SHQ1234ABC",
  "status": "completed",
  "completed_at": "2026-04-13T14:32:00Z",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always checkout.completed.

string

required

Use it together with event to spot repeats. See best practices.

string

Your reference, if you set one.

number

required

The amount you asked for. This isn’t always what arrived. See amount_received_usdc.

number

required

The amount you asked for. Same as amount_usdc. Compare it with amount_received_usdc.

number

What your customer actually sent. Use this one in your books, not amount_usdc.If a customer sends a little more or less than you asked for, we still pay you out for what they sent, so their money isn’t stuck. That means a completed payment can show an amount_usdc you never received.

boolean

false when the amount received was more than $0.01 away from what you asked for. Take a look at these: the payout is real, but it isn’t the amount you quoted.

string

The network the payment came in on.

string

The blockchain transaction ID of the payment.

string

USDC or USDT, whichever your customer paid with.

string

required

fiat or usdc. Always present. A usdc message has fee_usdc, amount_usdc_net, settlement_chain, and forward_required instead of amount_local and exchange_rate.

number

USDC only. The platform fee taken from the payment.

number

USDC only. What you actually got: the amount received minus the fee.

string

USDC only. The network your USDC is on, or is being moved to.

boolean

USDC only. true when your USDC still has to be moved to settlement_chain.We send checkout.completed before that move starts, so you hear about the payment as soon as possible. When this is true, wait for checkout.forwarded before treating the money as arrived on your chosen network.

number

Local currency only. What you received after the platform fee.

string

required

KES, NGN, GHS, or UGX for local currency payouts. USDC if you keep USDC.

number

Local currency only. How much local currency 1 USDC was worth at payout.

string

required

For local currency, the payout receipt (an M-Pesa code, for example). For USDC, the transaction ID of your customer’s payment.

string

required

Always completed.

string

required

Date and time, ISO 8601.

string

required

Date and time, ISO 8601.

When this arrives

It depends on how you get paid:

How you’re paid	When it arrives	What it confirms
In USDC	Seconds after the payment is confirmed	The payment is yours
In local currency	Minutes, once the payout lands	The money is in your account
Either, when your customer pays in USDT	30 to 60 seconds later than above, for the conversion	Same as above

Whichever applies, by the time you get this event the payment can’t be reversed, and it’s safe to treat as final.

checkout.failed

The payment arrived but we couldn’t finish paying you out. This is rare.

{
  "event": "checkout.failed",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "currency": "KES",
  "status": "failed",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always checkout.failed.

string

required

string

number

required

The amount you asked for. If we’d already matched a payment to this session, amount_received_usdc shows what was actually sent.

string

required

string

required

Always failed.

string

required

Send the session_id to support and we’ll sort it out. Your customer’s money is not lost.

checkout.expired

Nobody paid within 30 minutes. Use this to mark the order as abandoned.

{
  "event": "checkout.expired",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "currency": "KES",
  "status": "expired",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always checkout.expired.

string

required

string

Use this to mark the matching order as abandoned.

number

required

The amount that was never paid.

string

required

string

required

Always expired.

string

required

Expired sessions cost you nothing. We only charge a fee on completed payments.

checkout.forwarded

Only if you keep USDC on a network other than Base. Your USDC has arrived on the network you chose.

{
  "event": "checkout.forwarded",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "settlement_chain": "ARB",
  "forward_tx_hash": "0x9f2c...",
  "status": "completed",
  "completed_at": "2026-04-13T14:08:22Z",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always checkout.forwarded.

string

required

string

required

The network your USDC arrived on.

string

required

The transaction ID on that network.

If the move fails, you get settlement.forward_failed below instead. Your USDC is safe on Base either way. To check without waiting for an event, look at forward.status on the checkout session.

settlement.forward_failed

Only if you keep USDC. Your money didn’t make it to the network you chose, and it needs our help to get there. Your customer’s payment isn’t affected: they paid and you were credited. This is only about moving your own USDC between networks.

{
  "event": "settlement.forward_failed",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "settlement_mode": "usdc",
  "settlement_chain": "ARB",
  "funds_on_chain": "BASE",
  "status": "completed",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always settlement.forward_failed.

string

required

Where the money was meant to go.

string

required

Where it is right now. Always Base, because the money never left.

We only send this once we’re sure the move won’t finish by itself, never on a first hiccup. Until then, treat it as still on its way. Send the session_id to support and we’ll get it moving again.

settlement.swap_failed

Only if you keep USDC, and only when your customer paid in USDT. We couldn’t convert their USDT to USDC, so for now you’re holding USDT on the network they paid on, instead of the USDC you expected.

{
  "event": "settlement.swap_failed",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "settlement_mode": "usdc",
  "settlement_chain": "BASE",
  "funds_on_chain": "ARB",
  "funds_token": "USDT",
  "status": "completed",
  "created_at": "2026-04-13T14:00:00Z"
}

string

required

Always settlement.swap_failed.

string

required

The network your customer paid on. That’s where the money is now.

string

required

The coin you’re holding: USDT, not the USDC you expected.

This always comes after checkout.completed, because your customer’s payment did go through. If you’re paid in local currency instead, you won’t get this event. We keep trying the conversion for you, since we can’t pay out local currency from unconverted USDT. Send the session_id to support.

Best practices

Reply first, then do the work

app.post('/webhooks/minisend', (req, res) => {
  res.status(200).send('OK');
  processWebhookAsync(req.body);
});

Avoid handling the same event twice

We can occasionally send the same news more than once, and each copy can have a different X-Minisend-Event-Id. So check for repeats using session_id and event from the message body:

async function processWebhookAsync(payload) {
  const key = `${payload.session_id}:${payload.event}`;
  const seen = await db.events.findOne({ key });
  if (seen) return;

  await db.events.insert({ key, processed_at: new Date() });
  // ...handle event
}

Check settlement_mode before reading amounts

amount_local and exchange_rate only appear when you’re paid in local currency. When you keep USDC, you get fee_usdc, amount_usdc_net, and forward_required instead, so check which one you’re dealing with first:

if (payload.event === 'checkout.completed') {
  if (payload.settlement_mode === 'usdc') {
    if (payload.forward_required) {
      // wait for checkout.forwarded before treating funds as arrived
    }
    ledger.record(payload.session_id, payload.amount_usdc_net);
  } else {
    ledger.record(payload.session_id, payload.amount_local, payload.currency);
  }
}

Record what arrived, not what you asked for

amount_usdc is the amount you created the session with. If you record your sales from it, an underpayment shows up as money you never got.

if (payload.event === 'checkout.completed') {
  const received = payload.amount_received_usdc ?? payload.amount_usdc;

  if (payload.amount_matched === false) {
    await ops.flagForReview(payload.session_id, {
      expected: payload.amount_expected_usdc,
      received: payload.amount_received_usdc,
    });
  }
}

Match payments to your orders with external_id

if (payload.event === 'checkout.completed') {
  await orders.markPaid(payload.external_id, {
    receipt: payload.receipt,
    payout_amount: payload.amount_local,
    currency: payload.currency,
  });
} else if (payload.event === 'checkout.expired') {
  await orders.markAbandoned(payload.external_id);
}

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Webhook events

checkout.pending

checkout.completed

When this arrives

checkout.failed

checkout.expired

checkout.forwarded

settlement.forward_failed

settlement.swap_failed

Best practices

Reply first, then do the work

Avoid handling the same event twice

Check settlement_mode before reading amounts

Record what arrived, not what you asked for

Match payments to your orders with external_id

​checkout.pending

​checkout.completed

​When this arrives

​checkout.failed

​checkout.expired

​checkout.forwarded

​settlement.forward_failed

​settlement.swap_failed

​Best practices

​Reply first, then do the work

​Avoid handling the same event twice

​Check settlement_mode before reading amounts

​Record what arrived, not what you asked for

​Match payments to your orders with external_id

checkout.pending

checkout.completed

When this arrives

checkout.failed

checkout.expired

checkout.forwarded

settlement.forward_failed

settlement.swap_failed

Best practices

Reply first, then do the work

Avoid handling the same event twice

Check settlement_mode before reading amounts

Record what arrived, not what you asked for

Match payments to your orders with external_id