🧪 FiatRails Testing Guide

Complete guide to testing payments across different countries

🎯 Overview

This guide covers testing FiatRails payments in sandbox mode across Kenya, Ghana, Tanzania, and Nigeria. Use the provided test credentials and phone numbers to simulate real transactions without actual money movement.

🏗️ Sandbox Environment: All tests run on FUJI testnet with simulated mobile money providers. No real money is transferred.

🚀 Quick Test Flow

1 Get API Keys

Login to your sandbox at partners.fiatrails.com and get your API key from the dashboard.

2 Choose Test Country

Select a country and use the corresponding test phone numbers and currency.

3 Test On-ramp

Initiate a payment using the test phone number. The STK push will be simulated.

4 Check Status

Monitor transaction status using the status endpoint.

5 Test Off-ramp

Convert tokens back to mobile money using test disbursement numbers.

🌍 Test Data by Country

🇰🇪Kenya (KES)

Mobile Money: M-Pesa Safaricom

Test Phone Numbers

+254700000000
+254711111111
+254722222222
+254733333333

Amount Limits

Type Minimum Maximum Recommended Test
On-ramp 1 KES 100,000 KES 1,000 KES
Off-ramp 10 KES 50,000 KES 500 KES

Test Transaction

Kenya On-ramp Test
curl -X POST https://api.fiatrails.com/api/v1/onramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+254700000000",
    "amountKES": 1000,
    "merchantWallet": "0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7",
    "currency": "KES"
  }'

🇬🇭Ghana (GHS)

Mobile Money: MTN MoMo MTN Ghana

Test Phone Numbers

+233200000000
+233244444444
+233555555555
+233266666666

Amount Limits

Type Minimum Maximum Recommended Test
On-ramp 1 GHS 10,000 GHS 100 GHS
Off-ramp 5 GHS 5,000 GHS 50 GHS

Test Transaction

Ghana On-ramp Test
curl -X POST https://api.fiatrails.com/api/v1/onramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+233200000000",
    "amountKES": 100,
    "merchantWallet": "0x742d35Cc6635C0532925a3b8D0C0F0E4C33a8cC7",
    "currency": "GHS"
  }'

🇹🇿Tanzania (TZS)

Mobile Money: M-Pesa Vodacom

Test Phone Numbers

+255700000000
+255788888888
+255777777777
+255666666666

Amount Limits

Type Minimum Maximum Recommended Test
On-ramp 1 TZS 200,000 TZS 2,000 TZS
Off-ramp 100 TZS 100,000 TZS 1,000 TZS

🇳🇬Nigeria (NGN)

Mobile Money: Airtel Money Airtel Nigeria

Test Phone Numbers

+234800000000
+234900000000
+234810000000
+234701000000

Amount Limits

Type Minimum Maximum Recommended Test
On-ramp 1 NGN 500,000 NGN 5,000 NGN
Off-ramp 100 NGN 250,000 NGN 2,500 NGN

🧪 Test Scenarios

Scenario 1: Basic On-ramp

Goal: Test successful mobile money to crypto conversion

Steps:

  1. Use any test phone number
  2. Set amount within country limits
  3. Provide valid wallet address
  4. Expect "initiated" status
  5. Check status after 30 seconds
Expected: Transaction completes with "completed" status and blockchain hash

Scenario 2: Amount Validation

Goal: Test amount limit validation

Steps:

  1. Try amount below minimum (e.g., 0.5 KES)
  2. Try amount above maximum (e.g., 200,000 KES)
  3. Try negative amount
Expected: 400 error with "AMOUNT_OUT_OF_RANGE" code

Scenario 3: Invalid Phone Number

Goal: Test phone number validation

Steps:

  1. Try phone without country code: "0700000000"
  2. Try invalid format: "+254-700-000-000"
  3. Try non-existent number: "+254999999999"
Expected: 400 error with "INVALID_PHONE_NUMBER" code

Scenario 4: Cross-border Test

Goal: Test payments across different countries

Steps:

  1. Send KES from Kenya to Ghana wallet
  2. Convert GHS to TZS via API
  3. Test off-ramp to Nigeria
Expected: All transactions process with appropriate exchange rates

📊 Status Monitoring

Monitor your test transactions using the status endpoint:

Check Transaction Status
curl -X GET "https://api.fiatrails.com/api/status?transactionId=YOUR_TX_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Transaction Statuses

Status Description Next Action
initiated STK push sent to customer Wait for customer to enter PIN
pending Customer entered PIN, processing Wait for blockchain confirmation
completed Payment successful, tokens minted Tokens available in wallet
failed Payment failed or cancelled Check error details, retry if needed
expired Customer didn't complete in time Initiate new transaction

🛠️ Debugging Tips

Common Issues

⚠️ "Invalid API Key": Check your API key format and ensure it starts with "sandbox_"
⚠️ "Network Error": Verify your internet connection and API endpoint URL
⚠️ "Transaction Stuck": In sandbox, transactions auto-complete after 30 seconds

Best Practices

🚀 Ready for Production?

Once you've completed testing, request production access from your sandbox dashboard.

Access Sandbox API Reference