Integrating payments into your app with the MariPay API, step by step

You can have a working payment integration in an afternoon. The shape is always the same: your server creates a payment, the customer approves it on their phone, and your server learns the result through a webhook. Here is the whole path using test mode, which never moves real money.

Get a test key

Create an account, add a business and open the API keys page. Sandbox keys start with sk_test_ and work immediately; you do not need to be verified to use them. Live keys (sk_live_) unlock after your account is verified. Keep every secret key on your server. Never put one in a website or mobile app.

Create a payment

Send the amount in minor units as an integer, an explicit currency, and your own reference. Always include an Idempotency-Key header so a retry can never create a second charge.

curl -X POST https://api.maripay.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Idempotency-Key: 7c1f0e2a-9c4b-4a1d-8f5e-2b6d1c3a4e5f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "UGX",
    "reference": "invoice-42",
    "metadata": { "invoice_id": "42" }
  }'

The response includes a payment id, a status and, when the customer must be sent somewhere to pay, a checkout_url. If you would rather not build a payment form, create a checkout session or a payment link instead and let MariPay host the page.

Listen for the result

Register a webhook endpoint in the dashboard and handle payment.completed and payment.failed. Verify the signature on every request, update your order, and return a 2xx quickly. We cover this in detail in our webhooks guide.

Try every outcome in test mode

In test mode a built-in simulator plays the customer's phone. A payment stays pending, exactly as it would while a real customer decides, until you answer it. You can do that from the dashboard (open the collection and press Approve payment or Decline) or from your code.

curl -X POST https://api.maripay.com/api/v1/payments/pay_xxx/simulate \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "completed" }'   # or "failed"

• Approve it, and check that your order is marked paid exactly once.
• Decline it, and check the customer sees a clear message and can try again.
• Leave it pending, to test your waiting state and what happens when it expires.
• An amount ending in 11 simulates a provider outage, to test your error handling.

Go live

When your tests pass, submit your business verification. Once it is approved, live keys and live payments switch on, and everything you built against the sandbox works the same way against real money. Only the key changes.