Responsive web payment

From Barion Documentation
Revision as of 12:24, 4 February 2017 by Birot (talk | contribs) (Preparing the payment)
Jump to navigation Jump to search

Simple Webshop Integration

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


To be able to integrate your webshop with the Barion Payment Gateway,

  • you have to register a Barion wallet in the appropriate Barion environment (there are separate environments for testing and production).
  • For this wallet you have to register a shop and this should be approved by Barion.
  • For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be an USD account created in your wallet.
  • To make sure every corner case scenario works for your webshop it is best to topup that account with a small amount (aprrox. 5-10EUR or your choice of currency around the same value).
  • For the technical communication guide please read the this: TODO

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. The purchased products should be represented in the Items array of the transactions. The total payment amount will be calculated from the attached transactions. The amount specified for the items is not validated against the transaction Total it is up to the integrator to make sure it is calculated appropriately.


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 addition to this you can also provide an OrderNumber for the payment.

Payment scenario

In this scenario the PaymenType should be set to Immediate indicating that the financial transaction should take place immediately after the successful customer charge. This means that the amount charged will be placed immediately in the account of the webshop.

Every attached transaction has a Payee property. That property indicates the user wallet that will receive the amount of the transaction. It is very important to make sure that this wallet is the same wallet that opened the webshop. In technical terms the POSKey provided should belong to one of the Payee's shop. This is valid for all the transactions attached to the particular payment. If one of the payees is different the scenario autmatically will be upgraded to sharing economy scenario.


You can define the currency of the payment by specifying the Currency payment property. It is important to mention that multi-currency transactions are not supported. This means that the currency you define for the payment will be automatically the currency of all the attached transactions. The currency also defines the available precision of the transaction Total. For example for HUF payments no decimal digits allowed while for EUR payments two decimal digits can be used. To be able to receive payments in the selected currency the shop has to have an account created in that currency in the wallet. This means that if the shop only has HUF and USD accounts in its wallet, EUR payments will not be allowed to prepare.

Example preparation

This is an example POST Start with minimum provided information

    "POSKey": "630ee026-3e19-469f-8325-afc9bd1ae6a6",
    "PaymentType": "Immediate",
    "PaymentRequestId": "EXMPLSHOP-PM-001",
    "FundingSources": ["All"],
    "Currency": "EUR",
    "Transactions": [
            "POSTransactionId": "EXMPLSHOP-PM-001/TR001",
            "Payee": "[email protected]",
            "Total": 37.2,
            "Comment": "A brief description of the transaction",
            "Items": [
                    "Name": "iPhone 7 smart case",
                    "Description": "Durable elegant phone case / matte black",
                    "Quantity": 1,
                    "Unit": "piece",
                    "UnitPrice": 25.2,
                    "ItemTotal": 25.2,
                    "SKU": "EXMPLSHOP/SKU/PHC-01"
                    "Name": "Fast delivery",
                    "Description": "Next day delivery",
                    "Quantity": 1,
                    "Unit": "piece",
                    "UnitPrice": 12,
                    "ItemTotal": 12,
                    "SKU": "EXMPLSHOP/SKU/PHC-01"

Processing the successful response

After a successfully preparing the payment a JSON response is sent back as response. This JSON should be processed and some properties should be saved in the database of the webshop. The single most important property of this JSON is the PaymentId. This should be saved into the database of the webshop along the the ids of the transactions (TransactionId) attached.

The successful response will also contain the appropriate URL where the customer should be redirected so the integration doesn't have to hard-code any URL. This information is displayed in the GatewayUrl.

At this point the Status of the payment should be Prepared. This means that all the necessary information is prepared for the payment but no financial transfer happened yet.

In the Transactions array are all the transaction that were processed. This array also contains the various fee transactions as well. So if there are transaction here that are not familiar it's because they were not sent by the webshop.

Example success response

  "PaymentId": "31dfdaff269e4aa0b7a12e1c0cc2f933",
  "PaymentRequestId": "EXMPLSHOP-PM-001",
  "Status": "Prepared",
  "QRUrl": "",
  "Transactions": [
      "POSTransactionId": "EXMPLSHOP-PM-001/TR001",
      "TransactionId": "a4ead1d965bd48b3934847504c67ec8c",
      "Status": "Prepared",
      "Currency": "EUR",
      "TransactionTime": "2017-02-03T13:07:10.215",
      "RelatedId": null
  "RecurrenceResult": "None",
  "GatewayUrl": "",
  "RedirectUrl": "",
  "CallbackUrl": "",
  "Errors": []

Processing the successful response

If there is something wrong during the preparation an error response will be provided. If this happens the Errors array will be filled out with information about the problem.

Possible error responses

Error code Description
AuthenticationFailed The provided POSKey is invalid. Check that the key used is appropriate for the environment. The test and production environment are separate so the keys are only valid for one environment. Another problem could be that the provided key is the public key and not the private key. For API requests the secret API key should be used.
InvalidShop There is a problem with the shop.
InvalidUser Nem megfelelő felhasználó. Ellenőrizd, hogy az adott Barion környezetben létezik-e a megadott felhasználó.
UserCantReceiveEMoney A felhasználó nem fogadhat pénzt. Valószínűleg a felhasználó még nem a Barion rendszer része vagy már törölt felhasználó. A Barion fizetési rendszert használva nem fizethetsz nem regisztrált, regisztrált, de nem aktivált vagy törölt felhasználóknak.

Example error response

For example this is the error response when the authentication data (the POSKey) is not correct.

  "Errors": [
      "ErrorCode": "AuthenticationFailed",
      "Title": "User authentication failed.",
      "Description": "The login information provided is incorrect. There is no such user in the system or the password is incorrect.",
      "EndPoint": "",
      "AuthData": null,
      "HappenedAt": "2017-02-03T13:18:07.8878292Z"

Redirecting the customer

After a successful payment preparation the next step is to redirect the customer to the secure Barion site. The URL is provided in the response of the Payment/Start request.

Processing the callback


Requesting information about the payment


Asssembling the GET request

Processing the response

Processing the returning customer