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

string

required

Always offramp.completed.

string

required

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

string

Your reference, if set at creation.

number

required

The order’s USDC amount.

number

required

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

string

required

KES, NGN, GHS, or UGX.

number

required

Local currency per 1 USDC, as executed.

number

Minisend fee in local units. 0 for NGN.

string

required

string

required

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

string

required

ISO 8601.

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

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Off-ramp webhooks

offramp.completed

offramp.failed

offramp.expired

Handling pattern

​offramp.completed

​offramp.failed

​offramp.expired

​Handling pattern

offramp.completed

offramp.failed

offramp.expired

Handling pattern