Payment-Start-v2: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
(rollback to Nov 2022)
Tag: Manual revert
 
(4 intermediate revisions by the same user not shown)
Line 5: Line 5:
{{api_callmethod
{{api_callmethod
|method=POST
|method=POST
|uri=/{API_version}/Payment/Start
|uri=/v2/Payment/Start
}}
}}


POST /{API_version}/Payment/Start sets up a new payment in the Barion Smart Gateway.<span id="api-version"></span>
The <code>/payment/start</code> API endpoint is used to create a new payment in the Barion system.
== API Version ==


v2<span id="authentication"></span>
Prerequisites before use:
== Authentication ==
* [[Creating_an_account|Creating an account in Barion]]
* [[Creating_a_shop|Creating a shop in Barion]]
* [[Calling_the_API|Calling the Barion API]]


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


An invalid POS key generates an <code>AuthenticationFailed</code> error.
<span class="api-ver">v2</span> This API endpoint is available in '''API v2''' only.
== Request ==
=== Required headers ===


Your Barion shop’s POS key as the <code>x-pos-key</code> header parameter
== Authentication ==


=== Request body parameters ===
[[Barion Shop Authentication]]


==== POSKey ====
== Use cases ==
guid


required
This API endpoint is designed to be used in the following scenarios:
* [[Responsive_web_payment|Responsive Web Payment]]


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


==== PaymentType ====
{|
string
|-
|{{3dsfield}} || Properties marked with this must be provided to comply with 3D Secure authentication. The more attributes you provide the more chance you have to avoid the challenge flow.
|-
|}
'''Important:''' if the merchant does not provide 3DS-related properties, it doesn't mean that the payment will fail. It means that the payer will have a higher chance of getting a challenge during payment.


required
{{api_input_table_header}}
|-
| POSKey || Guid ||
* Required
|| The secret API key of the shop, generated by Barion. This lets the shop to authenticate through the Barion API, but does not provide access to the account owning the shop itself.


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 ====
| PaymentType || string ||
Boolean
* Required
* Accepted values:
** "Immediate"
** "Reservation"
** "DelayedCapture"
|| The type of payment, which can be either immediate or a money reservation. Reservation means that the shop has a time window to finish the payment (even though the money transaction still takes place immediately). Reservation amounts can be modified during this time window unless the new amount is lower than the original.
Click here to learn more about reservation payments: [[Reservation_payment|Reservation payments]], and delayed capture: [[Delayed_Capture|Delayed capture]].


required
|-


Determines whether the payer needs an active Barion Wallet to complete the payment.
| ReservationPeriod || TimeSpan (d.hh:mm:ss) ||
* Required only if PaymentType is "Reservation"
* Minimum value: one minute
* Maximum value: one year
* Default value: 30 minutes
|| Only makes sense at reservation payments. This is the time window that allows the shop to finish (finalize) the payment. If this does not happen within the time window, the system refunds the payment amount to the payer.


A Boolean value; integer evaluation isn’t supported.
|-


Defaults to <code>false</code>.
| DelayedCapturePeriod || TimeSpan (d.hh:mm:ss) ||
* Required only if PaymentType is "DelayedCapture"
* Minimum value: one minute
* Maximum value: 7 days (21 days in case of a Hungarian shop)
* Default value: seven days
|| This is the time window that allows the shop to complete (finalize) the payment. If this does not happen within the time window, the system releases the payment amount.


<blockquote>For reasons of fraud control, payers must supply a valid email address even if guest checkout is allowed.
|-
</blockquote>


==== FundingSources ====
| PaymentWindow || TimeSpan (d.hh:mm:ss) ||
array
* Optional
* Minimum value: one minute
* Maximum value: one week
* Default value: 30 minutes
|| Time window for the payment to be completed. The payer must execute the payment before this elapses, or else the payment will expire and can no longer be completed.


required
|-


The list of payment methods that the Barion Smart Gateway will display to the payer.
| GuestCheckOut || bool ||
* Required
* Value must be "true" or "false", integer evaluation is not supported
|| Flag indicating whether the payment can be completed without a registered Barion wallet. Guest checkout can only be done with bank cards, and the payer must supply a valid e-mail address - this is necessary for fraud control.


An array of one or more strings from the [[FundingSources]] enumeration.
|-


<blockquote>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.
| InitiateRecurrence || bool ||
</blockquote>
* Optional
|| This flag indicates that the shop would like to initialize a token payment. This means that the shop is authorized to charge the funding source of the payer in the future without redirecting her/him to the Barion Smart Gateway. It can be used for one-click and subscription payment scenarios.  
Click here to learn more about token payments: [[Token_payment]]


==== PaymentRequestId ====
|-
string


required
| RecurrenceId || string ||
* Required when executing token payments
* Maximum length: 100 characters
* Must be unique per shop and per user
* [https://docs.barion.com/Token_payment#Creating_the_token Generated by the shop]
|| A string used to identify a given token payment. Its purpose is determined by the value of the '''InitiateRecurrence''' property.
* If '''InitiateRecurrence''' is <code>true</code>, this property must contain a <u>new</u> desired identifier for a new token payment. This should be generated and stored by the shop before calling the API. Also, the shop must ensure that this is unique per user in its own system.
* If '''InitiateRecurrence''' is <code>false</code>, this property must contain an <u>existing</u> identifier for a token payment. This should be used to charge a payer's funding source (either bank card or Barion wallet) that was already used successfully for a payment in the shop.
* multiple shops can use the same RecurrenceId. Should you be interested, please contact [email protected]
|-


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


==== RedirectUrl ====
string


required
| FundingSources || [[FundingSources|string[]]] ||
* Required
|| An array of strings containing the allowed funding sources that can be used to complete the payment.
|-


The URL string where the payer will be redirected after completing the payment.
| PaymentRequestId || string ||
* Required
* Maximum length: 100 characters
|| The unique identifier for the payment generated by the shop. This is so the shop can track its own payment identifiers. It is also useful for bookkeeping purposes since this shows up in the monthly account statement and the transaction history export, making identification of payments easier for the shop.


Required but if not passed explicitly, defaults to the URL of the Barion shop whose <code>POSkey</code> 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.
| PayerHint || string ||
* Required for {{3dsfield}}
* Optional, but recommended.
* If provided, must be a valid email format
* Maximum length: 256 characters
|| The shop can supply an e-mail address as a hint on who should complete the payment. This can be used if the shop is certain about that the payer has an active Barion wallet or the shop would like to help the guest payer with filling in the email field for her/him. If provided, the Barion Smart Gateway automatically fills out the e-mail address field in the Barion wallet login form and the guest payer form, speeding up the payment process.


Defaults to the URL of the Barion shop whose <code>POSkey</code> was passed.
|-
| CardHolderNameHint || string ||
* Required for {{3dsfield}}
* Optional, but recommended
* Between 2 and 45 characters
|| The shop can provide a hint for the customer's name on the card to speed up the payment flow. If a value is provided, the cardholder name input will be pre-filled with it and the customer can use the pre-filled value instead of typing it out on its own, which speeds up the payment process.


<blockquote>The payment’s <code>paymentId</code> will be included in the request as a query string to specifically identify the payment.
|-


Read more about how callbacks work [[Callback mechanism|in the dedicated guide]].
| RecurrenceType || [[RecurrenceType]] ||
</blockquote>
* Required for {{3dsfield}}, when executing token payments
|| Describes the nature of the token payment.
|-


==== Transactions ====
|-
array


required
| TraceId || string ||
* Required for {{3dsfield}}, when executing token payments
* Maximum length: 100 characters
|| Identifies the nature of the token payment.
|-


The list of payment transactions included in the payment: one or more [[PaymentTransaction]] objects.
| RedirectUrl || string ||
* Required
* Maximum length: 2000 characters
|| The URL where the payer should be redirected after the payment is completed or canceled. The payment identifier is added to the query string part of this URL in the <code>paymentId</code> parameter. If not provided, the system will use the redirect URL assigned to the shop that started the payment.


==== Locale ====
|-
string


required
| CallbackUrl || string ||
* Required
* Maximum length: 2000 characters
|| The URL where the Barion system sends a request whenever there is a change in the state of the payment. The payment identifier is added to the query string part of this URL in the <code>paymentId</code> parameter. Click here to learn more about the callback mechanism: [[Callback_mechanism|Payment callback mechanism (IPN)]]


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


One of the following strings:
| Transactions || [[PaymentTransaction]][] ||
* Required
|| An array of payment transactions contained in the payment. A payment must contain at least one such transaction. See the [[PaymentTransaction]] page for the appropriate structure and syntax.
Defining multiple transactions allow the payment initiator to distribute the payment amount between multiple shops. See the following page to learn more: [[Facilitated payments]]


* “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 ====
| OrderNumber || string ||
string
* Optional
* Maximum length: 100 characters
|| The order number generated by the shop. This is to aid the shop in identifying a given payment in its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping.


required
|-


The currency that the transactions in the payment are made in.
| ShippingAddress || [[ShippingAddress]] ||
* Required for {{3dsfield}}
|| The shipping address associated with the payment, if applicable. Providing this is recommended because it helps the automatic anti-fraud analysis get more accurate results. See the [[ShippingAddress]] page for the appropriate structure and syntax.


One of the following [https://en.wikipedia.org/wiki/ISO_4217 ISO 4217 currency code] strings:
|-


* “CZK” (Czech crown)
| Locale || string ||
* “EUR” (Euro)
* Required
* “HUF” (Hungarian forint)
* Maximum length: 10 characters
* “USD” (US dollar)
* Accepted values:
** "cs-CZ" (Czech)
** "de-DE" (German)
** "en-US" (English)
** "es-ES" (Spanish)
** "fr-FR" (French)
** "hu-HU" (Hungarian)
** "sk-SK" (Slovak)
** "sl-SI" (Slovenian)
|| This indicates in which language the Barion Smart Gateway should display for the payer upon redirect.
|-


<blockquote>Only one currency is accepted per payment, for all transactions included in the payment.
| Currency || string ||
</blockquote>
* Required
==== OrderNumber ====
* Required length: 3 characters
string
Accepted values:
{{CurrencyList}}
|| The currency of the payment. Must be supplied in ISO 4217 format. This affects all transactions included in the payment; it is not possible to define multiple transactions in different currencies.
|-
| PayerPhoneNumber || string ||
* Required for {{3dsfield}}
* Max length: 30 characters
* Expected format: 36701231234 (where 36 is the country code)
|| The number must be sent in the expected format, without + sign or leading zero(s).
|-
| PayerWorkPhoneNumber || string ||
* Required for {{3dsfield}}
* Max length: 30 characters
* Expected format: 36701231234 (where 36 is the country code)
|| The work phone of the payer. The number must be sent in the expected format, without + sign or leading zero(s).
|-
| PayerHomeNumber || string ||
* Required for {{3dsfield}}
* Max length: 30 characters
* Expected format: 36701231234 (where 36 is the country code)
|| The home phone number of the payer. The number must be sent in the expected format, without + sign or leading zero(s).
|-
| BillingAddress || [[BillingAddress]] ||
* Required for {{3dsfield}}
|| The billing address associated with the payment, if applicable.
|-


optional
| PayerAccountInformation|| [[PayerAccountInformation]] ||
* Required for {{3dsfield}}
|| Information about the account of the payer in the merchant's system.
|-


A string of up to 100 characters that identifies of the order that the payment settles, generated by the Barion shop operator.
| PurchaseInformation|| [[PurchaseInformation]] ||
* Required for {{3dsfield}}
|| Information about current purchase.
|-


<blockquote>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.
| ChallengePreference || [[ChallengePreference]] ||
</blockquote>
* Required for {{3dsfield}}
|| The merchant's preference of the 3DS challenge. Here you can specify what 3DS authentication should be utilized.
|-


==== ReservationPeriod ====
string


required when calling the endpoint as part of [[Reservation payment|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.
== Output properties ==


Defaults to 0.00:30:00 (30 minutes).
{{api_output_table_header}}
|-
| PaymentId || Guid || The identifier of the newly initialized payment, generated by the Barion system.


Required only for payments where the <code>PaymentType</code> is “Reservation”.
|-


Reserved payments not finished within the configured <code>ReservationPeriod</code> the payer is refunded the reserved amount.
| PaymentRequestId || string || The payment identifier supplied by the API caller in the request.


For details about reserved payments, [[Reservation payment|see the dedicated guide]].
|-


==== DelayedCapturePeriod ====
| Status || [[PaymentStatus]]|| The status of the payment in the Barion system.
string


required when calling the endpoint as part of [[Delayed Capture|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.
| QRUrl || string || URL for a QR code representing the payment. This is useful in physical real life situations where the payer uses a mobile device.


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


Defaults to 7.00:00:00 (7 days).
| RecurrenceResult || RecurrenceResult || Indicates the result of an authorized payment scenario. The result depends on the values of the '''InitiateRecurrence''' and '''RecurrenceId''' properties supplied in the request.


Required only for payments where the <code>PaymentType</code> is “DelayedCapture”.
* If '''InitiateRecurrence''' was <code>true</code>, and a new authorized payment was successfully created, this will be <code>None</code> (because no actual token charge took place yet)


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.
* If '''InitiateRecurrence''' was <code>false</code>, but a previously authorized payment identifier was supplied in '''RecurrenceId''', the system will try to charge the funding source associated with the authorized payment. If this charge is successful, the result is <code>Successful</code>. If the system could not charge the funding source, the result is <code>Failed</code>. If the given identifier is invalid or does not exist, the result is <code>NotFound</code>. In case the payment can not be processed due to lack of 3DS v2 information <code>ThreeDSAuthenticationRequired</code> is returned. In this case, either offsite 3DS v2 authentication should be performed or the TraceId of the initial payment should be sent as well.


For details about delayed capture payments, [[Delayed Capture|see the dedicated guide]].
|-


==== InitiateRecurrence ====
| Transactions || [[ProcessedTransaction]][] || An array containing all transactions associated with the payment. If the Barion system deducts fees from the shop after payments, this also contains these additional fee transactions beside the payment transactions that were sent in the request.
Boolean


required when the payer’s payment instrument is tokenized for later reuse: [[One-click payments: saving your customer's card|one-click payment]], [[Subscriptions: set up recurring billing|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.
| GatewayUrl || string || The URL of the Barion Smart Gateway (including the payment identifier), where the API caller should redirect the payer.


Only required for token payment scenarios.
|-


Read more in the guides about [[One-click payments: saving your customer's card|one-click payments]] and [[Subscriptions: set up recurring billing|subscriptions]].
| CallbackUrl || string || The URL (including the payment identifier) where the Barion system will send a request to whenever there is a change in the state of the payment. If an explicit URL was not supplied, this will be the callback URL associated with the shop that started the payment.


==== RecurrenceId ====
|-
string


required when the payer’s payment instrument is tokenized for later reuse: [[One-click payments: saving your customer's card|one-click payment]], [[Subscriptions: set up recurring billing|subscription]], or MIT
| RedirectUrl || string || The URL (including the payment identifier) where the payer gets redirected to after the payment is completed or cancelled. If an explicit URL was not supplied, this will be the redirect URL associated with the shop that started the payment.


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 <code>InitiateRecurrence</code>:
|-


* if <code>InitiateRecurrence: true</code>, <code>RecurrenceId</code> is the new unique identifier that the Barion shop operator assigns to the token payment
| ThreeDSAuthClientData|| string || Encrypted client authentication data required for 3D Secure processing. This value can be used when the webshop first tried to complete the payment without user interaction, but the charge failed due to a 3D Secure challenge being mandatory.
* if <code>InitiateRecurrence: false</code>, <code>RecurrenceId</code> 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: saving your customer's card|one-click payments]] and [[Subscriptions: set up recurring billing|subscriptions]].
 
==== RecurrenceType ====
string
 
required when the payer’s payment instrument is tokenized for later reuse: [[One-click payments: saving your customer's card|one-click payment]], [[Subscriptions: set up recurring billing|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 [[3DSecure|the dedicated guide]].
 
==== TraceId ====
string
 
required when the payer’s payment instrument is tokenized for later reuse: [[One-click payments: saving your customer's card|one-click payment]], [[Subscriptions: set up recurring billing|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 [[3DSecure|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 ===
 
<syntaxhighlight lang="json">{
  "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        }
      ]
    }
  ]
}</syntaxhighlight>
 
== Response ==
 
The /{API_version}/Payment/Start endpoint returns a JSON object with the following properties.<span id="paymentid"></span>
=== PaymentId ===
 
The Barion server generated guid for the payment that the request initialized.<span id="paymentrequestid-1"></span>
=== PaymentRequestId ===
 
The Barion shop’s unique string identifier for the payment that was passed as <code>PaymentRequestId</code> in the request.<span id="status"></span>
=== Status ===
 
The payment’s current status within Barion: one of the string values in the [[PaymentStatus]] enumeration.<span id="qrurl"></span>
=== QRUrl ===
 
A URL to a QR code that represents the payment.
 
<span id="recurrenceresult"></span>
=== RecurrenceResult ===
 
String status of the tokenization or the subsequent charge to a tokenized payment instrument: “None”, “Failed”, “Successful”, “NotFound”, or “ThreeDSAuthenticationRequired”.
 
For details, see [[#how-to-interpret-recurrenceresult|the dedicated section]].
 
<blockquote>Always returned, but only applies to payments that are part of a tokenized payment scenario
</blockquote><span id="transactions-1"></span>
=== Transactions ===
 
All the transactions associated with the payment: an array of [[ProcessedTransaction]] object
 
Includes all applicable Barion-deducted fees.<span id="gatewayurl"></span>
=== GatewayUrl ===
 
The URL of the Barion Smart Gateway where the payer needs to be redirected for payment.
 
Includes the <code>PaymentId</code> as a query string.<span id="callbackurl-1"></span>
=== CallbackUrl ===
 
The URL where the Barion server sends a request each time there is a change in the payment’s status.
 
Includes the <code>PaymentId</code> as a query string.


If no <code>CallbackURL</code> was passed in the request, this property defaults to the URL of the Barion shop whose <code>POSkey</code> was passed.<span id="redirecturl-1"></span>
| TraceId || string || A unique value generated by the card issuer to track a chain of [[Token_payment_3D_Secure|recurring or token payments that require 3D Secure authentication]]. This shall be used in such scenarios, otherwise it can be ignored.
=== RedirectUrl ===


The URL where the payer is redirected once they complete the payment. Includes the <code>PaymentId</code> as a query string.
If no <code>RedirectURL</code> was passed in the request, this property defaults to the URL of the Barion shop whose <code>POSkey</code> was passed.
<span id="threedsauthclientdata"></span>
=== ThreeDSAuthClientData ===
Encrypted client authentication data, as a string, required for 3-D Secure processing.
<blockquote>[[One-click payments: saving your customer's card#Integrate Barion’s off-site authentication|Pass this data to the off-site authentication library]] if a token payment was rejected because of missing authentication.
</blockquote><span id="traceid-1"></span>
=== 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.<span id="how-to-interpret-recurrenceresult"></span>
==== How to interpret <code>RecurrenceResult</code> ====
{|class="wikitable"
!width="50%"| Value
!width="50%"| Description
|-
| None
| Either the payment isn’t part of a token payment scenario, or, if <code>InitiateRecurrence: true</code> (and no <code>RecurrenceId</code>) was passed in the request, the tokenization was successful, but no attempt has been made to use the token.
|-
| Successful
| <code>InitiateRecurrence: false</code> and a <code>RecurrenceId</code> was passed in the request, and the previously tokenized payment instrument has been successfully used to complete the payment.
|-
| Failed
| <code>InitiateRecurrence: false</code> and a <code>RecurrenceId</code> was passed in the request, but the previously tokenized payment instrument couldn’t be charge to complete the payment.
|-
| NotFound
| The <code>RecurrenceId</code> passed in the request is invalid, or the previous tokenization had been unsuccessful.
|-
| ThreeDSAuthenticationRequired
| <code>InitiateRecurrence: false</code> and a <code>RecurrenceId</code> 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. </br>Perform [[01-payments/03-payment-scenarios/02-save-card#integrate-barions-offsite-authentication|off-site 3-DS authentication]], or [[Subscriptions: set up recurring billing#Troubleshoot subsequent payments|pass the <code>TraceId</code> associated with the payment instrument in the request]].
|}
|}
<span id="example-response"></span>
==== Example response ====
<syntaxhighlight lang="json">{
  "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": []
}</syntaxhighlight>
== 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 [[InitiatePurchase|the <code>InitiatePurchase</code> Barion Pixel event]] when this endpoint request returns.

Latest revision as of 12:23, 28 August 2024

Barion API: Initialize a new payment

POST /v2/Payment/Start

The /payment/start API endpoint is used to create a new payment in the Barion system.

Prerequisites before use:


v2 This API endpoint is available in API v2 only.

Authentication

Barion Shop Authentication

Use cases

This API endpoint is designed to be used in the following scenarios:

Input properties

3DS
 Properties marked with this must be provided to comply with 3D Secure authentication. The more attributes you provide the more chance you have to avoid the challenge flow.

Important: if the merchant does not provide 3DS-related properties, it doesn't mean that the payment will fail. It means that the payer will have a higher chance of getting a challenge during payment.

Property name Property type Limitations and constraints Description
POSKey Guid
  • Required
 The secret API key of the shop, generated by Barion. This lets the shop to authenticate through the Barion API, but does not provide access to the account owning the shop itself.
PaymentType string
  • Required
  • Accepted values:
    • "Immediate"
    • "Reservation"
    • "DelayedCapture"
 The type of payment, which can be either immediate or a money reservation. Reservation means that the shop has a time window to finish the payment (even though the money transaction still takes place immediately). Reservation amounts can be modified during this time window unless the new amount is lower than the original.

Click here to learn more about reservation payments: Reservation payments, and delayed capture: Delayed capture.

ReservationPeriod TimeSpan (d.hh:mm:ss)
  • Required only if PaymentType is "Reservation"
  • Minimum value: one minute
  • Maximum value: one year
  • Default value: 30 minutes
 Only makes sense at reservation payments. This is the time window that allows the shop to finish (finalize) the payment. If this does not happen within the time window, the system refunds the payment amount to the payer.
DelayedCapturePeriod TimeSpan (d.hh:mm:ss)
  • Required only if PaymentType is "DelayedCapture"
  • Minimum value: one minute
  • Maximum value: 7 days (21 days in case of a Hungarian shop)
  • Default value: seven days
 This is the time window that allows the shop to complete (finalize) the payment. If this does not happen within the time window, the system releases the payment amount.
PaymentWindow TimeSpan (d.hh:mm:ss)
  • Optional
  • Minimum value: one minute
  • Maximum value: one week
  • Default value: 30 minutes
 Time window for the payment to be completed. The payer must execute the payment before this elapses, or else the payment will expire and can no longer be completed.
GuestCheckOut bool
  • Required
  • Value must be "true" or "false", integer evaluation is not supported
 Flag indicating whether the payment can be completed without a registered Barion wallet. Guest checkout can only be done with bank cards, and the payer must supply a valid e-mail address - this is necessary for fraud control.
InitiateRecurrence bool
  • Optional
 This flag indicates that the shop would like to initialize a token payment. This means that the shop is authorized to charge the funding source of the payer in the future without redirecting her/him to the Barion Smart Gateway. It can be used for one-click and subscription payment scenarios.

Click here to learn more about token payments: Token_payment

RecurrenceId string
  • Required when executing token payments
  • Maximum length: 100 characters
  • Must be unique per shop and per user
  •  Generated by the shop
 A string used to identify a given token payment. Its purpose is determined by the value of the InitiateRecurrence property.
  • If InitiateRecurrence is true, this property must contain a new desired identifier for a new token payment. This should be generated and stored by the shop before calling the API. Also, the shop must ensure that this is unique per user in its own system.
  • If InitiateRecurrence is false, this property must contain an existing identifier for a token payment. This should be used to charge a payer's funding source (either bank card or Barion wallet) that was already used successfully for a payment in the shop.
  • multiple shops can use the same RecurrenceId. Should you be interested, please contact [email protected]
FundingSources string[]
  • Required
 An array of strings containing the allowed funding sources that can be used to complete the payment.
PaymentRequestId string
  • Required
  • Maximum length: 100 characters
 The unique identifier for the payment generated by the shop. This is so the shop can track its own payment identifiers. It is also useful for bookkeeping purposes since this shows up in the monthly account statement and the transaction history export, making identification of payments easier for the shop.
PayerHint string
  • Required for
    3DS
  • Optional, but recommended.
  • If provided, must be a valid email format
  • Maximum length: 256 characters
 The shop can supply an e-mail address as a hint on who should complete the payment. This can be used if the shop is certain about that the payer has an active Barion wallet or the shop would like to help the guest payer with filling in the email field for her/him. If provided, the Barion Smart Gateway automatically fills out the e-mail address field in the Barion wallet login form and the guest payer form, speeding up the payment process.
CardHolderNameHint string
  • Required for
    3DS
  • Optional, but recommended
  • Between 2 and 45 characters
 The shop can provide a hint for the customer's name on the card to speed up the payment flow. If a value is provided, the cardholder name input will be pre-filled with it and the customer can use the pre-filled value instead of typing it out on its own, which speeds up the payment process.
RecurrenceType RecurrenceType
  • Required for
    3DS
    , when executing token payments
 Describes the nature of the token payment.
TraceId string
  • Required for
    3DS
    , when executing token payments
  • Maximum length: 100 characters
 Identifies the nature of the token payment.
RedirectUrl string
  • Required
  • Maximum length: 2000 characters
 The URL where the payer should be redirected after the payment is completed or canceled. The payment identifier is added to the query string part of this URL in the paymentId parameter. If not provided, the system will use the redirect URL assigned to the shop that started the payment.
CallbackUrl string
  • Required
  • Maximum length: 2000 characters
 The URL where the Barion system sends a request whenever there is a change in the state of the payment. The payment identifier is added to the query string part of this URL in the paymentId parameter. Click here to learn more about the callback mechanism: Payment callback mechanism (IPN)
Transactions PaymentTransaction[]
  • Required
 An array of payment transactions contained in the payment. A payment must contain at least one such transaction. See the PaymentTransaction page for the appropriate structure and syntax.

Defining multiple transactions allow the payment initiator to distribute the payment amount between multiple shops. See the following page to learn more: Facilitated payments

OrderNumber string
  • Optional
  • Maximum length: 100 characters
 The order number generated by the shop. This is to aid the shop in identifying a given payment in its own system. This also shows up in generated monthly account statements and transaction history exports, so it also helps with bookkeeping.
ShippingAddress ShippingAddress
  • Required for
    3DS
 The shipping address associated with the payment, if applicable. Providing this is recommended because it helps the automatic anti-fraud analysis get more accurate results. See the ShippingAddress page for the appropriate structure and syntax.
Locale string
  • Required
  • Maximum length: 10 characters
  • Accepted values:
    • "cs-CZ" (Czech)
    • "de-DE" (German)
    • "en-US" (English)
    • "es-ES" (Spanish)
    • "fr-FR" (French)
    • "hu-HU" (Hungarian)
    • "sk-SK" (Slovak)
    • "sl-SI" (Slovenian)
 This indicates in which language the Barion Smart Gateway should display for the payer upon redirect.
Currency string
  • Required
  • Required length: 3 characters

Accepted values:

  • "CZK" (Czech crown)
  • "EUR" (Euro)
  • "HUF" (Hungarian forint)
  • "USD" (U.S. dollar)
 The currency of the payment. Must be supplied in ISO 4217 format. This affects all transactions included in the payment; it is not possible to define multiple transactions in different currencies.
PayerPhoneNumber string
  • Required for
    3DS
  • Max length: 30 characters
  • Expected format: 36701231234 (where 36 is the country code)
 The number must be sent in the expected format, without + sign or leading zero(s).
PayerWorkPhoneNumber string
  • Required for
    3DS
  • Max length: 30 characters
  • Expected format: 36701231234 (where 36 is the country code)
 The work phone of the payer. The number must be sent in the expected format, without + sign or leading zero(s).
PayerHomeNumber string
  • Required for
    3DS
  • Max length: 30 characters
  • Expected format: 36701231234 (where 36 is the country code)
 The home phone number of the payer. The number must be sent in the expected format, without + sign or leading zero(s).
BillingAddress BillingAddress
  • Required for
    3DS
 The billing address associated with the payment, if applicable.
PayerAccountInformation PayerAccountInformation
  • Required for
    3DS
 Information about the account of the payer in the merchant's system.
PurchaseInformation PurchaseInformation
  • Required for
    3DS
 Information about current purchase.
ChallengePreference ChallengePreference
  • Required for
    3DS
 The merchant's preference of the 3DS challenge. Here you can specify what 3DS authentication should be utilized.

Output properties

Property name Property type Description
PaymentId Guid The identifier of the newly initialized payment, generated by the Barion system.
PaymentRequestId string The payment identifier supplied by the API caller in the request.
Status PaymentStatus The status of the payment in the Barion system.
QRUrl string URL for a QR code representing the payment. This is useful in physical real life situations where the payer uses a mobile device.
RecurrenceResult RecurrenceResult Indicates the result of an authorized payment scenario. The result depends on the values of the InitiateRecurrence and RecurrenceId properties supplied in the request.
  • If InitiateRecurrence was true, and a new authorized payment was successfully created, this will be None (because no actual token charge took place yet)
  • If InitiateRecurrence was false, but a previously authorized payment identifier was supplied in RecurrenceId, the system will try to charge the funding source associated with the authorized payment. If this charge is successful, the result is Successful. If the system could not charge the funding source, the result is Failed. If the given identifier is invalid or does not exist, the result is NotFound. In case the payment can not be processed due to lack of 3DS v2 information ThreeDSAuthenticationRequired is returned. In this case, either offsite 3DS v2 authentication should be performed or the TraceId of the initial payment should be sent as well.
Transactions ProcessedTransaction[] An array containing all transactions associated with the payment. If the Barion system deducts fees from the shop after payments, this also contains these additional fee transactions beside the payment transactions that were sent in the request.
GatewayUrl string The URL of the Barion Smart Gateway (including the payment identifier), where the API caller should redirect the payer.
CallbackUrl string The URL (including the payment identifier) where the Barion system will send a request to whenever there is a change in the state of the payment. If an explicit URL was not supplied, this will be the callback URL associated with the shop that started the payment.
RedirectUrl string The URL (including the payment identifier) where the payer gets redirected to after the payment is completed or cancelled. If an explicit URL was not supplied, this will be the redirect URL associated with the shop that started the payment.
ThreeDSAuthClientData string Encrypted client authentication data required for 3D Secure processing. This value can be used when the webshop first tried to complete the payment without user interaction, but the charge failed due to a 3D Secure challenge being mandatory.
TraceId string A unique value generated by the card issuer to track a chain of recurring or token payments that require 3D Secure authentication. This shall be used in such scenarios, otherwise it can be ignored.
Retrieved from "https://docs.barion.com/index.php?title=Payment-Start-v2&oldid=4606"