Draft: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

Property name Property type Limitations and constraints Description
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 bool
  • Required
  • 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.
 Determines whether the payer needs an active Barion Wallet to complete the payment.
FundingSources string[]
  • Required
 The list of payment methods that the Barion Smart Gateway will display to the payer.

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
  • Maximum length: 100 characters
 The Barion shop’s unique string identifier for the payment.
RedirectUrl string
  • Required
  • Maximum length: 2000 characters
  • Defaults to the URL of the Barion shop whose POSKey you passed.
 The URL string where the payer will be redirected after completing the payment.
CallbackUrl string
  • Required
  • Maximum length: 2000 characters
  • Defaults to the URL of the Barion shop whose POSkey was passed.
 The URL string where the Barion server will send a request whenever there’s a change in the payment’s state.

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 PaymentTransaction[]
  • Required
 The list of payment transactions included in the payment. See also: Facilitated payments
Locale string
  • Required
  • Maximum length: 10 characters
  • 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)
 The language that the Barion Smart Gateway will be displayed in.
Currency string
  • Required
  • One of the following ISO 4217 currency code strings:
  • "CZK" (Czech crown)
  • "EUR" (Euro)
  • "HUF" (Hungarian forint)
  • "USD" (U.S. dollar)
 The currency that the transactions in the payment are made in. Only one currency is accepted per payment, for all transactions included in the payment.
OrderNumber string
  • Optional but best practice
  • Maximum length: 100 characters
 A string 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 TimeSpan (d.hh:mm:ss)
  • Required when calling the endpoint as part of a reservation payment scenario
  • A timespan between 1 minute and 1 year, inclusive, in the d.hh:mm:ss format.
  • Defaults to 0.00:30:00 (30 minutes).
 The time window allowed for a Barion shop to finalize (finish) a reserved payment. 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 TimeSpan (d.hh:mm:ss)
  • Required when calling the endpoint as part of a delayed capture scenario.
  • 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).
 The time window allowed for a Barion shop to finalize (complete) a delayed capture payment. 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 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. Read more in the guides about one-click payments and subscriptions.
RecurrenceId string 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 Read more in the guides about one-click payments and subscriptions.
RecurrenceType string[]
  • 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.
 Indicates the type of token payment scenario that the payment is a part of.
TraceId string
  • Required when the payer’s payment instrument is tokenized for later reuse: one-click payment, subscription, or MIT
  • Maximum length: 100 characters
 A string that identifies both the payer’s payment instrument, and the type of token payment scenario it is used in. For more details, see the dedicated guide.
ShippingAddress ShippingAddress
  • 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 BillingAddress
  • 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 string
  • Optional, but contributes to the payer not being challenged to authenticate themselves during the payment
  • A valid email-format string of up to 256 characters
 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
  • Max length: 30 characters
  • Expected format: ”<two-digit country code>123456789”, with no leading zeros.
 The payer’s phone number. For more details, see the dedicated guide.
PayerWorkPhoneNumber string
  • Optional, but contributes to the payer not being challenged to authenticate themselves during the payment
  • Max length: 30 characters
  • Expected format: ”<two-digit country code>123456789”, with no leading zeros.
 The payer’s work phone number. For more details, see the dedicated guide.
PayerHomeNumber string
  • Optional, but contributes to the payer not being challenged to authenticate themselves during the payment
  • Max length: 30 characters
  • Expected format: ”<two-digit country code>123456789”, with no leading zeros.
 The payer’s home phone number. For more details, see the dedicated guide.
PayerAccountInformation PayerAccountInformation
  • 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 PurchaseInformation
  • 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 ChallengePreference
  • 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. For more details, see the dedicated guide.
PaymentWindow TimeSpan (d.hh:mm:ss)
  • Optional
  • A timespan between 1 minute and 7 days, inclusive, in the d.hh:mm:ss format.
  • Defaults to 0.00:30:00 (30 minutes).
 The time window for the payer to make the payment, after which the payment can no longer be completed:

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

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.

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.

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=Draft:Payment-Start-v2&oldid=4608"