Payment-Start-v2

From Barion Documentation
Jump to navigation Jump to search

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.

Request

Required headers

Your Barion shop’s POS key as the x-pos-key header parameter

Request body parameters

POSKey

guid

required

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

PaymentType

string

required

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”.

GuestCheckout

Boolean

required

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

A Boolean value; integer evaluation isn’t supported.

Defaults to false.

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

FundingSources

array

required

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.

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

string

required

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

RedirectUrl

string

required

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

string

required

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

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

array

required

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

Locale

string

required

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)

Currency

string

required

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)

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

OrderNumber

string

optional

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.

ReservationPeriod

string

required when calling the endpoint as part of a reservation payment scenario

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.

Defaults to 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.

DelayedCapturePeriod

string

required when calling the endpoint as part of a delayed capture scenario.

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.

Defaults to 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.

InitiateRecurrence

Boolean

required when the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT

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

string

required when the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT

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

string

required when the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT

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

string

required when the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT

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.

ShippingAddress

a ShippingAddress object

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

The shipping address associated with the payment, if applicable.

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

For more details, see the dedicated guide.

BillingAddress

a BillingAddress object

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

The billing address associated with the payment, if different from the shipping address.

For more details, see the dedicated guide.

PayerHint

a valid email-format string of up to 256 characters

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

A placeholder email address used to pre-populate the Barion Wallet login when the payer is redirected to the Barion Smart Gateway.

For more details, see the dedicated guide.

CardHolderNameHint

string

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

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.

For more details, see the dedicated guide.

PayerPhoneNumber

string

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

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.

For more details, see the dedicated guide.

PayerWorkPhoneNumber

string

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

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.

For more details, see the dedicated guide.

PayerHomeNumber

string

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

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.

For more details, see the dedicated guide.

PayerAccountInformation

a PayerAccountInformation object

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

Details about the payer’s account in the Barion shop operator’s system.

For more details, see the dedicated guide.

PurchaseInformation

a PurchaseInformation object

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

Details about the purchase associated with the payment.

For more details, see the dedicated guide.

ChallengePreference

string

optional, but contributes to the payer not being challenged to authenticate themselves during the payment

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.

For more details, see the dedicated guide.

PaymentWindow

string

optional

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.

Defaults to 0.00:30:00 (30 minutes).

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.

Retrieved from "https://docs.barion.com/index.php?title=Payment-Start-v2&oldid=4601"