Integration checklist

Everything to check before going live.

Account

[ ] Account created and email verified
[ ] KYC approved (level ≥ 2 to collect payments, level 3 for payouts)
[ ] Settlement bank account (account number and bank name) saved in the dashboard
[ ] At least one secondary user with MFA enabled (no single human point of failure)

[ ] sk_test_… keys created with minimal scopes per use case
[ ] sk_live_… keys created and stored in a secret manager (Vault, AWS Secrets Manager, Doppler)
[ ] No sk_live_… key in a public git repository, a committed .env file or a public environment variable
[ ] IP allowlist enabled if your infrastructure has fixed IPs
[ ] Rotation procedure documented (owner, frequency, runbook)

[ ] Every mutating request sends Idempotency-Key (client-generated UUID v4)
[ ] The idempotency key is persisted on your side until the final confirmation
[ ] Authorization: Bearer … header on 100% of calls
[ ] 4xx / 5xx error handling (see error codes)
[ ] Exponential backoff on 429 / 5xx
[ ] Structured logging of requests and responses (with the key masked)
[ ] Client timeout of at least 15s
[ ] Amounts sent in leones with at most 2 decimals ("150.00"), currency SLE
[ ] Phone numbers in E.164 format: +232 followed by 8 digits

[ ] Webhook endpoint created in the dashboard (HTTPS required)
[ ] Secret stored in the secret manager
[ ] Signature verified on the raw body (not after JSON parsing)
[ ] Timestamp checked (|now - t| ≤ 300s)
[ ] HMAC compared in constant time (hash_equals / crypto.timingSafeEqual)
[ ] Idempotency on your server (UNIQUE(event, data.id) in your log)
[ ] 2xx response in under 15 s (long processing → async job)
[ ] Your own retries disabled (SOAMTAR retries for you; retrying twice causes duplicates)
[ ] A plan for SOAMTAR's 5 delivery attempts (alert ops if failures persist)

[ ] Daily cron that pulls GET /v1/payments?status=success and compares it with your database
[ ] On a mismatch: call POST /v1/payments/{id}/verify to force a sync
[ ] Alerts on transactions still pending after 1 h (sandbox) or 30 min (live)

[ ] HTTPS everywhere (including return_url / cancel_url)
[ ] CSP allowing connect-src https://app.so-amtar.com
[ ] No auth middleware on the /webhooks/soamtar route (bypassed for that endpoint only)
[ ] Masked logging: no API key or signature in your own logs
[ ] Internal audit trail on every payment operation (who, when, from which IP)
[ ] No sensitive data in query strings: never ?phone=, ?email=, ?token= or ?api_key= on API calls. Use the JSON body. SOAMTAR masks these values in its own logs if they appear in a query string, but your own infrastructure (reverse proxy, CDN, browser history) does not.
[ ] Webhook endpoint URL registered in SOAMTAR: public HTTPS only. Loopback URLs, private IPs and internal TLDs are rejected at registration.

[ ] Unit tests on webhook signature verification (success + 3 failure cases)
[ ] Integration tests on the full flow: init → customer PIN → webhook → confirmation
[ ] Duplicate delivery tests (same event sent twice → database unchanged)
[ ] SOAMTAR retry tests (5xx then 200 → processed only once)
[ ] Sandbox test of every expected event (success, failed, cancelled, expired)

[ ] Terms of sale updated with "Payments processed by SOAMTAR"
[ ] Privacy policy mentioning that payer data is shared with SOAMTAR
[ ] Receipts or invoices given to customers for every successful transaction
[ ] Refund procedure documented (channel, delay, contact). Refunds go through POST /v1/refunds (credited back to the payer's Orange Money wallet); refund.success / refund.failed are handled.

[ ] Internal dashboard with transaction volume, success rate, latency and error rate
[ ] Alert if the success rate drops below 90% within 5 min
[ ] Alert if no webhook has arrived for more than 30 min (possible SOAMTAR incident)
[ ] Internal status page linking to SOAMTAR support contacts

[ ] Switch from sk_test_… to sk_live_… in the production configuration
[ ] First live transaction: send a test to an internal Orange Money number (Le 50.00) and check the whole chain
[ ] Tell your support team: "SOAMTAR live since [date]"
[ ] Rollback procedure: how to return to sk_test_… in 5 min in case of incident

[ ] Rotate the webhook secret every 6 months
[ ] Rotate API keys every 6 months
[ ] Update your event handlers whenever a new event type is added (see the changelog)
[ ] Quarterly review of permissions (who can access the dashboard, IP allowlist up to date)

All ticked? You are ready to go live. See also Test → Production.