Payment Simulation
The simulation endpoint allows you to test payment flows in the staging environment without making actual payments. This is useful for testing your integration and webhook handlers.
The simulation endpoint is only available in the staging environment: https://staging.api.mavapay.co/api/v1
Endpoint
POST /api/v1/simulation/pay-in
How It Works
- Create a quote using the Create Quote endpoint
- Use the
quoteId from the response
- Call the simulation endpoint to simulate payment
- Your webhook will receive
payment.received event
- If autopayout is enabled, you’ll also receive
payment.sent event
Nigerian Naira (NGN) Simulation
Request
{
"currency": "NGN",
"quoteId": "c523383d-d44c-4d2e-be48-b64bcaf7b403",
"amount": 604300
}
Response
{
"status": "ok",
"data": "PayIn simulation successful"
}
Parameters
| Parameter | Type | Required | Description |
|---|
currency | string | Yes | Must be "NGN" |
quoteId | string (UUID) | Yes | The quote ID from your created quote |
amount | number | Yes | Amount in kobo (must match quote amount) |
Bitcoin (BTC) Simulation
Request
{
"currency": "BTC",
"quoteId": "a523383d-d44c-4d2e-be48-b64bcaf7b404"
}
Response
{
"status": "ok",
"data": "PayIn simulation successful"
}
Parameters
| Parameter | Type | Required | Description |
|---|
currency | string | Yes | Must be "BTC" |
quoteId | string (UUID) | Yes | The quote ID from your created quote |
For BTC simulations, the amount parameter is not required as it’s determined by the Lightning invoice.
Complete Testing Flow
Step 1: Create a Quote
curl -X POST https://staging.api.mavapay.co/api/v1/quote \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_staging_api_key" \
-d '{
"amount": "604300",
"sourceCurrency": "NGNKOBO",
"targetCurrency": "KESCENT",
"paymentMethod": "BANKTRANSFER",
"paymentCurrency": "NGNKOBO",
"autopayout": true,
"beneficiary": {
"identifierType": "paytophone",
"identifiers": {
"phoneNumber": "+254796980711"
}
}
}'
Step 2: Simulate Payment
curl -X POST https://staging.api.mavapay.co/api/v1/simulation/pay-in \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_staging_api_key" \
-d '{
"currency": "NGN",
"quoteId": "c523383d-d44c-4d2e-be48-b64bcaf7b403",
"amount": 604300
}'
Step 3: Receive Webhook
Your registered webhook endpoint will receive a payment.received event:
{
"event": "payment.received",
"data": {
"id": "0b234e32-d5ba-4c2a-8f71-0b820a477f01",
"amount": 604300,
"currency": "NGN",
"type": "DEPOSIT",
"status": "SUCCESS",
...
}
}
payment.sent event shortly after.
Testing Different Scenarios
Test Successful Payment
Use the simulation endpoint as shown above to test successful payment flows.
Test Different Currency Pairs
Create quotes for different currency pairs and simulate payments:
// BTCSAT => KESCENT
const btcToKes = await createQuote({
amount: "100000",
sourceCurrency: "BTCSAT",
targetCurrency: "KESCENT",
...
});
await simulatePayment({
currency: "BTC",
quoteId: btcToKes.data.id
});
// NGNKOBO => ZARCENT
const ngnToZar = await createQuote({
amount: "300000",
sourceCurrency: "NGNKOBO",
targetCurrency: "ZARCENT",
...
});
await simulatePayment({
currency: "NGN",
quoteId: ngnToZar.data.id,
amount: 300000
});
Test Webhook Handling
- Set up a webhook endpoint using webhook.site or ngrok
- Register your webhook in staging
- Create a quote and simulate payment
- Verify your webhook receives and processes the events correctly
Common Errors
| Error | Description | Solution |
|---|
Invalid quote ID | Quote doesn’t exist or has expired | Create a new quote and use the fresh quote ID |
Amount mismatch | Simulation amount doesn’t match quote amount | Use the exact amount from the quote response |
Quote already paid | Quote has already been paid (simulated or real) | Create a new quote for testing |
Invalid currency | Currency doesn’t match quote parameters | Use the correct currency from your quote |
Best Practices
- Fresh Quotes: Create new quotes for each test to avoid “already paid” errors
- Webhook Testing: Test both
payment.received and payment.sent events
- Error Handling: Test how your system handles different payment statuses
- Idempotency: Verify your webhook handler processes duplicate events correctly
- Timing: Test scenarios where webhooks arrive out of order
Integration Checklist
Next Steps
Always thoroughly test your integration in staging before moving to production!
