Integration best practices

The sections below contain advice and recommendations from our engineers based on their experience with real use cases. None of the suggestions are strictly required but we believe that they will help you integrate ProcessOut into your payment flow more easily and effectively.

Webhooks

Webhooks are very powerful because they give you rapid updates about any transaction status changes. The Event object associated with a webhook message contains the full details of the transaction, including the history of operations that have been performed.

Webhooks are especially useful for handling Alternative Payment Methods (APMs). APMs differ in the features they offer. For example, some APMs allow separate authorization and capture stages (as with card payments) but others do not. What most APMs do have in common is an asynchronous flow from the merchant's website or app to the APM's website and back again. However, even when the APM redirects the customer back to the merchant successfully, this does not necessarily mean the payment was also successful. For this reason, we recommend using webhooks to detect when a payment is captured and respond accordingly.

Advice:

• Use webhooks to update any transaction data that you are storing in your own database. You can check transactions simply by fetching and inspecting them periodically but this is time-consuming when you have a lot of active transactions. Webhooks let you respond quickly and they give you a powerful "single source of truth" that you can use to manage updates whenever a transaction's status changes.

• Rely on webhooks to confirm when a payment is successfully captured and use your webhook code to start shipment of goods or supply of services. With this approach, you can use the same handler code for cards and APMs. You can also handle APMs identically whether or not they support separate authorization and capture.

• Process webhook messages by initially adding them to a queue and then responding to them when the load on your server is low. If you respond to the messages synchronously as they arrive, your server can easily get overloaded during busy periods.

Batch operations

We impose a rate limit on the operations you can perform with our API. This applies to all operations, not just transactions. We do this to balance the load among all merchants and prevent spikes in one merchant's activity from causing delays to other merchants' transactions. This rate limit will not delay or obstruct everyday business but you might notice it if you run batch operations, such as compiling a report from many invoices. You should manage batch operations carefully to avoid using too many of your available operations in a short space of time and delaying
your business transactions as a result.

Advise: Start large batches slowly and allow a long time for them to run. Contact us for advice on designing your batch operations to get the best results.

Testing

It is naturally very important to test your code. We provide our own sandbox environment for safe testing and you can also use the sandboxes supplied by Payment Service Providers (PSPs) with ProcessOut. You should use both options for a complete end-to-end test, but note that sandboxes from different PSPs tend to have different production behavior. This can make automated testing more complex if several PSPs are involved.

Advice: Use our sandbox during implementation and for running automated tests. Use PSPs' sandboxes for subsequent manual testing and for checking that your API credentials are working correctly.