Asynchronous Flows

Flows may vary in their communication modes and in the steps you may require customers to follow in order to complete a payment. In this topic we will explore two types of communication modes that a payment flow may implement: asynchronous and synchronous modes. We will also explore the implementation of a redirection flow as means of redirecting customers to a third party platform for completing additional steps needed to finalize a payment.

Synchronous vs. Asynchronous Payment Flows and Operations

Payment flows and operations can either be synchronous or asynchronous. In synchronous flows and operations, the final status (Succeed or Failed) of a transaction is returned immediately. In asynchronous flows and operations, the transaction may first return a status of Pending before returning a final status indicating the success or failure of the transaction request. The provider you are transacting against determines whether a flow or operation is synchronous or asynchronous.

Bear in mind that your mode of working may differ depending on whether a flow or operation is synchronous or asynchronous. In synchronous flows and operations, you can immediately act upon the response status of a transaction. Asynchronous flows and operations, in contrast, require you to check for a change in status before you can invoke the next step in your payment flow. You can register to receive a webhook that will inform you the moment a transaction request changes its status. Read more about Webhooks for additional information.

Implementing a Redirection Flow

Redirection refers to an asynchronous process in which customers are diverted to a third-party platform to finalize a payment, before returning to the web page on which you inform customers that the transaction has been completed. Examples include:

3D Secure (3DS) authentication, in which a transaction initiates a redirection to an authentication page of the card issuing bank, where customers then need to authenticate themselves to authorize the transaction.
Pay by Link (PBL), in which you send your customer a payment link (in an email, text message etc.) and then redirect the customer to a hosted secure payment page to complete the payment.

If the provider you are transacting against supports a redirection flow, then you can setup PaymentsOS to handle the redirection flow as well. The following image illustrates a redirection flow.

Payment Flow

Implementing a redirection process requires some additional integration procedures, both in PaymentsOS and in the provider’s configuration environment. The purple numbers in the image above, indicate a step that requires additional configuration on your behalf:

Step 2: When invoking the Create Authorization API or Create Charge API, pass in a merchant_site_url. This is the URL to which customers will be redirected once they have completed the payment process.
Steps 5 and 6: When receiving a reply from the Create Authorization API or Create Charge API, redirect your customers to the page on which they need to perform the required action. We provide you with the page URL in the Redirection object of the authorization or charge response data.
Step 8: The provider sends an update to a callback endpoint URL, the moment the customer completed the authentication process and the status of the transaction changed. Some providers require that you configure the callback’s endpoint URL in the provider’s configuration environment (this endpoint is sometimes known as the IPN URL, or Instant Payment Notification URL). PaymentsOS monitors the endpoint and informs you of a change in the transaction’s status through a webhook notification. Refer to the Provider Integration Guides for integration procedures that are specific to each provider.
Step 9: PaymentsOS will extend the merchant_site_url with the following parameters: payment_id, authorization_id or charge_id and the authorization status. You can use these parameters to provide customers with additional information about the transaction. Here’s an example of additional parameters added to the merchant_site_url (notice that the status of the transaction may still be ‘pending’ when we redirect your customer back to your site):
```
<merchant_site_url>
?payment_id=dd1fbe34-4636-4a61-8cb1-27ac8a175284
&authorization_id=aec1c306-e0f7-452b-8fb5-5b34489e9d10
&status=Pending
```
Step 10: If the required action was completed successfully, the transaction will have transitioned to a status of Succeed (and alternatively to Failed, if the action failed). In your PaymentsOS test or live environment, make sure you configured the webhook endpoint to which PaymentsOS will send a notification informing you of a change in the transaction’s status. Read more about Webhooksfor additional information.

Important Note

As shown in step 9 above, the url of your site to which customers are redirected after completing a transaction will also include a transaction status. You should only use this status for providing customers with additional information about the transaction. Do not use this status for determining the final transaction status. To determine the final transaction status, you must solely rely on the status received in the webhook notification.

Last modified February 12, 2023