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 (or orderId if you don’t have the quote) 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)	No*	The quote ID from your created quote
`orderId`	string (UUID)	No*	The order ID (use if you don’t have the quote ID)
`amount`	number	Yes	Amount in kobo (must match quote amount)

*Either quoteId or orderId is required.

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)	No*	The quote ID from your created quote
`orderId`	string (UUID)	No*	The order ID (use if you don’t have the quote ID)

*Either quoteId or orderId is required.

For BTC simulations, the amount parameter is not required as it’s determined by the Lightning invoice.

Payment Link Simulation

For Payment Links (including on-chain Bitcoin purchases), you need to first retrieve the order ID.

Step 1: Get the Order ID

Retrieve the order ID associated with your payment link:

curl -X GET "https://staging.api.mavapay.co/api/v1/paymentlink/orders?id={paymentRef}" \
  -H "X-API-KEY: your_staging_api_key"

Step 2: Simulate Payment

Use the order ID to simulate the bank transfer:

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 '{
    "amount": 800000,
    "currency": "NGN",
    "orderId": "11110-0001"
}'

For Payment Link simulations, use orderId instead of quoteId. The amount should match the payment link amount in kobo.

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",
        "accountName": "John Doe",
        "network": "mpesa"
      }
    }
  }'

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",
    ...
  }
}

If autopayout is enabled, you’ll also receive a payment.sent event shortly after.

Testing Different Scenarios

Test Successful Payment

Use the simulation endpoint as shown above to test successful payment flows.

Using Order ID Instead of Quote ID

If you don’t have access to the quote ID, you can use the order ID instead:

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",
    "orderId": "5466-3532",
    "amount": 604300
  }'

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

Create quotes successfully
Simulate NGN payments
Simulate BTC payments
Receive payment.received webhooks
Receive payment.sent webhooks
Handle webhook signature verification
Implement idempotent webhook processing
Test error scenarios
Verify beneficiary payouts work correctly

Next Steps

Learn about webhook integration
View quote examples for all currency pairs
Explore beneficiary formats
Test in production with small amounts first

Always thoroughly test your integration in staging before moving to production!

Get Started

Payouts

Stablecoins

Webhooks

Guides

Payment Simulation

Payment Simulation

Endpoint

How It Works

Nigerian Naira (NGN) Simulation

Request

Response

Parameters

Bitcoin (BTC) Simulation

Request

Response

Parameters

Payment Link Simulation

Step 1: Get the Order ID

Step 2: Simulate Payment

Complete Testing Flow

Step 1: Create a Quote

Step 2: Simulate Payment

Step 3: Receive Webhook

Testing Different Scenarios

Test Successful Payment

Using Order ID Instead of Quote ID

Test Different Currency Pairs

Test Webhook Handling

Common Errors

Best Practices

Integration Checklist

Next Steps

​Payment Simulation

​Endpoint

​How It Works

​Nigerian Naira (NGN) Simulation

​Request

​Response

​Parameters

​Bitcoin (BTC) Simulation

​Request

​Response

​Parameters

​Payment Link Simulation

​Step 1: Get the Order ID

​Step 2: Simulate Payment

​Complete Testing Flow

​Step 1: Create a Quote

​Step 2: Simulate Payment

​Step 3: Receive Webhook

​Testing Different Scenarios

​Test Successful Payment

​Using Order ID Instead of Quote ID

​Test Different Currency Pairs

​Test Webhook Handling

​Common Errors

​Best Practices

​Integration Checklist

​Next Steps

Payment Simulation

Endpoint

How It Works

Nigerian Naira (NGN) Simulation

Request

Response

Parameters

Bitcoin (BTC) Simulation

Request

Response

Parameters

Payment Link Simulation

Step 1: Get the Order ID

Step 2: Simulate Payment

Complete Testing Flow

Step 1: Create a Quote

Step 2: Simulate Payment

Step 3: Receive Webhook

Testing Different Scenarios

Test Successful Payment

Using Order ID Instead of Quote ID

Test Different Currency Pairs

Test Webhook Handling

Common Errors

Best Practices

Integration Checklist

Next Steps