LengoPay

cashin_request

• ⚠amount must be a numeric string (e.g. "1000"), not a number. Passing a number causes a 400 error.
• ⚠The "Success" status in the response only indicates that the request was received, not that the payment has been made. Use cashin_status or the callback to get the final result.
• ⚠The returned pay_id is base64-encoded — keep it as is to use it in cashin_status, without decoding.
• ⚠callback_url must be a valid HTTPS URL. HTTP URLs are silently ignored.
• ⚠type_account must match the network of the account number (e.g. do not use lp-om-gn for an MTN number).

cashin_status

• ⚠Use the base64 pay_id returned by cashin_request without decoding — LengoPay expects it as is.
• ⚠PENDING means the payment is being processed on the mobile network. Do not treat PENDING as final — wait for SUCCESS or FAILED.
• ⚠Never fulfill an order on PENDING status, even after several successive checks.

create_payment

• ⚠Store pay_id immediately before redirecting the user — it is the only identifier for calling verify_payment and confirming the payment server-side.
• ⚠The Authorization header expects the license key directly: 'Basic {license_key}'. This is not standard Basic Auth (no base64 username:password) — pass the key as is.
• ⚠websiteid is a required parameter, separate from the license key. Both must be configured as separate environment variables.
• ⚠There is no sandbox. All calls hit production — use small amounts for testing.

get_balance

• ⚠balance is returned as a string (e.g. "7792"), not a number — use parseFloat(balance) before any calculation.
• ⚠The URL has no /v1/ prefix, unlike the other LengoPay endpoints (e.g. /api/getbalance/ and not /api/v1/getbalance/).

list_cashin_transactions

• ⚠Returns only Cash In transactions (push to a phone number via cashin_request). For Cash Out transactions via payment URL, use list_transactions.
• ⚠The account field may be returned as a number or a string depending on the response — normalize with String(account) before use.

list_transactions

• ⚠Returns only Cash Out transactions (payments initiated via create_payment with a payment URL). For Cash In transactions, use list_cashin_transactions.
• ⚠The status field may be a string ("SUCCESS") or an integer (0) depending on the transaction — normalize before use.

verify_payment

• ⚠Always call verify_payment server-side before confirming an order. The webhook alone is not enough — it can be forged by anyone who knows your callback_url.
• ⚠PENDING is a valid status: the payment is being processed. Do not fulfill the order on PENDING — wait for SUCCESS.
• ⚠The status is strictly UPPERCASE: compare with status === 'SUCCESS'.
• ⚠The endpoint changed in v1.2.0: it is now POST /api/v1/transaction/status with pay_id and websiteid in the body. The old GET /api/v1/payments/{payId} no longer works.

webhook_payment_completed

• ⚠Never fulfill an order based on the webhook alone. Call verify_payment (POST /api/v1/transaction/status with pay_id and websiteid) to confirm server-side — the webhook can be forged by anyone who knows your callback_url.
• ⚠Respond HTTP 200 immediately and process the payment asynchronously. LengoPay retries on failure, which can cause duplicates if your handler is slow.
• ⚠Implement idempotency: LengoPay may send the same webhook multiple times for the same pay_id. Check that the order is not already fulfilled before acting.
• ⚠The Client field contains the payer's phone number (e.g. '624897845'). It is missing from the payload in some cases — do not rely on it.
• ⚠[MUST TELL USER] LengoPay only calls the callback_url over HTTPS — http:// URLs are silently ignored. In local development, the webhook will never fire without an HTTPS tunnel. Tell the user explicitly: run `ngrok http 3000`, then update NEXT_PUBLIC_BASE_URL (or the equivalent) with the ngrok URL before testing.