API Integration Checklist

Ensure your system’s IP addresses are pre-approved to access the API.
Store your clientId and clientSecret securely.
Implement the token acquisition flow using /v1/partners/auth/login endpoint to authenticate and receive an access token.
Implement token refresh logic based on expiresInSecs to maintain authentication.
Include the Authorization: Bearer {access_token} header in all API calls.
Implement logic to generate and include a unique X-REQUEST-ID header in all API requests. This request ID is crucial for cross-system request tracking and must be retained for issue resolution and troubleshooting.

Implement a periodic (daily/weekly) scheduled task to fetch available brands using the /v1/partners/products endpoint to keep your catalog updated. This ensures your system remains synchronized with the latest brand information, even if brand update callbacks are missed.

Ensure the request body includes correct product IDs, reference IDs, amounts, and customer details.
Ensure each order includes a unique referenceId acting as an idempotency key, preventing duplicate orders. No two orders can have the same idempotency key, ensuring each transaction is processed only once even if the order request is sent multiple times.
Implement logic to handle orders with a PROCESSING status as follows:
- Set up your system to listen for the “Order Reached Terminal State” callback to automatically update the order status to SUCCESS or FAILED once it changes.
- If the callback has not been received, initiate polling of the order status via /v1/partners/orders/{orderId} endpoint starting one minute after the order was placed.
- Limit polling to a maximum of 5 attempts to avoid excessive load on your system and the API.
- If the order status remains PROCESSING and has not been updated after 15 minutes from the initial request, mark the order as FAILED on your side.
If you encounter a timeout while placing an order through an API, you should use the endpoint /v1/partners/orders/by-reference/{referenceId} to check the status of the order. A 404 response code indicates that the order has not been placed, and you may safely attempt to place the order again.

Use /v1/partners/orders/{orderId} or /v1/partners/orders/by-reference/{referenceId} dendpoints to fetch order details.
Implement logic to handle different voucher statuses and details.

Set up endpoints on your server to receive callbacks for brand updates, wallet low balance notifications, and order state changes.
Ensure your system can update brand information, alert on low balance, and process order updates based on these callbacks.

Implement a feature to check the partner wallet balance using /v1/partners/wallet/balance.

Implement comprehensive error handling based on the provided error codes and structures.
Validate request bodies to avoid common errors (e.g., E150-E160 for order validation errors).

Thoroughly test the integration in a staging environment before going live.
Test the handling of different order statuses, especially how your system reacts to PROCESSING and FAILED statuses.
Verify the behavior of your implementation of callbacks/webhooks to ensure proper real-time updates.
Conduct wallet balance management testing to ensure operations do not exceed available funds.

Set up monitoring for API responses and error rates to quickly identify and address integration issues.