PayGate

check_balance

• ⚠[MUST TELL USER] /v1/check-balance requires IP whitelisting on PayGate's side. Only requests originating from IPs registered in the merchant dashboard are accepted. Make sure your production server IP is whitelisted before going live.
• ⚠Flooz and T-Money balances are completely separate accounts. A disburse on TMONEY consumes only the `tmoney` balance, even if your `flooz` balance is plentiful — and vice versa. Always check the matching network before calling disburse.
• ⚠Balances are returned as numbers without a currency field — they are always in XOF (FCFA), with no decimals.
• ⚠Do not poll this endpoint at high frequency. Use it before disbursements and at low cadence for monitoring.
• ⚠[MUST TELL USER] PayGate API documentation is private. Confirm response field types in your dashboard if you observe schema mismatches.

check_payment_status

• ⚠The status codes (0/2/4/6) on this endpoint mean PAYMENT outcomes — 0 = paid, 2 = pending, 4 = expired, 6 = cancelled. The IDENTICAL numbers on /v1/pay (initiate_payment) mean REGISTRATION outcomes (0=registered, 2=invalid token, 4=invalid params, 6=duplicate). Do not share a single status enum across both endpoints.
• ⚠status = 2 (pending) is the normal state immediately after initiate_payment — the customer has not yet entered their PIN. Re-poll every few seconds until you reach a terminal state (0, 4, or 6).
• ⚠payment_reference is the operator-side reference (Flooz or T-Money). It is what your customer-support agents need for reconciliation with the operator. Empty until status = 0.
• ⚠payment_method on the response uses 'T-Money' (with hyphen), while the `network` field you send to /v1/pay uses 'TMONEY' (uppercase, no hyphen). Do not assume they are the same string.
• ⚠PayGate also exposes /api/v1/status which takes `tx_reference` instead of `identifier`. /v2/status is usually more convenient because you already control the identifier from your side. Use whichever you persisted.
• ⚠Never fulfill an order based on the webhook alone — always re-check status via this endpoint server-side before releasing goods or funds.
• ⚠[MUST TELL USER] PayGate API documentation is private. Confirm response field shapes in your account dashboard if you see any mismatch in production.

create_payment_page

• ⚠This is NOT a JSON API — it's a hosted page. The 'response' is an HTML page rendered to the customer's browser. The capability just builds the redirect URL.
• ⚠The network enum is DIFFERENT from /v1/pay and /v1/disburse: here it's 'MOOV' or 'TOGOCEL'. On /v1/pay and /v1/disburse the same concept is encoded as 'FLOOZ' / 'TMONEY'. Do not pass FLOOZ or TMONEY to /v1/page — they are silently ignored.
• ⚠After the customer completes (or abandons) the payment, PayGate redirects to the url query parameter. The redirect URL alone is NOT proof of payment — always re-verify server-side with check_payment_status before fulfilling.
• ⚠If you also configured a webhook in your dashboard, you will receive the webhook on success regardless of whether the customer made it back to the redirect URL. The webhook is the more reliable signal.
• ⚠Use this capability instead of initiate_payment when you want to let the customer choose their operator on a PayGate-hosted page rather than knowing the network upfront.
• ⚠[MUST TELL USER] PayGate API documentation is private and only visible from inside the merchant dashboard. The query parameters and behavior of /v1/page may evolve — cross-check with the current docs in your account.
• ⚠This endpoint uses /v1/page (no /api/ prefix), unlike all other PayGate endpoints which go through /api/. If you centralize BASE_URL as 'https://paygateglobal.com/api', this call will break silently.

disburse

• ⚠Unlike every other PayGate endpoint where success = status 0, /v1/disburse returns status 200 on success. Hard-coding `status === 0` will mis-treat every successful disbursement as a failure.
• ⚠[MUST TELL USER] /v1/disburse requires IP whitelisting on PayGate's side. Only requests originating from IPs registered in the merchant dashboard are accepted. Make sure your production server IP is whitelisted before going live — otherwise the API returns an error regardless of credentials.
• ⚠status 200 means PayGate ACCEPTED the transfer, not that the money has landed on the recipient's wallet. The actual settlement is asynchronous — re-poll check_payment_status by the same identifier/reference to confirm.
• ⚠If you intend to poll the status afterwards, pass `reference` here and re-use the SAME value as `identifier` on /v2/status. Inconsistent values between the two endpoints will break the lookup.
• ⚠Check your balance (check_balance) on the matching network BEFORE calling disburse. Disbursing FLOOZ from an empty Flooz wallet (even if your T-Money balance is plentiful) fails — the two balances are separate.
• ⚠PayGate's introductory text on this endpoint talks specifically about 'Moov' transfers, but the network enum officially supports both FLOOZ and TMONEY.
• ⚠[MUST TELL USER] PayGate API documentation is private. Confirm response semantics in your dashboard if you observe a different status code on success.

initiate_payment

• ⚠status: 0 only means PayGate registered the transaction — the customer still has to validate the USSD push on their phone. Always poll check_payment_status (/api/v2/status) by identifier before treating the payment as completed.
• ⚠The four status codes on /v1/pay (0, 2, 4, 6) are REGISTRATION statuses, not payment statuses. They look identical to the codes returned by /v2/status but mean completely different things. Do not reuse the same mapping.
• ⚠identifier must be globally unique per merchant. Reusing the same identifier returns status 6 (duplicate) and silently breaks idempotency on your side — use a UUID or a strictly-incrementing order ID.
• ⚠network MUST be exactly 'FLOOZ' or 'TMONEY' (uppercase). Other values such as 'MOOV', 'TOGOCEL', 'T-Money' belong to other endpoints (/v1/page, payment_method response field) and will not work here.
• ⚠PayGate has no sandbox environment. Test with small real amounts on real phones during integration.
• ⚠[MUST TELL USER] PayGate API documentation is private and only visible from inside the merchant dashboard. Field names, payload shape, and edge cases may differ slightly between accounts and over time — always cross-check with the current docs in your account.

webhook_payment_completed

• ⚠[MUST TELL USER] The PayGate webhook does NOT fire by default — you must configure the destination URL inside your PayGate merchant dashboard. Until that is done, no webhook is ever sent, even if payments succeed.
• ⚠[MUST TELL USER] PayGate's public documentation does NOT describe any signature, HMAC, or shared-secret mechanism for verifying webhook payloads. Treat the payload as UNTRUSTED — any party that knows your URL can forge a webhook. ALWAYS call check_payment_status (/api/v2/status) with the received `identifier` and confirm status = 0 before fulfilling the order.
• ⚠PayGate may retry or drop webhooks in case of timeouts or 5xx responses. Implement a reconciliation job that re-polls /v2/status for any PENDING transaction older than a few minutes.
• ⚠Return HTTP 200 immediately and process asynchronously if your handler is slow. Anything other than 200 is treated as a delivery failure.
• ⚠payment_method on this payload uses 'T-Money' (with hyphen), NOT 'TMONEY'. Same caveat as on the /v2/status response — do not assume it matches the value you sent on /v1/pay.
• ⚠Restrict the webhook endpoint to PayGate's outbound IP range if possible, and rate-limit it — there is no other defense-in-depth available since there is no signature.
• ⚠The `amount` field in the webhook payload cannot be verified against the API — /v2/status does not return an amount. Always compare against the amount stored in your database at order creation, never trust the webhook value directly.