Paycard

Capabilities

Gotchas

• ⚠Always verify payment status server-side by calling verify_payment before fulfilling an order. The callback URL alone is not sufficient — it can be spoofed by anyone who knows your endpoint.
• ⚠Store operation_reference from the response immediately. It is the only way to call verify_payment later. If you passed your own paycard-operation-reference in the request, that same value is echoed back.
• ⚠Auth is the field 'c' sent in the POST body, not an HTTP header. Do not confuse it with a Bearer token or X-Api-Key pattern.
• ⚠There is no sandbox environment. All requests hit production. Use minimal amounts (e.g. 100 GNF) when testing.
• ⚠paycard-redirect-with-get: 'on' redirects the user's browser to paycard-callback-url with the reference appended as the query param 'paycard-operation-reference' (e.g. ?paycard-operation-reference=2604-XXX&c=...&transaction-reference=...). No server-to-server POST is sent. Read 'paycard-operation-reference' from the query string and pass it to verify_payment server-side before fulfilling the order.
• ⚠code: 0 means the transaction was found, NOT that it was paid. Always check status: treat status?.toLowerCase() === 'success' as confirmed. status: 'new' means pending — do not fulfill.
• ⚠Always call this endpoint server-side before fulfilling an order. Never trust the redirect URL or callback payload alone.
• ⚠The ref path parameter is the operation_reference returned by create_payment, not your own internal order ID.
• ⚠The API key (c) is a path segment in the URL, not a query parameter: GET /epay/{c}/{ref}/status.
• ⚠Never fulfill an order based on the webhook payload alone. Always call verify_payment (GET /epay/{c}/{ref}/status) with the operation reference to confirm server-side. Check that status?.toLowerCase() === 'success' — code: 0 alone does not confirm payment.
• ⚠Return HTTP 200 immediately. Paycard does not retry failed webhook deliveries — if your handler throws or times out, the notification is lost.
• ⚠Paycard sends no webhook signature. Anyone who knows your callback URL can POST to it. The only safe verification is calling verify_payment with the API key.
• ⚠If create_payment was called with paycard-redirect-with-get: 'on', Paycard sends a browser GET redirect instead of this server-to-server POST. In that case, your callback route must handle GET (not POST) and extract operation_reference from the query string.