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
PosKeyquery 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
paymentIdwill 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,RecurrenceIdis the new unique identifier that the Barion shop operator assigns to the token payment - if
InitiateRecurrence: false,RecurrenceIdis 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.
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": "[YOUR_SECRET_POSKEY]",
"PaymentType": "Immediate",
"PaymentRequestId": "[THE_ID_YOU_GENERATE_FOR_THE_PAYMENT]",
"GuestCheckOut": true,
"FundingSources": [ "ALL" ],
"Currency": "EUR",
"RedirectUrl": "[WWW:EXAMPLE:COM]",
"CallbackUrl": "[YOUR_WEBHOOK_LISTENER_ENDPOINT]",
"Locale": "ab-AB",
"Transactions": [
{
"POSTransactionId": "[THE_ID_YOU_GENERATE_FOR_THE_TRANSACTION]",
"Payee": "[YOUR_BARION_WALLET_EMAIL]",
"Total": [THE_PURCHASE_AMOUNT_1000_IN_THIS_EXAMPLE],
"Items": [
{
"Name": "[NAME_OF_PURCHASED_ITEM]",
"Description": "placeholder",
"Quantity": 1,
"Unit": "piece",
"UnitPrice": 1000,
"ItemTotal": 1000 }
]
}
]
}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.