Responsive web payment

This scenario is the most common integration for webshops that don't need any extra steps in the payment process.

The payment process

1. In this scenario the payment starts with the preparation of the payment. This means that the webshop creates a JSON representation of the payment data. This data contains all the necessary information about the items to be purchased, the customer and the desired payment scenario. This JSON should be sent as the body of a POST request to the /v2/Payment/Start API endpoint. After the system recives the data it will be validated. If all the properties are correct a payment will be prepared in the database and a HTTP response is returned to the webshop.
2. The response should be processed by the webshop system and the Id of the payment (PaymentId) should be extracted from the response. This Id should be stored in the webshop database with the initial information about the payment. This is necessary because every following request is based on this Id.
3. The next step is to redirect the customer to the Barion website to a specific URL with the PaymentId as a query parameter.
4. After the customer paid the requested amount and the payment is completed a server to server request is initiated by Barion towards the webshop. This is called the callback mechanism.
5. At this point the customer is advised on the screen to return to the webshop to complete the process. If the customer clicks through the customer is redirected back to the webshop.
6. At any point of the process the webshop can request information about the payment through the v2/Payment/GetPaymentState API endpoint.

Preparing the payment

To prepare a new payment an HTTP POST request should be made to the /v2/Payment/Start API endpoint. The body of this request should contain a well-formed JSON representation of the desired payment process. To see the full specification of this endpoint head over to the API reference.

The structure of a Barion Gateway payment is hierarchical. The payment is the meta information that describes the process. This payment contains at least one transaction. The transaction represents a financial transfer from a customer to a seller. The payment can contain multiple transactions, this is up to the webshop to decide how the structure of the whole process should be represented.

To make sure that the payment can be properly identified always generate an Id for the payment, that is is unique in the webshop. This should be sent in the PaymentRequestId property. This is true for all the transactions attached to the payment. For this user the POSTransactionId of the PaymentTransaction entity. If the webshop only handles one transaction per payment it is possible to use the same Id for both the PaymentRequestId and the POSTransactionId although it is not recommended.

In this scenario the PaymenType should be set to Immediate indicating that the financial transaction should take place immediately after the successful customer charge.

Processing the response

TODO

Redirecting the customer

TODO

Processing the callback

TODO

Requesting information about the payment

TODO

Processing the returning customer

TODO