Skip to main content

Payment Callback and Checklist Guide

1. Overview​

Network delays or system issues can sometimes cause a payment to succeed while the merchant doesn’t receive the payment notification. This might make the order appear unpaid, leading to user confusion, complaints, or even duplicate payments.

2. Goal​

This guide helps merchants reliably verify payment status even when the notification is missed — improving system stability and preventing user issues caused by mismatched order statuses.

3. Front-End Payment Handling​

3.1 Integrated POS Payments​

  • If the front end shows “Canceled by user”, treat the order as unpaid and inform the user that payment was not completed.
  • If the front end shows “Success”, “Error”, timeout, or any unexpected status, call the order verification API to confirm payment status:
  • ✅ If verified as paid, show the Payment Success page.
  • ❌ If unpaid, inform the user to check the order later and avoid repeated payments.
  • For more details, see Back-end service processing.

3.2 Cloud API Payments​

After submitting a payment request:

  • Poll the order verification API (e.g., every 2 seconds for up to 60 seconds, or as needed).
  • If verification confirms payment success, show the Payment Success page.
  • If no confirmation after the polling period, show a Transaction Timeout message.

3.3 Hosted Page Payments​

After payment, users are redirected to the payment page or a predefined redirect_url. Display a “Payment Completed” button.

When the user clicks “Payment Completed”:

  • Check the order verification API to confirm the payment status:
  • ✅ If paid, redirect to Payment Success.
  • ❌ If unpaid, inform the user to revisit the Order Management page later and avoid repeated payments.

Note:

  • The back-end should regularly update the order status using the verification API (see Back-end service processing).
  • If the user retries payment for an unpaid order, always reuse the original order number to prevent duplicate payments.

4. Back-End Service Processing​

4.1 Payment Callback Processing​

Your backend must handle CodePay’s asynchronous payment notifications reliably and in real-time.

When a callback is received:

  • Verify and process the payment data according to CodePay’s callback parameters.
  • Update your internal order status immediately to reflect the payment result.
  • Acknowledge receipt of the callback by returning a proper response to CodePay (as defined in the API documentation).

🔗 Reference:

4.2 Periodic Order Status Polling​

If your system doesn’t receive a payment notification in time, your backend should automatically verify the order status using CodePay Query Order API.

You can choose one of the following polling strategies depending on your business setup:

Option 1: Progressive Retry Schedule

After the payment request is sent (or when the first notification fails):

  1. Use the CodePay Query Order API at increasing intervals: • 5s → 30s → 1min → 3min → 5min → 10min → 30min
  2. Stop querying once payment is confirmed as successful.
  3. If all queries fail to confirm payment, close the order using the CodePay Cancel Order API.

💡 You can customize the polling frequency and number of retries to match your operational needs.

Option 2: Scheduled Task Polling

  1. Create a scheduled task (e.g., every 30 seconds) that checks for orders created in the last 10 minutes that are still marked as unpaid.
  2. For each order: • Call the CodePay Query Order API to confirm its status. • Record how many times the order has been queried.
  3. If after 10 checks the order still shows unpaid, stop further attempts and revoke the order using the CodePay Cancel Order API.

⏱ Polling interval and retry count can be adjusted based on your business logic and system capacity.

✅ Best Practices • Always prioritize callback-based updates over polling results. • Use idempotent logic in your order update process to prevent duplicate handling. • Log every query and callback for audit and debugging purposes.