Best Practices

Recommendations for a stable EasyCheckout integration. Differences between payment methods and internal processing are absorbed by elepay, so you only need to check the final charge result.

Integration sequence

The merchant server creates an EasyQR code, shows it to the customer, the customer pays, and elepay notifies the result via Webhook. See the best practices below for how to handle it.

Status lifecycle

Best practices

1. Treat the Webhook as the single source of truth

• Always verify the elepay-signature (HMAC-SHA256) of the received Webhook before processing.
• The redirect status parameter is for page transition only. Do not use it for result determination; determine the result from the final events charge.succeeded (success) / charge.revoked (revoked).

2. Process the Webhook idempotently and return 2xx quickly

• The same event may be re-delivered, so make processing idempotent (keyed by orderNo, etc.) to avoid double processing.
• Offload heavy work to async; return 2xx immediately on receipt. A 4xx / 5xx triggers automatic retries (every 1 min x3 -> every 10 min x2).

3. Prepare a reconciliation fallback for missed events

• In case a Webhook is not delivered, implement a path to reconcile the result via a sync API such as Retrieve EasyQR code. Do not rely on the Webhook alone.

4. Set a unique orderNo per order

• Set a unique orderNo per order in Create EasyQR code. It is used to match the order on Webhook receipt and prevents duplicate creation for the same orderNo.

5. Determine amount and currency on the server side

• Create the code on the server side (secret key) and limit the public key to client-side display. Do not let the client decide the amount, to prevent tampering.

6. Verify in Test mode before going Live

• Switch between Test / Live and verify the full flow, including Webhook receipt, in Test mode before switching to Live.

7. Design the expiry and failure flows

• Set an expiry appropriate to your use case. When the expiry is reached, an unsettled (pending) payment is revoked and charge.revoked is notified.
• On expiry or failure, provide a recovery path for the customer, such as regenerating the QR code.