Off-ramp webhooks

Off-ramp events are delivered to the same webhook URL you configure in Settings, signed with the same secret and X-Minisend-Signature header as checkout events. Signature verification is identical, and failed deliveries retry up to 5 times with exponential backoff.

Event	Fires when	Terminal status
`offramp.completed`	Payout delivered to the recipient	`completed`
`offramp.failed`	Payout failed after your deposit	`failed`
`offramp.expired`	No deposit before `expires_at`	`expired`

offramp.completed

{
  "event": "offramp.completed",
  "order_id": "9b2f6c1e-...",
  "external_reference": "payout-8412",
  "status": "completed",
  "amount_usdc": 10,
  "amount_local": 1294,
  "payout_currency": "KES",
  "exchange_rate": 129.45,
  "fee": 13,
  "recipient_account_name": "Jane Wanjiku",
  "settlement_receipt": "SHQ1234ABC",
  "completed_at": "2026-07-05T12:07:41Z",
  "created_at": "2026-07-05T12:00:03Z"
}

event

string

required

Always offramp.completed.

order_id

string

required

Use as an idempotency key. Minisend may redeliver if your server timed out.

external_reference

string

Your reference, if set at creation.

amount_usdc

number

required

The order’s USDC amount.

amount_local

number

required

Gross local amount at the executed rate. The recipient received amount_local − fee.

payout_currency

string

required

KES, NGN, GHS, or UGX.

exchange_rate

number

required

Local currency per 1 USDC, as executed.

fee

number

Minisend fee in local units. 0 for NGN.

recipient_account_name

string

required

settlement_receipt

string

required

Payout receipt: an M-Pesa code for KES mobile payouts, an on-chain settlement hash for NGN.

completed_at

string

required

ISO 8601.

created_at

string

required

ISO 8601.

offramp.failed

The payout could not complete after your deposit.

{
  "event": "offramp.failed",
  "order_id": "9b2f6c1e-...",
  "external_reference": "payout-8412",
  "status": "failed",
  "amount_usdc": 10,
  "amount_local": 1294,
  "payout_currency": "KES",
  "exchange_rate": 129.45,
  "fee": 13,
  "recipient_account_name": "Jane Wanjiku",
  "created_at": "2026-07-05T12:00:03Z"
}

NGN deposits are refunded automatically to the order’s refund_address. For KES, GHS, and UGX failures, contact support with the order_id. Funds are not lost.

offramp.expired

No deposit arrived before expires_at. Nothing was sent and nothing is owed. Create a new order to retry.

{
  "event": "offramp.expired",
  "order_id": "9b2f6c1e-...",
  "external_reference": "payout-8412",
  "status": "expired",
  "amount_usdc": 10,
  "payout_currency": "KES",
  "recipient_account_name": "Jane Wanjiku",
  "created_at": "2026-07-05T12:00:03Z"
}

If you sent USDC but the order still expired (e.g. the transfer confirmed after the window, or you never submitted the hash), contact support with the order_id and transaction hash.

Handling pattern

Same as checkout webhooks: respond 200 immediately, process async, and dedupe on order_id.

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

  const payload = req.body;
  if (payload.event?.startsWith('offramp.')) {
    processOfframpEvent(payload); // dedupe on payload.order_id
  } else {
    processCheckoutEvent(payload); // dedupe on payload.session_id
  }
});

​offramp.completed

​offramp.failed

​offramp.expired

​Handling pattern

offramp.completed

offramp.failed

offramp.expired

Handling pattern