API version 1

Build payments people trust.

Accept BIF payments with hosted checkout, real-time status updates, protected funds and dependable merchant settlement.

Start integrating Talk to a developer
Quickstart

Create your first checkout session

Make a POST request from your server to the checkout/sessions endpoint with an API key from your merchant workspace. Include a unique Idempotency-Key on every write request to prevent duplicates.

POST /api/v1/checkout/sessions/ 
curl -X POST https://amatopay.amatotechgroup.com/api/v1/checkout/sessions/ \
  -H "Authorization: Bearer sk_••••" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "ORDER-1001",
    "description": "Online purchase",
    "amount": "50000.00",
    "currency": "BIF",
    "payer_alias": "+25779000000",
    "return_url": "https://merchant.bi/payment/result"
  }'

AmatoPay responds with a session object containing a session_id and a checkout_url. Redirect your customer there to complete the payment.

Selling a service that is delivered the moment payment clears (transport tickets, airtime, event tickets)? If your account has the instant settlement capability, send "require_delivery_confirmation": false — the payment skips the secure-code hold and pays out to you immediately. Ask support to enable it.

Response
{
  "session_id": "8f1c…",
  "checkout_url": "https://…/pay/8f1c…/",
  "status": "alias_verified",
  "amount": "50000.00",
  "currency": "BIF",
  "order_number": "ORDER-1001"
}
⌁

Authentication

Authenticate server-to-server calls with a secret API key from your developer settings. Send it as Authorization: Bearer sk_… or X-Api-Key: sk_…. Never expose secret keys in browser or mobile code.

◇

Ping & readiness

Call GET /api/v1/ping/ to confirm your key works and see whether your account is verified and cleared to operate. Returns a welcome message, your merchant details, can_operate, and any pending verification steps. Works even while in review.

Webhooks

Signed webhooks are your source of truth

Configure endpoints in the dashboard and subscribe to the events you need for payment, delivery, settlement and refund updates.

payment.processing payment.awaiting_approval payment.paid payment.failed delivery.confirmed payment.disputed settlement.completed settlement.failed payment.refunded

Each request carries AmatoPay-Signature: t=<timestamp>,v1=<hex>, where v1 is HMAC-SHA256(endpoint_secret, "<timestamp>." + raw_body). Reject requests with a bad signature or a stale timestamp. Failed deliveries retry with exponential backoff for up to 8 attempts.

Payment lifecycle

One traceable flow from checkout to payout

  1. 1Verify the payerThe payer's MOBILE alias is checked before a payment is created.
  2. 2Create the sessionYour server sends order, payer and amount details. The response is immediate — no gateway wait.
  3. 3Customer paysRedirect to checkout_url; the payer approves the payment request and gets a six-digit secure code.
  4. 4Funds are protectedPaid funds are held in a fiduciary account while the order is fulfilled.
  5. 5Settlement completesOnce the payer confirms delivery, net funds are paid to your verified settlement number.
◇
Security

Design for verification, not assumptions.

Never treat the browser return_url as proof of payment — the customer may close the browser early. Always confirm status with the API or a signed webhook before fulfilling an order.

Protected funds

Delivery-aware settlement

AmatoPay tracks fiduciary holds, delivery confirmation, operational reviews, refunds and final settlement as separate auditable states. Domestic transactions use a four-business-day protection window; international transactions use fourteen calendar days, subject to compliance review.