Interaction Types

In the context of payment processing the involved entities are:

the User and the User's Web Browser.
the Merchant System (usually a custom web application offering some goods/services).
the PXP Financial Payment Service providing an API for unified access to different payment methods,
and having the responsibility to process and keep track of all payments, and
the External Payment Providers – numerous external systems with their specific APIs.

This section lists the 3 standard interaction types between the involved parties above. Every payment method falls into one of these 3 interaction types:

Synchronous Execution
Redirection to External Payment Provider
Offline Execution.

Synchronous Execution

Step	Description
1	The Merchant System calls the `initiatePayment` web service method.
2	The Merchant System receives a synchronous initiatePaymentResponse with the last state of the payment indicating if it was successfully executed or not.
3	An asynchronous notification is sent in the background from the PaymentService to the Merchant System with the payment status.

Redirection to External Payment Provider

Certain payment methods require redirecting the user to the External Payment Provider for authentication and transaction confirmation purposes. There are 2 variations of how PXP Financial receives the processing result from the External Payment Provider:

data is passed with a background notification from External Payment Provider to PXP Financial
data is passed as part of the browser redirect from External Payment Provider to the Merchant, and then with an API call from Merchant to PXP Financial.

Passing data with a background notification

The transaction status data gets passed back through a callback (system-to-system API call in the background) from the External Payment Provider to PaymentService. See the below diagram for more details:

Step	Description
1	The Merchant System calls `initiatePayment` web service method and gets back a `RedirectionUrl`.
2	The Merchant System redirects the user to the RedirectionUrl / External Payment Provider, where the user authenticates and authorizes the payment.
3	The External Payment Provider processes the user request and redirects the user to `SuccessPageUrl` or `ErrorPageUrl`.
4	In case of a successful payment, the Merchant System receives an asynchronous notification.

Passing data as part of the browser redirect

The transaction status gets passed together with the HTTPS redirection of the user from the External Payment Provider's website to the Merchant's website usually as HTTPS POST or GET data). See the below diagram for more details:

Step	Description
1	The Merchant System calls the `initiatePayment` web service method and gets back a `RedirectionUrl`.
2	The Merchant System redirects the user to the RedirectionUrl of the External Payment Provider.
3	The External Payment Provider processes the user request and returns data with the redirect back to the Merchant's website.
4	The Merchant System collects all data from the HttpRequest received from External Payment Provider and calls the `handleProviderNotificationToMerchant` web service method.
5	The Merchant System receives back the `handleProviderNotificationToMerchantResponse` and depending on the state of the payment decides to take further action.
6	In case of a successful payment the Merchant System receives an asynchronous notification.

Offline Execution

Other payment methods require that the user performs an offline transaction (e.g. by going to his bank, or to a terminal). In these cases only the destination payment data (e.g. destination bank account or Western Union account) is displayed and a reference is generated for the user’s offline transaction. In some cases a transaction is initiated/prepared as well. The following diagram visualizes the flow:

Step	Description
1	Merchant System sends a `getPaymentInputDataRequest` (see getPaymentInputData) and receives a list of inputs that it will display to the user.
2	PXP Financial notifies the merchant to process the payment (`handlePaymentStateChangedNotificationRequest`) after it has been notified by the External Payment Provider that the offline payment took place.