Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Mobile money

How to on-ramp and off-ramp RWF with mobile money in Rwanda: fields, limits and API examples.

countryIsoCode
currencyIsoCode
paymentChannel
Typical settlement

RW

RWF

mobile_money

—

Route
Per order (production)
Transfer type

On-ramp, Mobile money (rw_airtel)

1,592 to 795,545 RWF

stk_push

Off-ramp, Mobile money (rw_airtel)

672 to 709,616 RWF

—

Before the first call: set up the keys and the signing helpers from Countries, and verify the user as Rwanda explains.

On-ramp

1. Get a quote

The quote fixes the rate and lists the fields to collect from the user. Use it before quoteExpiresAt, or get a new one.

ENDPOINT='/api/v2/quote'
TIMESTAMP=$(($(date +%s) * 1000))
curl -X POST "$FONBNK_BASE_URL$ENDPOINT" \
  -H "x-client-id: $FONBNK_CLIENT_ID" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $(fonbnk_sign "$TIMESTAMP" "$ENDPOINT")" \
  -H "Content-Type: application/json" \
  --data '{"deposit":{"paymentChannel":"mobile_money","currencyType":"fiat","currencyCode":"RWF","countryIsoCode":"RW","carrierCode":"rw_airtel","amount":7000},"payout":{"paymentChannel":"crypto","currencyType":"crypto","currencyCode":"CELO_USDT"}}'
const response = await fonbnkRequest('POST', '/api/v2/quote', {
  "deposit": {
    "paymentChannel": "mobile_money",
    "currencyType": "fiat",
    "currencyCode": "RWF",
    "countryIsoCode": "RW",
    "carrierCode": "rw_airtel",
    "amount": 7000
  },
  "payout": {
    "paymentChannel": "crypto",
    "currencyType": "crypto",
    "currencyCode": "CELO_USDT"
  }
});

In production the quote asks for these fields:

Field
Label
Type
Required
Example

phoneNumber

Phone Number

phone

Yes

250781234567

carrierCode

Carrier

enum

Yes

rw_airtel

accountHolderName

Account name

string

Yes

Aline Uwase

blockchainWalletAddress

Your wallet address

string

Yes

0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20

blockchainMemo

Memo

string

No

—

Sandbox does not ask for accountHolderName. Production does, so send it there.

2. Create the order

Send quoteId from the quote, and every required field of both legs as one flat fieldsToCreateOrder object.

3. Take the payment

The transfer type is stk_push. Call Trigger order intermediate action. The carrier sends a PIN prompt to the user phone, and the user approves the payment there. Then call Confirm order.

In sandbox the user phone is not verified yet, so the order first asks for a one-time code in transferInstructions.fieldsForIntermediateAction. Sandbox accepts 123456. Send it with Trigger order intermediate action:

Then confirm the order:

4. Wait for the final status

The webhook tells you each new status. To check an order, call Get order. What to do at each status is on Countries. In sandbox this order reached payout_successful.

Off-ramp

1. Get a quote

The quote fixes the rate and lists the fields to collect from the user. Use it before quoteExpiresAt, or get a new one.

In production the quote asks for these fields:

Field
Label
Type
Required
Example

blockchainWalletAddress

Your wallet address

string

No

0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20

phoneNumber

Phone Number

phone

Yes

250781234567

carrierCode

Carrier

enum

Yes

rw_airtel

accountHolderName

Account name

string

Yes

Aline Uwase

Sandbox does not ask for accountHolderName. Production does, so send it there.

2. Create the order

Send quoteId from the quote, and every required field of both legs as one flat fieldsToCreateOrder object.

3. Receive the crypto

The user sends the crypto to the address in order.deposit.transferInstructions. Then call Confirm order with the fields in transferInstructions.fieldsToConfirmOrder, here the blockchainTransactionHash of that transfer. We check the transfer on-chain, and the payout starts when it is confirmed.

4. Wait for the final status

The webhook tells you each new status. To check an order, call Get order. What to do at each status is on Countries. Sandbox crypto runs on a test network and checks each deposit on-chain. The sample hash above matches no transfer, so this sandbox order stays in deposit_validating. Send a real test-network transfer to finish an off-ramp in sandbox.

Testing in sandbox

Add one of these fields to fieldsToCreateOrder to force how a sandbox order ends, then run the walkthrough. Without them, a sandbox on-ramp succeeds. No real money moves.

Route
Field
Values

On-ramp, Mobile money (rw_airtel)

depositSandboxForcedFlow

deposit_success, deposit_invalid, deposit_underpayment, deposit_overpayment, deposit_payment_info_mismatch

On-ramp, Mobile money (rw_airtel)

payoutSandboxForcedFlow

payout_success, payout_failed

Off-ramp, Mobile money (rw_airtel)

depositSandboxForcedFlow

deposit_success, deposit_invalid, deposit_crypto_transfer_not_found, deposit_crypto_sender_mismatch, deposit_crypto_transfer_reverted, deposit_crypto_paid_before_order

Off-ramp, Mobile money (rw_airtel)

payoutSandboxForcedFlow

payout_success, payout_failed