Skip to content

Deposits

Initiates a KES deposit to the user's USDC account via M-Pesa STK push.

The M-Pesa prompt is sent to the phone number stored on the account. You do not supply the phone number per-request.

Step 1 — Get a rate quote

GET /accounts/{account_id}/deposit-quote?amount_kes=5000

{
  "rate_id": "abc123-...",
  "amount_kes": 5000.0,
  "crypto_amount": 38.45,
  "net_usdc_amount": 38.07,
  "fee_usdc": 0.38,
  "exchange_rate": 131.35,
  "spread_bps": 20,
  "expires_in_seconds": 600
}

Show the user the exchange rate and fee. The quote is valid for 10 minutes and is single-use.

Step 2 — Confirm the deposit

POST /accounts/{account_id}/deposits

{
  "amount_kes": 5000,
  "rate_id": "abc123-..."
}

An Idempotency-Key header is required for safe retries:

Idempotency-Key: <unique-uuid-per-request>

Response:

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

The deposit is now pending. The user will receive an M-Pesa STK push. Once they confirm, Regini credits their account and fires a deposit.completed webhook.

Option B: Auto-confirm at live rate

Skip the quote step and execute immediately at the live rate.

POST /accounts/{account_id}/deposits

{
  "amount_kes": 5000,
  "auto_confirm_rate": true,
  "max_spread_bps": 50
}

max_spread_bps is optional. If the live spread exceeds this value, the request is rejected with SPREAD_EXCEEDED. Use it to protect your users from unfavorable rates.