Payment-Start-v2

Barion API: Initialize a new payment

POST	/{API_version}/Payment/Start

POST /{API_version}/Payment/Start sets up a new payment in the Barion Smart Gateway.

API Version

v2

Authentication

The endpoint requires Barion shop authentication: pass the call to the endpoint your Barion shop’s POS key as the x-pos-key header parameter.

An invalid POS key generates an AuthenticationFailed error.

GET API endpoints below v4 also accept the PosKey query parameter.

Request

Required headers

N/A

Request body parameters

Required parameters

You’ll need to pass the following parameters when calling the endpoint no matter the payment scenario.

POSKey

The secret guid that authenticates the Barion shop that’s preparing the payment.

Always required.

PaymentType

Determines whether the payer’s selected payment method is expected to be charged immediately, or whether the payments funds are only reserved, and the actual payment is completed within a preset time window. One of the following strings: “Immediate”, “Reservation”, or “Delayed capture”.

Always required.

GuestCheckout

Determines whether the payer needs an active Barion Wallet to complete the payment.

A boolean value; integer evaluation isn’t supported.

Always required.

For reasons of fraud control, payers must supply a valid email address even if guest checkout is allowed.

FundingSources

The list of payment methods that the Barion Smart Gateway will display to the payer.

An array of one or more strings from the FundingSources enumeration.

Always required.

Intended to help book-keeping: this parameter is included in the shop owner’s (monthly or daily) Barion Wallet statement, as well as their transaction history.

PaymentRequestId

The Barion shop’s unique string identifier for the payment.

Always required.

RedirectUrl

The URL string where the payer will be redirected after completing the payment.

Required but if not passed explicitly, defaults to the URL of the Barion shop whose POSkey was passed.

CallbackUrl

The URL string where the Barion server will send a request whenever there’s a change in the payment’s state.

Required but if not passed explicitly, defaults to the URL of the Barion shop whose POSkey was passed.

The payment’s paymentId will be included in the request as a query string to specifically identify the payment.

Read more about how callbacks work in the dedicated guide.

Transactions

The list of payment transactions included in the payment: one or more PaymentTransaction objects

Always required.

Locale

The language that the Barion Smart Gateway will be displayed in.

One of the following strings:

• “cs-CZ” (Czech)
• “de-DE” (German)
• “en-US” (English)
• “es-ES” (Spanish)
• “fr-FR” (French)
• “hu-HU” (Hungarian)
• “sk-SK” (Slovak)
• “sl-SI” (Slovenian)

Always required.

Currency

The currency that the transactions in the payment are made in.

One of the following ISO 4217 currency code strings:

• “CZK” (Czech crown)
• “EUR” (Euro)
• “HUF” (Hungarian forint)
• “USD” (US dollar)

Always required.

Only one currency is accepted per payment, for all transactions included in the payment.

Reservation payment parameters

This parameter is required only when calling the endpoint as part of a reservation payment scenario.

ReservationPeriod

The time window allowed for a Barion shop to finalize (finish) a reserved payment: A timespan between 1 minute and 1 year, inclusive, in the d.hh:mm:ss format.

The default value is 0.00:30:00 (30 minutes).

Required only for payments where the PaymentType is “Reservation”.

Reserved payments not finished within the configured ReservationPeriod the payer is refunded the reserved amount.

For details about reserved payments, see the dedicated guide.

Delayed capture parameters

This parameter is required only when calling the endpoint as part of a delayed capture scenario.

DelayedCapturePeriod

The time window allowed for a Barion shop to finalize (complete) a delayed capture payment: A timespan between 1 minute and 7 days, inclusive, in the d.hh:mm:ss format.

The allowed maximum value is 21 days for Barion shops registered to a business in Hungary.

The default is 7.00:00:00 (7 days).

Required only for payments where the PaymentType is “DelayedCapture”.

If the transactions in a delayed capture payment isn’t completed within the configured time window, the authorization on the payer’s payment instrument for the payment amount is canceled.

For details about delayed capture payments, see the dedicated guide.

Token payment parameters

Parameters related to payment scenarios where the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT.

InitiateRecurrence

A boolean that indicates whether the Barion shop is authorized to store tokenized details of the payer’s payment instrument so future payments don’t involve the Barion Smart Gateway.

Only required for token payment scenarios.

Read more in the guides about one-click payments and subscriptions.

RecurrenceId

Unique string identifier of up to 100 characters identifying the payer generated by the Barion shop operator for a token payment whose function depends on the value of InitiateRecurrence:

• if InitiateRecurrence: true, RecurrenceId is the new unique identifier that the Barion shop operator assigns to the token payment
• if InitiateRecurrence: false, RecurrenceId is the existing identifier that was assigned to the token payment during the initial payment in the scenario

Only required for token payment scenarios.

Read more in the guides about one-click payments and subscriptions.

RecurrenceType

Indicates the type of token payment scenario that the payment is a part of: one of the strings in the RecurrenceType enumeration.

Required to comply with the 3-D Secure authentication protocol if the payment is part of a token payment scenario. For more details, see the dedicated guide.

TraceId

A string of up to 100 characters that identifies both the payer’s payment instrument, and the type of token payment scenario it is used in.

Only required for subsequent payments in token payment scenarios (one-click payments and subscriptions)

Required to comply with the 3-D Secure authentication protocol if the payment is part of a token payment scenario. For more details, see the dedicated guide.

3-D Secure related parameters

While not required, the more parameters in this group you pass to the endpoint request, the less likely it is that the payer will be challenged to authenticate themselves during the payment.

For more details, see the dedicated guide.

ShippingAddress

The shipping address associated with the payment, if applicable: a ShippingAddress object

Providing this parameter helps the anti-fraid analysis get more accurate results.

BillingAddress

The billing address associated with the payment, if different from the shipping address: a BillingAddress object

PayerHint

A placeholder email address used to pre-populate the Barion Wallet login when the payer is redirected to the Barion Smart Gateway: a valid email-format string of up to 256 characters.

CardHolderNameHint

A placeholder string between 2 and 45 characters, used to pre-populate the cardholder name field when the payer is redirected to the Barion Smart Gateway.

PayerPhoneNumber

The payer’s phone number. A string of up to 30 numeric characters in the following format”<two-digit country code>123456789”, with no leading zeros.

PayerWorkPhoneNumber

The payer’s work phone number. A string of up to 30 numeric characters in the following format”<two-digit country code>123456789”, with no leading zeros.

PayerHomeNumber

The payer’s home phone number. A string of up to 30 numeric characters in the following format”<two-digit country code>123456789”, with no leading zeros.

PayerAccountInformation

Details about the payer’s account in the Barion shop operator’s system: a PayerAccountInformation object

PurchaseInformation

Details about the purchase associated with the payment: a PurchaseInformation object

ChallengePreference

The Barion shop’s preference for whether they’d like to raise or lower the chances of the payer being authenticated during the purchase using the 3-D Secure authentication protocol.

One of the strings in the ChallengePreference enumeration

Optional paremeters

These parameters either have a default value or are only indirectly related to the payment.

OrderNumber

A string of up to 100 characters that identifies of the order that the payment settles, generated by the Barion shop operator.

Intended to help book-keeping: this parameter is included in the shop owner’s (monthly or daily) Barion Wallet statement, as well as their transaction history.

PaymentWindow

The time window for the payer to make the payment, after which the payment can no longer be completed: A timespan between 1 minute and 7 days, inclusive, in the d.hh:mm:ss format.

The default value is 0.00:30:00 (30 minutes).

Optional parameter.

Example request

{
  "PosKey": "placeholder",
  "PaymentType": "Immediate",
  "PaymentRequestId": "placeholder",
  "GuestCheckOut": true,
  "FundingSources": [ "ALL" ],
  "Currency": "EUR",
  "RedirectUrl": "placeholder",
  "CallbackUrl": "placeholder",
  "Locale": "ab-AB",
  "Transactions": [
    {
      "POSTransactionId": "placeholder",
      "Payee": "placeholder",
      "Total": "placeholder",
      "Comment": "placeholder",
      "Items": [
        {
          "Name": "placeholder",
          "Description": "placeholder",
          "Quantity": 1,
          "Unit": "placeholder",
          "UnitPrice": 1000,
          "ItemTotal": 1000,
          "SKU": "placeholder"
        }
      ]
    }
  ]
}

Response

The /{API_version}/Payment/Start endpoint returns a JSON object with the following properties.

PaymentId

The Barion server generated guid for the payment that the request initialized.

PaymentRequestId

The Barion shop’s unique string identifier for the payment that was passed as PaymentRequestId in the request.

Status

The payment’s current status within Barion: one of the string values in the PaymentStatus enumeration.

QRUrl

A URL to a QR code that represents the payment.

RecurrenceResult

String status of the tokenization or the subsequent charge to a tokenized payment instrument: “None”, “Failed”, “Successful”, “NotFound”, or “ThreeDSAuthenticationRequired”.

For details, see the dedicated section.

Always returned, but only applies to payments that are part of a tokenized payment scenario

Transactions

All the transactions associated with the payment: an array of ProcessedTransaction object

Includes all applicable Barion-deducted fees.

GatewayUrl

The URL of the Barion Smart Gateway where the payer needs to be redirected for payment.

Includes the PaymentId as a query string.

CallbackUrl

The URL where the Barion server sends a request each time there is a change in the payment’s status.

Includes the PaymentId as a query string.

If no CallbackURL was passed in the request, this property defaults to the URL of the Barion shop whose POSkey was passed.

RedirectUrl

The URL where the payer is redirected once they complete the payment. Includes the PaymentId as a query string.

If no RedirectURL was passed in the request, this property defaults to the URL of the Barion shop whose POSkey was passed.

ThreeDSAuthClientData

Encrypted client authentication data, as a string, required for 3-D Secure processing.

Pass this data to the off-site authentication library if a token payment was rejected because of missing authentication.

TraceId

A unique string identifier generated by the card issuer to represent and track the payment instrument in token payment scenarios that require 3-D Secure authentication.

How to interpret RecurrenceResult

Value	Description
None	Either the payment isn’t part of a token payment scenario, or, if InitiateRecurrence: true (and no RecurrenceId) was passed in the request, the tokenization was successful, but no attempt has been made to use the token.
Successful	InitiateRecurrence: false and a RecurrenceId was passed in the request, and the previously tokenized payment instrument has been successfully used to complete the payment.
Failed	InitiateRecurrence: false and a RecurrenceId was passed in the request, but the previously tokenized payment instrument couldn’t be charge to complete the payment.
NotFound	The RecurrenceId passed in the request is invalid, or the previous tokenization had been unsuccessful.
ThreeDSAuthenticationRequired	InitiateRecurrence: false and a RecurrenceId was passed in the request, but the payment didn’t go through because The holder of the card whose token you registered is challenged to perform 3-D Secure authentication. Perform off-site 3-DS authentication, or pass the TraceId associated with the payment instrument in the request.

Example response

{
  "PaymentId": "ebded28e481fef118c08001dd8b71cc5",
  "PaymentRequestId": "ALMA-BARACK-03",
  "Status": "Prepared",
  "QRUrl": "https://api.test.barion.com/qr/generate?paymentId=ebded28e-481f-ef11-8c08-001dd8b71cc5&size=Large",
  "Transactions": [
    {
      "POSTransactionId": "ALMA-BARACK-CEKLA-01",
      "TransactionId": "ecded28e481fef118c08001dd8b71cc5",
      "Status": "Prepared",
      "Currency": "HUF",
      "TransactionTime": "0001-01-01T00:00:00",
      "RelatedId": null
    },
    {
      "POSTransactionId": null,
      "TransactionId": "edded28e481fef118c08001dd8b71cc5",
      "Status": "Reserved",
      "Currency": "HUF",
      "TransactionTime": "2024-05-31T12:23:17.868",
      "RelatedId": null
    }
  ],
  "RecurrenceResult": "None",
  "ThreeDSAuthClientData": null,
  "GatewayUrl": "https://secure.test.barion.com/Pay?Id=ebded28e481fef118c08001dd8b71cc5",
  "RedirectUrl": "https://example.com/?paymentId=ebded28e481fef118c08001dd8b71cc5",
  "CallbackUrl": "https://webhook.site/3209de0d-d3fe-4256-aa01-d9c1cd04772c?paymentId=ebded28e481fef118c08001dd8b71cc5",
  "TraceId": null,
  "Errors": []
}

Integrating the endpoint

/{API_version}/Payment/Start relates to the point in the sales funnel when the customer confirms a purchase.

When implementing Full Barion Pixel, make sure that your webshop triggers the InitiatePurchase Barion Pixel event when this endpoint request returns.