Integration Best Practices

  • Updated on May 22, 2025
  • Published on Sep 4, 2024
  • 5 minute(s) read
Prev Next
  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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. Preference to FullPage vs iFrame for 3DS Browser Based authentication reliability

Due to lack of consistency from card issuers when handling 3DSecure Authentication redirects we recommend the use of a full page redirect rather than a iframe when loading the Hosted Payment Page since this guarantees more reliable handling across card issuers.

🔍 Justification and Industry Context:

Issuer and ACS Variability:

  • Different card issuers and Access Control Servers (ACS) implement 3D Secure authentication flows in different ways. Some expect full control of the browser context (e.g., top-level window) and may not render correctly in an iframe.
  • This behavior is inconsistent and outside the merchant or PSP’s control.

Security Measures in Browsers:

  • Modern browsers impose security restrictions on iframe usage, such as:

    • X-Frame-Options headers.
    • Cross-origin navigation blocking.

  • Some issuer ACS pages set X-Frame-Options: DENY or SAMEORIGIN, blocking iframe rendering entirely.

  • Others may rely on specific browser features (e.g., cookies, modal prompts) that fail in embedded iframe contexts.

EMVCo 3DS Best Practices:

  • The EMV 3-D Secure Browser SDK Implementation Guidelines and EMVCo’s 3DS best practices highlight the need to accommodate a wide range of issuer ACS implementations.
  • While EMVCo permits iframe-based challenge windows via the 3DS Method and Challenge frames, it does not guarantee that all issuers support this properly.

Scheme Recommendations:

  • Visa, Mastercard, and Amex documentation commonly recommend full-page redirects for the challenge flow to reduce the risk of failed authentications due to iframe limitations.
  • Example: Visa’s developer guides indicate that embedding the challenge flow in an iframe "may not be supported by all issuers", and therefore "a full-page redirect is preferred for broader compatibility."

📚 References:

  1. EMVCo 3-D Secure Protocol and Core Functions Specification v2.3.1*

  2. Visa Developer – 3DS Implementation Best Practices*

  3. Mastercard Identity Check – Integration Guidelines*

  1. 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.

  1. 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.

See Point 13 for additional availability considerations.

  1. Use Payment Notifications

Implement webhooks to as a priority 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.

See Point 13 for additional availability considerations.

Dynamic Webhooks

Based on the specific Provider/s utilized for payments, the webhook response may vary in structure. We recommend that webhook parsing logic is not strict to a rigid contract however JSON attributes should be parsed allowing for additional attributes that can be added over time.

See: Payment Notifications and Extended Payment Notification as a guide.

  1. Validate for Tempering on all interactions

Ensure that the same signature algorithm validation 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.

Tempering Validation vs Payload Validation

The application logic should calculate the signature based on the attributes/values in the received payloads and NOT the expected payloads schema. The code should give priority to checking whether the payloads / responses where tempered with as a first step. Since response payloads may change due to specific provider requirements or new platform capabilities, payload validation should be treated separately to tempering validation

(e.g. Providers may introduce new flows that mandate the transmission of additional attributes)

  1. Consider Fallback Mechanisms

Implement robust fallback mechanisms, such as webhooks and server to server checks, 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.

Optional Transaction Status Implementation

You may consider to implement out of band mechanisms using the Get Payment Response operation alongside webhooks for covering cases where you need to increase resiliency in processing a payment response.