Integration Best Practices

1. Avoid Hardcoding any parts of Dynamic URLs

When dealing with URLs provided by the platform for redirecting customers to payment (such as a Hosted Payment Page URL), avoid storing any part of these URLs as fixed or unchangeable.

For instance, do not store the host component (e.g., 'payments.apcopay.tech') from the following URL as a base URL in your configuration:

https://payments.apcopay.tech/merchanttools/api/Redirect/Loader?token=f86dff7b36aa4401bbb92c88280d6db4

The token highlighted above is just an example.

All components of this URL, including the host, may change over time. To ensure flexibility and future-proof your integration, treat the entire URL as dynamic and subject to change.

2. Consistent Use of Standard Data Formats

Adopt a consistent data format, such as JSON, for both requests and responses. This practice ensures compatibility and simplifies integration across different platforms, making your APIs more developer-friendly and easier to work with.

3. Use of Standardised HTTP Status Codes

Always use standard HTTP status codes to indicate the outcome of API requests. This provides clients with a clear, universally recognized method to interpret and handle responses effectively.

4. Implement Secure Authentication

Ensure API access is protected by implementing secure authentication methods, such as Basic Authorization with Base64-encoded credentials. Always transmit credentials over secure channels (e.g., HTTPS) to prevent unauthorized access.

5. Environment Separation for Testing

Offer a dedicated testing environment where developers can safely conduct test transactions without impacting live data. This can be achieved by including a test mode flag (e.g., IsTest set to true) in API requests, allowing for the simulation of real-world scenarios in a controlled setting.

6. Ensure Data Integrity through Idempotency

To prevent duplicate transactions, implement idempotency by using unique references (e.g., UniqueReference) in transaction requests. This is crucial for resilient handling in scenarios where multiple transaction attempts are linked to a single OrderReference.

7. Enhance Security with HMAC Signatures

Protect your API requests and ensure data integrity by utilizing HMAC SHA256 signatures. This involves computing and verifying signatures based on specific request attributes before executing any business logic, adding an extra layer of security to your API operations.

8. Efficient Handling of Redirection

After payment processing, always validate the response ('isSuccess' flag) before redirecting clients to the next step in the payment process. Use the provided 'redirectURL' to guide the user accordingly.

9. Separation of Concerns for Transaction Status Updates

Avoid using client-side redirection query strings to update transaction statuses in your back office. Instead, implement server-side listeners (webhooks) that handle transaction status updates independently. This approach ensures more reliable and secure status updates, as it separates transaction processing from client-side operations.

10. Robust Webhook Implementation

Implement webhooks to handle critical transaction notifications. Webhooks reduce reliance on client-side actions, ensuring that important transaction updates are received even if the user’s browser fails. You can find more information on our Callback Notifications here.

11. Consistent Signature Algorithm Application

Ensure that the same signature algorithm is consistently applied across all stages of the transaction process—such as the initial request, redirection, and webhook notifications. This practice helps verify the integrity and authenticity of data throughout the entire process, preventing tampering and ensuring that each part of the transaction is securely validated. By maintaining consistency in your signature algorithms, you enhance the overall security and reliability of your transaction handling.

12. Fallback Mechanisms

Implement robust fallback mechanisms, such as webhooks, to handle scenarios where client-side operations might fail due to issues like poor connectivity, browser closures, or timeouts. This ensures that events are reliably processed and no data is lost. By utilizing server-side listeners, you can ensure that transaction statuses and other critical updates are captured and handled even if the client-side interaction is interrupted or unreliable.