Skip to content

Withdrawals

How it works

A withdrawal converts USDC from the user's Regini account into your market's currency (KES in Kenya), paid out directly to their mobile money wallet (M-Pesa in Kenya). See Markets. The flow:

  1. Quote (recommended): fetch a rate quote for the USDC amount. The response shows the exact amount the user will receive and the fee. The quote is locked for 10 minutes.
  2. Initiate: submit the withdrawal with the rate_id. Regini debits the USDC from the account immediately and queues the payout. The API responds immediately; the withdrawal is now in-flight.
  3. Payout: Regini instructs a mobile money payout (B2C) to the phone number stored on the account.
  4. Webhook: once the transfer is confirmed, a withdrawal.completed webhook fires.

Only one withdrawal can be in-flight per account at a time. A second request while one is pending is rejected with CONCURRENT_WITHDRAWAL. The payout goes to the phone stored on the account. You do not supply it per-request.


Step 1: Get a rate quote

You can quote by USDC amount or by the amount the user should receive, whichever your UX collects from the user.

By USDC:

GET /accounts/{account_id}/withdrawal-quote?amount_usdc=38

By fiat (user enters how much they want to receive, in your market's currency):

GET /accounts/{account_id}/withdrawal-quote?fiat_amount=5000

Provide either amount_usdc or fiat_amount, not both. The response is the same either way:

{
  "rate_id": "def456-...",
  "amount_usdc": 38.0,
  "net_fiat_amount": 4970.0,
  "currency": "KES",
  "fee_usdc": 0.38,
  "exchange_rate": 130.79
}

net_fiat_amount is what the user receives after fees, in currency. exchange_rate is the effective fiat-per-USDC rate with the FX spread already applied, this is the rate shown to the user. amount_usdc in the response is always the USDC that will be debited regardless of which input type you used. Pass the returned rate_id to confirm.

Step 2: Confirm the withdrawal

POST /accounts/{account_id}/withdrawals

{
  "rate_id": "def456-...",
  "reference": "optional-your-ref"
}

Idempotency-Key header required.

Response:

{
  "status": "success",
  "message": "Withdrawal initiated",
  "transaction_id": "tx-uuid-..."
}

Regini sends the payout to the user's mobile money wallet. Once confirmed, a withdrawal.completed webhook fires.


Option B: Auto-confirm at live rate

Skip the quote step and execute immediately. Provide either amount_usdc or fiat_amount (not both).

By USDC:

{
  "amount_usdc": 38,
  "auto_confirm_rate": true
}

By fiat:

{
  "fiat_amount": 5000,
  "auto_confirm_rate": true
}


Request fields

Field Required Description
amount_usdc Conditional USDC to debit. Required unless fiat_amount or rate_id is provided.
fiat_amount Conditional Amount the user wants to receive, in your market's currency. The USDC debit is back-calculated from the live rate.
rate_id Conditional Rate quote from GET .../withdrawal-quote. Required when auto_confirm_rate is false.
auto_confirm_rate No Default false. When true, executes at the live rate without a prior quote.
reference No Your own reference string (max 255 chars). Returned in the webhook and transaction history.

Unknown fields are refused with 422.


Limits

Limits are set per market, in the market's currency.

Limit Kenya (KES)
Minimum per transaction 100
Maximum per transaction 250,000
Daily (rolling 24 hours) 500,000 per account
Weekly (rolling 7 days) 2,000,000 per account

Deposit and withdrawal volumes are tracked independently, a 500,000 deposit does not affect your withdrawal allowance. Windows are rolling, not calendar-reset. Failed transactions are excluded from volume counts. Breaching a limit returns VELOCITY_LIMIT_EXCEEDED.


One withdrawal at a time

Only one withdrawal can be in-flight per account at a time. A second request while one is pending returns CONCURRENT_WITHDRAWAL.