Skip to content

Deposits

How it works

A deposit converts money from the user's mobile money wallet into USDC held in their Regini account. Amounts are in your market's currency (currency in every response; KES in Kenya), and the payment prompt comes from your market's mobile money network (M-Pesa in Kenya). See Markets. The flow:

  1. Quote (recommended): fetch a rate quote for the amount. The response shows the exact USDC the user will receive, the fee, and the exchange rate. The quote is locked for 10 minutes.
  2. Initiate: submit the deposit with the rate_id from the quote. Regini sends a mobile money payment prompt (an STK push on M-Pesa) to the phone number stored on the account. The API responds immediately; the deposit is now pending.
  3. User confirms: the user approves the payment on their phone.
  4. Webhook: once the payment is collected, Regini credits the USDC to the account and fires a deposit.completed webhook.

The payment prompt goes to the phone stored on the account. You do not supply it per-request. Your backend should listen for the webhook rather than polling for status.


Step 1: Get a rate quote

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

{
  "rate_id": "abc123-...",
  "fiat_amount": 5000.0,
  "currency": "KES",
  "net_usdc_amount": 38.07,
  "fee_fiat": 50.0,
  "exchange_rate": 131.35
}

fee_fiat is the fee 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. The quote is valid for 10 minutes and is single-use.

Step 2: Confirm the deposit

POST /accounts/{account_id}/deposits

{
  "fiat_amount": 5000,
  "rate_id": "abc123-...",
  "reference": "optional-your-ref"
}

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 a mobile money payment prompt. 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

{
  "fiat_amount": 5000,
  "auto_confirm_rate": true,
  "reference": "optional-your-ref"
}

Request fields

Field Required Description
fiat_amount Yes Amount to deposit, in your market's currency
rate_id Conditional Rate quote from GET .../deposit-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

Daily and weekly windows are rolling (not calendar-reset). Failed transactions do not count against the limits. Breaching a limit returns VELOCITY_LIMIT_EXCEEDED.