Difference between revisions of "Token payment 3D Secure"

From Barion Documentation
Jump to navigation Jump to search
(Using the token)
(Token payment scenarios)
 
(146 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{PageTitle|title=Token Payment with 3D Secure}}
 
__NOTOC__
 
__NOTOC__
{{PageTitle|title=Token Payment 3D Secure}}
+
{{IncompletePage}}
  
This payment scenario allows the integrator shop to register a customer (and a funding source) in the Barion system and then later on charge the customer without redirecting her to the Barion Payment Gateway UI. This means that the customer authorizes the shop to charge her card or Barion balance without typing in the card information or Barion login again.
+
This payment scenario allows the integrator shop to register a token for a customer (and a funding source) in the Barion system and then, later on, using this token, charge the customer without redirecting her to the Barion Smart Gateway UI. The user may be present at the site of the merchant or she can be off-session as well, so the merchant can charge her e.g. for subscriptions. This means that the customer authorizes the shop to charge her card or Barion balance without typing in the card information or Barion login again.
 +
{{NotificationBox|title=Premium feature|text=This scenario is not allowed automatically for every approved shop and should be requested from Barion!|color=#1993c7}}
 +
 
 +
== Token payment scenarios ==
 +
Token payment can be used in three use cases:
 +
* '''Customer Initiated Payments''': when the user is present on the website of the merchant and she decides to pay :
 +
** '''OneClick payment''': the user is charged upon her request initiated on the website of the merchant. Subsequent payments are subject to PSD2 SCA and as the user is present, she has to go through the authentication process.
 +
* '''Merchant Initiated Payments''': when the merchant initiates the payment without the user being present. It has two subtypes:
 +
** '''Recurring payment''': the user is charged with the same amount on a regular basis, typically in case of subscriptions. Subsequent payments are exempted from PSD2 SCA, but liability still shifts to the card issuer.
 +
** '''MIT (merchant initiated transaction)''': the user is charged on an irregular basis and/or with a different amount. Subsequent payments of this type are excluded from PSD2 SCA, the liability is on the merchant.
 +
 
 +
=== Customer participation ===
 +
 
 +
Since the token scenario is suitable for both customer and merchant initiated payments here is a comparison about who starts the payment. This includes the regular, non-tokenized payment scenario as well:
 +
 
 +
{|class=wikitable
 +
|-
 +
! rowspan="2" | Scenario
 +
! colspan="2" | Initial payment
 +
! colspan="2" | Subsequent payments
 +
|-
 +
! Customer present
 +
! Customer at Barion Smart GW
 +
! Customer present
 +
! Customer at Barion Smart GW
 +
|-
 +
| Non token (regular) payment || YES || YES || YES || YES
 +
|-
 +
| OneClick payment || YES || YES/NO<sup>1</sup> || YES || style="background:#FFE2C4" | NO
 +
|-
 +
| Recurring payment || YES || YES/NO<sup>1</sup> || style="background:#FFE2C4" | NO || style="background:#FFE2C4" | NO
 +
|-
 +
| MIT || YES || YES/NO<sup>1</sup> || style="background:#FFE2C4" | NO || style="background:#FFE2C4" | NO
 +
|-
 +
|}
 +
 
 +
<div style="border: 1px solid #aaa; background-color:#eee; font-size: 0.8em; padding:5px 10px; display:inline-block;">
 +
<sup>1</sup> Token payment scenarios can be initiated with already registered <code>RecurrenceId</code> as well, in this case the customer may remain on the merchant's site.
 +
</div>
 +
 
 +
=== Requirements for the scenarios ===
 +
 
 +
These token payment scenarios have different requirements, this table below summarizes the key differences.
 +
 
 +
{|class="wikitable"
 +
|-
 +
! Scenario
 +
! Payment amount
 +
! Payment frequency
 +
! Liability in case of fraud
 +
|-
 +
| OneClick payment || Various || Various || Card issuer
 +
|-
 +
| Recurring payment || Subsequent amounts must be equal or less than the initial amount  || Initial payment defines a minimum amount of days to wait between charges || Card issuer
 +
|-
 +
| Merchant initiated payment || Various  || Various || Merchant
 +
|-
 +
|}
 +
 
 +
=== 3DS authentication of the payer ===
 +
 
 +
The new more secure 3DS v2 authentication must be performed for every online card payment. These token payment scenarios also have to use this new secure way of authentication.
 +
The initial payment of a token scenario must be authenticated every time although the subsequent payments may be exempted in certain cases.
 +
 
 +
Here is a table to compare the 3DS authentication requirements:
 +
 
 +
{|class="wikitable"
 +
|-
 +
! Scenario
 +
! Initial payment
 +
! Subsequent payments
 +
|-
 +
| One-click payment || ✔️ || ✔️
 +
|-
 +
| Recurring payment || ✔️ ||
 +
|-
 +
| Merchant initiated payment || ✔️ ||
 +
|-
 +
|}
 +
 
 +
=== Example scenarios ===
  
Token payment can be used in two use cases:  
+
'''Phone bill'''
* when the user is present on the website of the merchant and she decides to pay (customer iniitated payment/transaction - e.g. one-click payment, recurring payment)
+
 
* when the merchant initiates the payment without the user being present (merchant initiated payment/transaction)
+
Payer has a usage-based phone subscription that wants to pay without being present for every charge. She authorizes the phone company to charge her card every month.
 +
* Scenario: Merchant Initiated Transaction
 +
* Explanation: Despite the frequency of the charges is monthly, the amount of the subsequent payments may exceed the initial payment.
 +
 
 +
'''TV subscription'''
 +
 
 +
Payer subscribes to online streaming of a television channel. She authorizes the phone company to charge her card every month. The subscription fee is the same for every month.
 +
* Scenario: Recurring payment
 +
* Explanation: The amount of the subsequent payments will not exceed the initial payment and the charge is regularly monthly-based.
 +
 
 +
'''Bookclub with "free first month" bonus'''
 +
 
 +
Payer subscribes to a book renting service. She authorizes the book club to charge her card every month for a selection of books. The subscription fee is the same for every month however, the first month is free. To ensure the subscription the service requires her to register her card details.
 +
* Scenario: Merchant Initiated Transaction
 +
* Explanation: Despite the frequency of the charges is monthly, and the fee will stay the same, the initial payment is zero. So the amount of the next payment will exceed the initial payment.
 +
 
 +
'''Online food delivery service'''
 +
 
 +
The food delivery company wants to provide a quick and easy experience for its customer. They decide that the order will be quicker if the customers don't leave the website to pay for the goods.
 +
* Scenario: OneClick payment
 +
* Explanation: The customer will always be there so the other two scenarios are not available.
 +
 
 +
=== How to decide ===
 +
 
 +
To help you decide on a suitable scenario, please use the decision graph below:
 +
 
 +
[[File:3ds-recurrencetype-decision.png|520px]]
  
{{NotificationBox|title=Premium feature|text=This scenario is not allowed automatically for every approved shop and should be requested from Barion!|color=#1993c7}}
 
 
== Prerequisites ==
 
== Prerequisites ==
 
To be able to integrate your webshop with the Barion Payment Gateway:  
 
To be able to integrate your webshop with the Barion Payment Gateway:  
 
* You must [[Creating_an_account|register a Barion wallet]] at the Barion website or in the Sandbox environment. Learn more about the Sandbox environment [[Sandbox|here]].
 
* You must [[Creating_an_account|register a Barion wallet]] at the Barion website or in the Sandbox environment. Learn more about the Sandbox environment [[Sandbox|here]].
 
* For this wallet you have to [[Creating_a_shop|create a shop]] which should be approved by Barion.
 
* For this wallet you have to [[Creating_a_shop|create a shop]] which should be approved by Barion.
* For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be an USD account created in your wallet.
+
* For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be a USD account created in your wallet.
* To make sure every corner case scenario works for your webshop it is best to topup that account with a small amount (aprrox. 5-10EUR or your choice of currency around the same value).
+
* To make sure every corner case scenario works for your webshop it is best to top up that account with a small amount (approx. 5-10EUR or your choice of currency around the same value).
* For the technical communication guide please read the this: [[Calling_the_API|Calling the API]]
+
* For the technical communication guide please read this: [[Calling_the_API|Calling the API]]
  
 
== The payment process ==  
 
== The payment process ==  
Line 22: Line 128:
 
# [[#Using the token|Using the registered token]] to charge the customer
 
# [[#Using the token|Using the registered token]] to charge the customer
  
[[File:Recurring.png]]
+
== Creating the token ==
 +
To be able to use a token payment scenario first we have to register the token with Barion. The token registration is basically a [[Responsive_web_payment|normal payment]] with three extra properties in the [[Payment-Start-v2|Payment/Start]] request. This means that the mercahnt has to make sure that the customer is well aware of the fact that they are giving consent to a tokenized payment. The Barion Smart Gateway UI does not indicate in any way that the payment is a token payment.
  
== Creating the token ==
+
By default the token is registered to the shop and not to the Barion account. So if the Barion account has multiple shops, the registered tokens can not be shared among them even if the customer is the same. If you want to use tokens in multiple shops, please contact Barion in the Customer center.
To be able to use a token payment scenario first we have to register the token with Barion. The token registration is basically a [[Responsive_web_payment|normal payment]] with two new properties in the [[Payment-Start-v2|Payment/Start]] request. This means that we have to make sure that the customer is well aware of the fact that they are giving consent to a tokenized payment. The Barion payment does not indicate in any way that the payment is a token payment.
 
  
The token is registered to the shop and not to the wallet. So if the Barion wallet has multiple shops registered the token can not be shared among them even if the customer is the same.
+
=== InitiateRecurrence, RecurrenceId and RecurrenceType===
  
One of the properties is the <code>InitiateRecurrence</code> property. This is a bool property, if you set it to '''true''' then the payment gateway will consider the request as a token registration. This happens even if the customer is already has a registered token, so you are able to re-register a customer.  
+
Let's start with the <code>InitiateRecurrence</code> property. This is a bool property, if you set it to '''true''' then the payment gateway will consider the request as a token registration. This happens even if the customer is already has a registered token, so you are able to re-register a customer.  
  
 
The other required property for a token registration is the token itself. This is generated by the shop and has to be unique for every registration. The token should be specified in the <code>RecurrenceId</code> property of the [[Payment-Start-v2|Payment/Start]] request. This token should be stored in the webshop database. Make sure that multiple tokens can belong to a single customer because the token is only unique for a specific shop, customer, funding source combination.
 
The other required property for a token registration is the token itself. This is generated by the shop and has to be unique for every registration. The token should be specified in the <code>RecurrenceId</code> property of the [[Payment-Start-v2|Payment/Start]] request. This token should be stored in the webshop database. Make sure that multiple tokens can belong to a single customer because the token is only unique for a specific shop, customer, funding source combination.
  
An already used <code>RecurrenceId</code> can be used for re-registration, in this case the new funding source will be registered for the token.
+
The appropriate [[RecurrenceType|Recurrence Type]] property has to be specified. In case of Recurring Payment <code>PurchaseInformation.RecurringExpiry</code> and <code>PurchaseInformation.RecurringFrequency</code> must also be set.
 +
 +
An already used <code>RecurrenceId</code> can be used for re-registration, in this case, the new funding source will be registered for the token.
 +
<br/>
 +
 
 +
[[File:Token_payment_1.png]]
  
 
=== Example JSON request ===
 
=== Example JSON request ===
<source lang=json>
+
<source lang=json line highlight="5-6">
 
{
 
{
 
     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
 
     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
Line 68: Line 179:
  
 
=== Customer selects funding source ===
 
=== Customer selects funding source ===
After the proper payment preparation the customer is redirected to the secure Barion gateway to choose between funding sources. The funding source the customer selects will be registered to the token. The funding source can either be an e-money wallet or a bank card. This means that even though the customer may own multiple cards only the one that was registered to the token can be used for future token payments. To change the funding source attached to the token a new registration should be requested.
+
After the proper payment preparation, the customer is redirected to the secure Barion Smart Gateway to choose a funding source. The funding source the customer selects will be registered to the token. The funding source can either be a Barion e-money balance or a bank card. This means that even though the customer may own multiple cards only the one that was registered to the token can be used for future token payments. To change the funding source attached to the token a new registration should be requested.
  
 
=== Processing the response ===
 
=== Processing the response ===
Line 75: Line 186:
 
* '''Failed''': the token registration was not successful, the token can not be used  
 
* '''Failed''': the token registration was not successful, the token can not be used  
 
* '''None''': this could only happen if no token payment was requested
 
* '''None''': this could only happen if no token payment was requested
 +
 +
=== TraceId ===
 +
 +
In case of Recurring payment or Merchant initiated payment the [[Payment-GetPaymentState-v2|GetPaymentState]] response returns an additional field called TraceId. The value of this property is generated by the card issuer. You have to save it and submit is in all subsequent Recurring or Merchant initiated payments of the same type, or otherwise the payments can be declined by the issuer. The TraceID represents the first, customer-present payment and helps the issuer to connect subsequent payments to this initial payment.
  
 
=== Displaying the funding source in a GUI ===
 
=== Displaying the funding source in a GUI ===
Line 87: Line 202:
 
|-
 
|-
 
|}
 
|}
 +
 +
  
 
== Using the token ==
 
== Using the token ==
You can use the token for one-click payment in a shop (like on Amazon or in Uber) or to automatically charge the user (e.g. in case of a subscription). In this case the 3DS authentication should be performed on the user's site, when required. <br>
 
To use an already registered token for a payment, you have to use the same [[Payment-Start-v2|/Payment/Start]] API endpoint but the <code>InitiateRecurrence</code> should be set to <code>false</code> and the <code>RecurrenceType</code> to <code>OneClickPayment</code>. This tells the Barion API to use the token for payment instead of only registering it. The token should be specified in the <code>RecurrenceId</code> property.
 
  
 +
Depending on the type of the subsequent payment, 3DSecure authentication might be required for subsequent payments.
 
3DS authentication is not required in the following cases:
 
3DS authentication is not required in the following cases:
* the token was requested before 3DS came into effect
+
* the token was requested before 3DS came into effect,
* the original payment was not initialized by bank card
+
* the original payment was not initialized by bank card,
 +
* the subsequent payment is a merchant initiated payment.
 +
 
 +
=== Prerequisites ===
 +
To be able to use a token, the initial payment must be in a successful state.
 +
 
 +
[[File:Token_payment_2.png]]
  
???There is no amount limitation for the token payment and the payment scenarios could be changed as well for the token charge. This means that the token payment can be reservation even if the original payment was an immediate scenario.???
+
=== OneClick payment ===
<br/>
+
==== Step 1 : Initialize oneClick ====
You have to include the following javascript files, which are available on our Github:
+
You have to include the following css and javascript files in the code of your site. These files include all the necessary javascript code and styling to handle the 3DS authentication and display the challenge if necessary.
 
<source lang=html>
 
<source lang=html>
<link href="/Content/micromodal/micromodal.css" rel="stylesheet">
+
<link href="https://secure.barion.com/static/barion.offsitegw.min.css" rel="stylesheet">
&gt;script src="/bundles/modernizr?v=wBEWDufH_8Md-Pbioxomt90vm6tJN2Pyy9u9zHtWsPo1"
+
<script src="https://secure.barion.com/static/barion.offsitegw.min.js"></script>
 +
</source >
 +
 
 +
Then you have to initialize the Barion javascript client:
 +
<source lang=javascript>
 +
const configuration = {
 +
    onAuthenticationSucceeded: function () {
 +
        // handle successful authentication by calling the Barion API via merchant's backend
 +
        // Call the v2/payment/complete endpoint
 +
    },
 +
    onAuthenticationFailed: function () {
 +
        // Handle unsuccessful authentication result, no charge was made.
 +
        // The payment might be still valid only the authentication failed
 +
    }
 +
}
 +
 
 +
const gw= new Barion.OffsiteGw(configuration);
 
</source>
 
</source>
  
Example request:
+
==== Step 2 : Make a payment  ====
<source lang=json>
+
To use an already registered token for a payment, you have to call the same [[Payment-Start-v2|/Payment/Start]] API endpoint but the <code>InitiateRecurrence</code> should be set to <code>false</code> and the appropriate [[RecurrenceType|Recurrence Type]] should be sent. This tells the Barion API to use the token for payment instead of only registering it. The token should be specified in the <code>RecurrenceId</code> property along with the <code>TraceId</code>.
 +
<br/>
 +
 
 +
===== Example Payment/Start json request =====
 +
<source lang=json line highlight="5-8">
 
{
 
{
 
     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
 
     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
Line 113: Line 255:
 
     "RecurrenceType" : "OneClickPayment",
 
     "RecurrenceType" : "OneClickPayment",
 
     "RecurrenceId" : "SHOP-XMLP-TOKEN-ABC-123",
 
     "RecurrenceId" : "SHOP-XMLP-TOKEN-ABC-123",
 +
    "TraceId" : "SHOP-XMLP-TRACEID-123",
 
     "FundingSources": ["All"],
 
     "FundingSources": ["All"],
 
     "Currency": "EUR",
 
     "Currency": "EUR",
Line 137: Line 280:
 
</source>
 
</source>
  
=== Processing the response ===
+
===== Processing the Payment/Start response =====
To this request the barion API sends back the required data for the 3DS authentication for the specified paymentId.
+
To this request, the Barion API sends back the required data for the 3DS authentication for the specified paymentId.
  
 
{|class=wikitable
 
{|class=wikitable
Line 153: Line 296:
 
|}
 
|}
  
Example response:
+
===== Example Payment/Start response =====
<source lang=json>
+
<source lang=json line style="word-break: break-all;">
 
{
 
{
 
     "PaymentId" : "dce46843-6266-4c1f-b82a-387e0fee9073",
 
     "PaymentId" : "dce46843-6266-4c1f-b82a-387e0fee9073",
     "ThreeDSAuthClientData" : ""
+
     "ThreeDSAuthClientData" : "ewoJIkNhcmRQdWJsaWNJZCI6ICIxYTE5M2E1NDQzNDI0YjJiOGJiMjMyOGRhNWY4NmYzYiIsCgkiUGF5bWVudElkIjogImRjZTQ2ODQzNjI2NjRjMWZiODJhMzg3ZTBmZWU5MDczIiwKCSJPbmVDbGlja0NvbnRlbnRVcmwiOiAiaHR0cDovL3NlY3VyZS5iYXJpb24uY29tL3RocmVlZHMvb25lY2xpY2twYXltZW50IiwKCSJBQ1NTdGFydFByb3RvY29sVmVyc2lvbiI6ICIyLjEuMCIsCgkiQUNTRW5kUHJvdG9jb2xWZXJzaW9uIjogIjIuMS4wIiwKCSJEU1N0YXJ0UHJvdG9jb2xWZXJzaW9uIjogIjIuMS4wIiwKCSJEU0VuZFByb3RvY29sVmVyc2lvbiI6ICIyLjIuMCIsCgkiVGhyZWVEU1NlcnZlclRyYW5zSUQiOiBudWxsLAoJIlRocmVlRFNNZXRob2RVUkwiOiBudWxsLAoJIlRocmVlRFNNZXRob2REYXRhRm9ybSI6ICJleUowYUhKbFpVUlRUV1YwYUc5a1RtOTBhV1pwWTJGMGFXOXVWVkpNSWpvaWFIUjBjSE02THk4elpITXVZbUZ5YVc5dUxtTnZiUzh6WkhNdmRqSXZNMlJ6TFcxbGRHaHZaQzF1YjNScFptbGpZWFJwYjI0aUxDSjBhSEpsWlVSVFUyVnlkbVZ5VkhKaGJuTkpSQ0k2SWpFNE5URTJPR0kxTFRKalkyUXROR0kxWlMxaVlqWm1MVFUzTW1VM00yVTNNemt3TnlKOSIsCgkiRXJyb3JEZXRhaWxzIjogbnVsbCwKCSJWZXJzaW9uIjogIjIuMS4wIgp9Cg=="
 
}
 
}
 
</source>
 
</source>
  
This data then should be passed onto the <code>BarionThreeDSecure.startProcess</code> method, which will do all the magic to authenticate and display the challenge (if needed). When the request is finished a <code>BarionAuthenticationSucceeded</code> or <code>BarionAuthenticationFailed</code> event is fired respectively.
+
==== Step 3: 3DS authentication & challenge ====
 +
This data then should be passed onto the <code>authenticate()</code> method of the offsite gw manager, which will do all the magic to authenticate and display the challenge (if needed).
 +
<source lang=javascript line highlight="9">
 +
        // call Barion API via merchant's backend
 +
        // once the result is returned continue with authentication
 +
        $.ajax({
 +
            url: "Url/Of/Your/Payment/Start",
 +
            method: "POST",
 +
            data: data,
 +
            success: function (threeDsClientData) {
 +
              // the threeDsClientData will be in the response of payment/start
 +
              gw.authenticate(threeDsClientData);
 +
            }
 +
        });
 +
</source>
 +
 
 +
When the request is finished the appropriate callback is fired, the BarionClient was initialized with in [[#Step 1 : Initialize oneClick|Step 1]]. In case of successful authentication, you have to call our [[Payment-Complete-v3|/Payment/Complete]] endpoint, where the actual charge will happen.
 +
 
 +
=== Recurring payment/Merchant Initiated payment ===
 +
 
 +
For these types of payments, the subsequent payments are nearly identical to the process of [[#Creating_the_token|Creating the token]]. The only difference is that the <code>TraceId</code> received in the initial [[Payment-GetPaymentState-v2|GetPaymentState]] response must be sent in the
 +
[[Payment-Start-v2|Payment/Start]] request. Also don't forget to set the appropriate [[RecurrenceType|Recurrence Type]].
  
 
=== Possible error responses ===
 
=== Possible error responses ===
Line 170: Line 334:
 
| InvalidRecurrenceId|| The token specified in the <code>RecurrenceId</code> is invalid. Check if the token registration was successful.
 
| InvalidRecurrenceId|| The token specified in the <code>RecurrenceId</code> is invalid. Check if the token registration was successful.
 
|-
 
|-
| RecurringPaymentDenied|| Something happened to the user since the token registration, either deleted, suspended or blocked. The payment s not allowed in these cases.
+
| RecurringPaymentDenied|| Something happened to the user since the token registration, either deleted, suspended, or blocked. The payment s not allowed in these cases.
 
|-
 
|-
| InsufficientFunds|| If the original payment was with e-money wallet and the customer doesn't have enough money to fulfill this charge this error happens.
+
| InsufficientFunds|| If the original payment was with an e-money wallet and the customer doesn't have enough money to fulfill this charge this error happens.
 
|-
 
|-
 
| OriginalPaymentWasntSuccessful || This means that the token belongs to an originally unsuccessful payment so this token can not be used anymore. This could only happen if the original payment was financed with a credit card.
 
| OriginalPaymentWasntSuccessful || This means that the token belongs to an originally unsuccessful payment so this token can not be used anymore. This could only happen if the original payment was financed with a credit card.

Latest revision as of 17:02, 25 November 2020

Token Payment with 3D Secure

WARNING
This article is incomplete. It may change significantly without any notice, so don't rely on any content you find here yet. Please check back later.

This payment scenario allows the integrator shop to register a token for a customer (and a funding source) in the Barion system and then, later on, using this token, charge the customer without redirecting her to the Barion Smart Gateway UI. The user may be present at the site of the merchant or she can be off-session as well, so the merchant can charge her e.g. for subscriptions. This means that the customer authorizes the shop to charge her card or Barion balance without typing in the card information or Barion login again.

Premium feature
This scenario is not allowed automatically for every approved shop and should be requested from Barion!

Token payment scenarios

Token payment can be used in three use cases:

  • Customer Initiated Payments: when the user is present on the website of the merchant and she decides to pay :
    • OneClick payment: the user is charged upon her request initiated on the website of the merchant. Subsequent payments are subject to PSD2 SCA and as the user is present, she has to go through the authentication process.
  • Merchant Initiated Payments: when the merchant initiates the payment without the user being present. It has two subtypes:
    • Recurring payment: the user is charged with the same amount on a regular basis, typically in case of subscriptions. Subsequent payments are exempted from PSD2 SCA, but liability still shifts to the card issuer.
    • MIT (merchant initiated transaction): the user is charged on an irregular basis and/or with a different amount. Subsequent payments of this type are excluded from PSD2 SCA, the liability is on the merchant.

Customer participation

Since the token scenario is suitable for both customer and merchant initiated payments here is a comparison about who starts the payment. This includes the regular, non-tokenized payment scenario as well:

Scenario Initial payment Subsequent payments
Customer present Customer at Barion Smart GW Customer present Customer at Barion Smart GW
Non token (regular) payment YES YES YES YES
OneClick payment YES YES/NO1 YES NO
Recurring payment YES YES/NO1 NO NO
MIT YES YES/NO1 NO NO

1 Token payment scenarios can be initiated with already registered RecurrenceId as well, in this case the customer may remain on the merchant's site.

Requirements for the scenarios

These token payment scenarios have different requirements, this table below summarizes the key differences.

Scenario Payment amount Payment frequency Liability in case of fraud
OneClick payment Various Various Card issuer
Recurring payment Subsequent amounts must be equal or less than the initial amount Initial payment defines a minimum amount of days to wait between charges Card issuer
Merchant initiated payment Various Various Merchant

3DS authentication of the payer

The new more secure 3DS v2 authentication must be performed for every online card payment. These token payment scenarios also have to use this new secure way of authentication. The initial payment of a token scenario must be authenticated every time although the subsequent payments may be exempted in certain cases.

Here is a table to compare the 3DS authentication requirements:

Scenario Initial payment Subsequent payments
One-click payment ✔️ ✔️
Recurring payment ✔️
Merchant initiated payment ✔️

Example scenarios

Phone bill

Payer has a usage-based phone subscription that wants to pay without being present for every charge. She authorizes the phone company to charge her card every month.

  • Scenario: Merchant Initiated Transaction
  • Explanation: Despite the frequency of the charges is monthly, the amount of the subsequent payments may exceed the initial payment.

TV subscription

Payer subscribes to online streaming of a television channel. She authorizes the phone company to charge her card every month. The subscription fee is the same for every month.

  • Scenario: Recurring payment
  • Explanation: The amount of the subsequent payments will not exceed the initial payment and the charge is regularly monthly-based.

Bookclub with "free first month" bonus

Payer subscribes to a book renting service. She authorizes the book club to charge her card every month for a selection of books. The subscription fee is the same for every month however, the first month is free. To ensure the subscription the service requires her to register her card details.

  • Scenario: Merchant Initiated Transaction
  • Explanation: Despite the frequency of the charges is monthly, and the fee will stay the same, the initial payment is zero. So the amount of the next payment will exceed the initial payment.

Online food delivery service

The food delivery company wants to provide a quick and easy experience for its customer. They decide that the order will be quicker if the customers don't leave the website to pay for the goods.

  • Scenario: OneClick payment
  • Explanation: The customer will always be there so the other two scenarios are not available.

How to decide

To help you decide on a suitable scenario, please use the decision graph below:

3ds-recurrencetype-decision.png

Prerequisites

To be able to integrate your webshop with the Barion Payment Gateway:

  • You must register a Barion wallet at the Barion website or in the Sandbox environment. Learn more about the Sandbox environment here.
  • For this wallet you have to create a shop which should be approved by Barion.
  • For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be a USD account created in your wallet.
  • To make sure every corner case scenario works for your webshop it is best to top up that account with a small amount (approx. 5-10EUR or your choice of currency around the same value).
  • For the technical communication guide please read this: Calling the API

The payment process

The process is divided into two major steps:

  1. Creating the token that represents one of the customer's funding sources (credit card or e-money wallet)
  2. Using the registered token to charge the customer

Creating the token

To be able to use a token payment scenario first we have to register the token with Barion. The token registration is basically a normal payment with three extra properties in the Payment/Start request. This means that the mercahnt has to make sure that the customer is well aware of the fact that they are giving consent to a tokenized payment. The Barion Smart Gateway UI does not indicate in any way that the payment is a token payment.

By default the token is registered to the shop and not to the Barion account. So if the Barion account has multiple shops, the registered tokens can not be shared among them even if the customer is the same. If you want to use tokens in multiple shops, please contact Barion in the Customer center.

InitiateRecurrence, RecurrenceId and RecurrenceType

Let's start with the InitiateRecurrence property. This is a bool property, if you set it to true then the payment gateway will consider the request as a token registration. This happens even if the customer is already has a registered token, so you are able to re-register a customer.

The other required property for a token registration is the token itself. This is generated by the shop and has to be unique for every registration. The token should be specified in the RecurrenceId property of the Payment/Start request. This token should be stored in the webshop database. Make sure that multiple tokens can belong to a single customer because the token is only unique for a specific shop, customer, funding source combination.

The appropriate Recurrence Type property has to be specified. In case of Recurring Payment PurchaseInformation.RecurringExpiry and PurchaseInformation.RecurringFrequency must also be set.

An already used RecurrenceId can be used for re-registration, in this case, the new funding source will be registered for the token.

Token payment 1.png

Example JSON request

 1 {
 2     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
 3     "PaymentType": "Immediate",
 4     "PaymentRequestId": "EXMPLSHOP-PM-001",
 5     "InitiateRecurrence": true,
 6     "RecurrenceId": "SHOP-XMLP-TOKEN-ABC-123",
 7     "FundingSources": ["All"],
 8     "Currency": "EUR",
 9     "Transactions": [
10         {
11             "POSTransactionId": "EXMPLSHOP-PM-001/TR001",
12             "Payee": "[email protected]",
13             "Total": 25.2,
14             "Comment": "Subsription fee for the first month",
15             "Items": [
16                 {
17                     "Name": "Website subscription",
18                     "Description": "Website subscription for one month",
19                     "Quantity": 1,
20                     "Unit": "month",
21                     "UnitPrice": 25.2,
22                     "ItemTotal": 25.2,
23                     "SKU": "EXMPLSHOP/SKU/PHC-01"
24                 }
25             ]
26         }
27     ]
28 }

Customer selects funding source

After the proper payment preparation, the customer is redirected to the secure Barion Smart Gateway to choose a funding source. The funding source the customer selects will be registered to the token. The funding source can either be a Barion e-money balance or a bank card. This means that even though the customer may own multiple cards only the one that was registered to the token can be used for future token payments. To change the funding source attached to the token a new registration should be requested.

Processing the response

The response is almost the same as to a basic Immediate scenario. The only difference is that there is the RecurrenceResult property that tells the result of the token registration. This could be either

  • Successful: the token is registered and live, can be used for payment
  • Failed: the token registration was not successful, the token can not be used
  • None: this could only happen if no token payment was requested

TraceId

In case of Recurring payment or Merchant initiated payment the GetPaymentState response returns an additional field called TraceId. The value of this property is generated by the card issuer. You have to save it and submit is in all subsequent Recurring or Merchant initiated payments of the same type, or otherwise the payments can be declined by the issuer. The TraceID represents the first, customer-present payment and helps the issuer to connect subsequent payments to this initial payment.

Displaying the funding source in a GUI

We strongly advise to save the complete response for future reference. The FundingSource field tells if the funding source is a Barion balance or a card. If it is a card, it is useful to save FundingInformation for displaying it for the user, when requesting future payments. The usual way to display funding sources is to show the last 4 digits of the card, with the rest represented by stars, eg: **** **** **** 1234. The card used can be obtained from FundingInformation's BankCard field. The CardType field can be used to display the appropriate card logo. You can even show, if the card is expired, and offer to register another one.

Possible error responses

Error code Description
RecurringPaymentNotAllowed The token payment is not allowed for the shop identified by the POSKey. Contact Barion to request this feature.


Using the token

Depending on the type of the subsequent payment, 3DSecure authentication might be required for subsequent payments. 3DS authentication is not required in the following cases:

  • the token was requested before 3DS came into effect,
  • the original payment was not initialized by bank card,
  • the subsequent payment is a merchant initiated payment.

Prerequisites

To be able to use a token, the initial payment must be in a successful state.

Token payment 2.png

OneClick payment

Step 1 : Initialize oneClick

You have to include the following css and javascript files in the code of your site. These files include all the necessary javascript code and styling to handle the 3DS authentication and display the challenge if necessary.

<link href="https://secure.barion.com/static/barion.offsitegw.min.css" rel="stylesheet">
<script src="https://secure.barion.com/static/barion.offsitegw.min.js"></script>

Then you have to initialize the Barion javascript client:

const configuration = {
    onAuthenticationSucceeded: function () {
        // handle successful authentication by calling the Barion API via merchant's backend
        // Call the v2/payment/complete endpoint
    },
    onAuthenticationFailed: function () {
        // Handle unsuccessful authentication result, no charge was made.
        // The payment might be still valid only the authentication failed
    }
}

const gw= new Barion.OffsiteGw(configuration);

Step 2 : Make a payment

To use an already registered token for a payment, you have to call the same /Payment/Start API endpoint but the InitiateRecurrence should be set to false and the appropriate Recurrence Type should be sent. This tells the Barion API to use the token for payment instead of only registering it. The token should be specified in the RecurrenceId property along with the TraceId.

Example Payment/Start json request
 1 {
 2     "POSKey": "E31EC263-01DC-40BD-BDF1-38FC7A332434",
 3     "PaymentType" : "Immediate",
 4     "PaymentRequestId": "EXMPLSHOP-PM-002",
 5     "InitiateRecurrence" : false,
 6     "RecurrenceType" : "OneClickPayment",
 7     "RecurrenceId" : "SHOP-XMLP-TOKEN-ABC-123",
 8     "TraceId" : "SHOP-XMLP-TRACEID-123",
 9     "FundingSources": ["All"],
10     "Currency": "EUR",
11     "Transactions": [
12         {
13             "POSTransactionId": "EXMPLSHOP-PM-002/TR002",
14             "Payee": "[email protected]",
15             "Total": 25.2,
16             "Comment": "Subsription fee for the second month",
17             "Items": [
18                 {
19                     "Name": "Website subscription",
20                     "Description": "Website subscription for one month",
21                     "Quantity": 1,
22                     "Unit": "month",
23                     "UnitPrice": 25.2,
24                     "ItemTotal": 25.2,
25                     "SKU": "EXMPLSHOP/SKU/PHC-01"
26                 }
27             ]
28         }
29     ]
30 }
Processing the Payment/Start response

To this request, the Barion API sends back the required data for the 3DS authentication for the specified paymentId.

Field name Description
PaymentId Payment Identifier of the purchase in Barion
ThreeDSAuthClientData basae64 encoded 3DS client data
Example Payment/Start response
1 {
2     "PaymentId" : "dce46843-6266-4c1f-b82a-387e0fee9073",
3     "ThreeDSAuthClientData" : "ewoJIkNhcmRQdWJsaWNJZCI6ICIxYTE5M2E1NDQzNDI0YjJiOGJiMjMyOGRhNWY4NmYzYiIsCgkiUGF5bWVudElkIjogImRjZTQ2ODQzNjI2NjRjMWZiODJhMzg3ZTBmZWU5MDczIiwKCSJPbmVDbGlja0NvbnRlbnRVcmwiOiAiaHR0cDovL3NlY3VyZS5iYXJpb24uY29tL3RocmVlZHMvb25lY2xpY2twYXltZW50IiwKCSJBQ1NTdGFydFByb3RvY29sVmVyc2lvbiI6ICIyLjEuMCIsCgkiQUNTRW5kUHJvdG9jb2xWZXJzaW9uIjogIjIuMS4wIiwKCSJEU1N0YXJ0UHJvdG9jb2xWZXJzaW9uIjogIjIuMS4wIiwKCSJEU0VuZFByb3RvY29sVmVyc2lvbiI6ICIyLjIuMCIsCgkiVGhyZWVEU1NlcnZlclRyYW5zSUQiOiBudWxsLAoJIlRocmVlRFNNZXRob2RVUkwiOiBudWxsLAoJIlRocmVlRFNNZXRob2REYXRhRm9ybSI6ICJleUowYUhKbFpVUlRUV1YwYUc5a1RtOTBhV1pwWTJGMGFXOXVWVkpNSWpvaWFIUjBjSE02THk4elpITXVZbUZ5YVc5dUxtTnZiUzh6WkhNdmRqSXZNMlJ6TFcxbGRHaHZaQzF1YjNScFptbGpZWFJwYjI0aUxDSjBhSEpsWlVSVFUyVnlkbVZ5VkhKaGJuTkpSQ0k2SWpFNE5URTJPR0kxTFRKalkyUXROR0kxWlMxaVlqWm1MVFUzTW1VM00yVTNNemt3TnlKOSIsCgkiRXJyb3JEZXRhaWxzIjogbnVsbCwKCSJWZXJzaW9uIjogIjIuMS4wIgp9Cg=="
4 }

Step 3: 3DS authentication & challenge

This data then should be passed onto the authenticate() method of the offsite gw manager, which will do all the magic to authenticate and display the challenge (if needed).

 1         // call Barion API via merchant's backend
 2         // once the result is returned continue with authentication
 3         $.ajax({
 4             url: "Url/Of/Your/Payment/Start",
 5             method: "POST",
 6             data: data,
 7             success: function (threeDsClientData) {
 8                // the threeDsClientData will be in the response of payment/start	
 9                gw.authenticate(threeDsClientData);
10             }
11          });

When the request is finished the appropriate callback is fired, the BarionClient was initialized with in Step 1. In case of successful authentication, you have to call our /Payment/Complete endpoint, where the actual charge will happen.

Recurring payment/Merchant Initiated payment

For these types of payments, the subsequent payments are nearly identical to the process of Creating the token. The only difference is that the TraceId received in the initial GetPaymentState response must be sent in the Payment/Start request. Also don't forget to set the appropriate Recurrence Type.

Possible error responses

Error code Description
InvalidRecurrenceId The token specified in the RecurrenceId is invalid. Check if the token registration was successful.
RecurringPaymentDenied Something happened to the user since the token registration, either deleted, suspended, or blocked. The payment s not allowed in these cases.
InsufficientFunds If the original payment was with an e-money wallet and the customer doesn't have enough money to fulfill this charge this error happens.
OriginalPaymentWasntSuccessful This means that the token belongs to an originally unsuccessful payment so this token can not be used anymore. This could only happen if the original payment was financed with a credit card.
InvalidCurrency If the original payment was paid with e-money and the current token payment is in a currency that the wallet does not have an account in this error happens.