Webhook events

Event	Fires when	Terminal status
`checkout.completed`	Payout delivered to your account	`completed`
`checkout.failed`	Settlement failed post-deposit	`failed`
`checkout.expired`	No deposit within 30 minutes	`expired`

checkout.completed

Deposit received, normalised to USDC on Base, converted, and paid out.

{
  "event": "checkout.completed",
  "session_id": "cs_7f8a9b2c-...",
  "external_id": "order-4821",
  "amount_usdc": 25.00,
  "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"
}

event

string

required

Always checkout.completed.

session_id

string

required

Use as an idempotency key.

external_id

string

Your reference, if set.

amount_usdc

number

required

amount_local

number

required

Net local currency after the 1% fee.

currency

string

required

KES, NGN, GHS, or UGX.

exchange_rate

number

required

Local currency per 1 USDC at settlement.

receipt

string

required

Payout provider receipt.

status

string

required

Always completed.

completed_at

string

required

ISO 8601.

created_at

string

required

ISO 8601.

checkout.failed

Deposit received but settlement could not complete. 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"
}

event

string

required

Always checkout.failed.

session_id

string

required

external_id

string

amount_usdc

number

required

The amount that was deposited but couldn’t be settled.

currency

string

required

status

string

required

Always failed.

created_at

string

required

Contact support with the session_id. Customer funds are not lost.

checkout.expired

Session opened but no deposit arrived in the 30-minute window. Use this to mark abandoned orders.

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

event

string

required

Always checkout.expired.

session_id

string

required

external_id

string

Use this to mark the corresponding order as abandoned.

amount_usdc

number

required

The amount the customer never sent.

currency

string

required

status

string

required

Always expired.

created_at

string

required

Expired sessions cost nothing. The 1% fee is only charged on completed payments.

Best practices

Respond fast, process async

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

Idempotency

Use session_id as the key — Minisend may redeliver if your server timed out.

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

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

Correlate via 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);
}

​checkout.completed

​checkout.failed

​checkout.expired

​Best practices

​Respond fast, process async

​Idempotency

​Correlate via external_id

checkout.completed

checkout.failed

checkout.expired

Best practices

Respond fast, process async

Idempotency

Correlate via external_id