API Best Practices and Performance

Overview

To ensure the stability and speed of your integration, please adhere to the following guidelines regarding status checks, security scans, and error handling.

Order and Payment Status Requests

After a payment is initiated (i.e. card details submitted), our gateway may need to complete processing by communicating with one or multiple external provider systems. This process may also include human interaction, such as 3D Secure (3DS) authentication. During this processing window, the payment status typically does not change immediately.

Webhook Recommendation (Preferred)

We strongly recommend configuring webhooks. Our system will send a status change notification immediately when the payment status changes in our system. Using webhooks reduces the need for polling and ensures you receive updates as soon as they occur.

Polling Guidelines

Sending get order requests immediately or very frequently will not speed up processing. If you must poll:

  • Do not start polling immediately after initiating the payment;
  • Start the first status check after a short delay; e.g., 5–10 seconds (Initial Delay);
  • If the status is not final, retry using increasing intervals (e.g., 10s → 20s → 30s → 60s) (Exponential Backoff);
  • Stop polling once a final status is received.

Automated Security and Vulnerability Scans

Our payment gateway is a secure solution, compliant with PCI DSS and ISO standards. Automated security or vulnerability scanning tools may generate a high number of requests to API endpoints, creating abnormal request patterns.

  • Exclude payment gateway API endpoints from your automated security or vulnerability scans;
  • Filter traffic in your system to ensure that security scans do not proxy or forward scan traffic to the payment gateway APIs.

Error Handling and Retry Logic

Requests may fail due to missing / invalid parameters or temporary system conditions.

  • 4xx Responses (Client Error): Indicate a client-side or validation error. Do not retry automatically, correct the request parameters first;
  • 5xx Responses (Server Error): Retry with increasing delays (e.g., 5s → 15s → 30s → 60s). Do not use aggressive or unlimited retries.