Difference between revisions of "Token payment upgrade to 3DS"

From Barion Documentation
Jump to navigation Jump to search
 
(23 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{PageTitle|title=Upgrading token payment implementation to comply with 3DS}}
 
{{PageTitle|title=Upgrading token payment implementation to comply with 3DS}}
 
__NOTOC__
 
__NOTOC__
{{IncompletePage}}
+
 
{{NotificationBox|title=NOTE|text=This tutorial was created to help merchants that already have token payment integration with Barion. If you are planning to create a new integration, please read [[Token_payment_3D_Secure|this description]]!|color=#1993c7}}
+
{{NotificationBox|title=NOTE|text=This tutorial was created to help merchants that already have token payment integration with Barion. First, please read through the detailed description of the new [[Token_payment_3D_Secure|token payment with 3DS]]!|color=#1993c7}}
 
= Background =
 
= Background =
[[Token_payment|Token payment]] is a solution that enables the merchant to charge the payer without the presence of them. It is a powerful tool to conduct subscription-like or payer-not-present scenarios. This scenario requires the merchant to create a token that would act as an identifier for the payer's funding source. To attach that token to a valid funding source the merchant had to do several things:
+
[[Token_payment_3D_Secure|Token payment]] is a solution that enables the merchant to charge the payer without the presence of them. It is a powerful tool to conduct subscription-like or payer-not-present scenarios. This scenario requires the merchant to create a token that would act as an identifier for the payer's funding source. To attach that token to a valid funding source the merchant had to do several things:
 
# Create an alphanumeric token
 
# Create an alphanumeric token
 
# Conduct an initial payment in which this token gets registered in the Barion system  
 
# Conduct an initial payment in which this token gets registered in the Barion system  
Line 13: Line 13:
 
This meant that as far as this token referenced a valid (and still available) funding source the merchant could create payments without any limitations. Basically, this token symbolized the funding source. It was up to the merchant to decide what it is used for, neither Barion nor the card issuer was aware of the nature of the subsequent payments.  
 
This meant that as far as this token referenced a valid (and still available) funding source the merchant could create payments without any limitations. Basically, this token symbolized the funding source. It was up to the merchant to decide what it is used for, neither Barion nor the card issuer was aware of the nature of the subsequent payments.  
  
This funding source can be either a card or an e-money wallet and this is up to the payer to choose. In case the payer chooses to fund the payment from their e-money wallet there is no further need for extra security. On the other hand when it comes to card payment the authentication process changed with the new Strong Customer Authentication directive and the 3DS v2 protocol.
+
This funding source can be either a card or an e-money wallet and this is up to the payer to choose. In case the payer chooses to fund the payment from their e-money wallet there is no further need for extra security. On the other hand, when it comes to card payment the authentication process changed with the new Strong Customer Authentication directive and the 3DS v2 protocol.
  
 
= Changes =
 
= Changes =
Line 22: Line 22:
 
First of all the merchant has to decide what kind of token payment scenario is suitable. These scenarios are the following:
 
First of all the merchant has to decide what kind of token payment scenario is suitable. These scenarios are the following:
 
* '''One-click payment''': The payer clicks on the "Purchase" button but the charge happens in the background without the payer leaving the merchant's site.
 
* '''One-click payment''': The payer clicks on the "Purchase" button but the charge happens in the background without the payer leaving the merchant's site.
* '''Recurring payment''': The payer authorizes the merchant (at the initial payment) to charge their card periodically without being present.
+
* '''Recurring payment''': The payer authorizes the merchant (at the initial payment) to charge their card periodically without being present with the same amount.
* '''Merchant initiated payment''': The payer authorizes the merchant to charge their card without restrictions.
+
* '''Merchant initiated payment''': The payer authorizes the merchant to charge their card without restrictions (eg. amounts can vary).
  
These scenarios have different properties and requirements, this table below summarizes the key differences.
+
To decide on a suitable scenario, please [[Token_payment_3D_Secure#Token_payment_scenarios|read this detailed description]]
 
 
{|class="wikitable"
 
|-
 
! Scenario
 
! Payer present?
 
! Amount
 
! Frequency
 
! Liability
 
|-
 
| One-click payment || Yes || Various || Various || Card issuer
 
|-
 
| Recurring payment || No || Various || Fixed  || Card issuer
 
|-
 
| Merchant initiated payment || No || Various  || Various || Merchant
 
|-
 
|}
 
 
 
<div style="border: 1px solid #aaa; background-color:#eee; font-size: 0.8em; padding:5px 10px;">
 
Explanation:<br/>
 
<hr/>
 
'''Payer present''': indicates whether the payer is present during the subsequent payments. During the first (initial) payment, the payer is always present in every scenario. <br/>
 
'''Amount''': specifies whether the amount of the payments can change from payment to payment or must be the same.<br/>
 
'''Frequency''': specifies whether it is mandatory to wait a fixed number of days between payments or the charges can happen ad-hoc.  <br/>
 
'''Liability''': describes the entity who is liable for the payment in case of fraud
 
</div>
 
 
 
To help you decide on a suitable scenario, please use the decision graph below:
 
 
 
[[File:3ds-recurrencetype-decision.jpg|500px]]
 
  
 
{{NotificationBox|title=CHANGE|text=The intended scenario must be specified in the new [[RecurrenceType|ReccurenceType]] property (located in the [[Payment-Start-v2|Payment/Start]] request)|color=#20c400}}
 
{{NotificationBox|title=CHANGE|text=The intended scenario must be specified in the new [[RecurrenceType|ReccurenceType]] property (located in the [[Payment-Start-v2|Payment/Start]] request)|color=#20c400}}
Line 60: Line 31:
 
== Usage of TraceId ==
 
== Usage of TraceId ==
  
3DS authentication requires another identifier. This new identifier is used to differentiate these token payment scenarios and help the issuer control what is non-fraudalent transaction.
+
3DS authentication requires another identifier. This new identifier is used to differentiate these token payment scenarios and help the issuer control what is a non-fraudulent transaction.
  
So from now on there will be two IDs for every payer-not-present scenario:
+
So from now on, there will be two IDs for every payer-not-present scenario:
 
* <code>RecurrenceId</code> for the funding source: this identifies the source of the money (could be card or wallet)
 
* <code>RecurrenceId</code> for the funding source: this identifies the source of the money (could be card or wallet)
 
* <code>TraceId</code> (new) for the ''nature of the charge:'' this identifies the type of token payment scenario the merchant is conducting.
 
* <code>TraceId</code> (new) for the ''nature of the charge:'' this identifies the type of token payment scenario the merchant is conducting.
Line 70: Line 41:
 
{{NotificationBox|title=CHANGE|text=The TraceId must processed from the [[Payment-GetPaymentState-v2|GetPaymentState]] response and must be attached to the payment in merchant's system. |color=#20c400}}
 
{{NotificationBox|title=CHANGE|text=The TraceId must processed from the [[Payment-GetPaymentState-v2|GetPaymentState]] response and must be attached to the payment in merchant's system. |color=#20c400}}
  
Once the <code>TraceId</code> is acquired it must be sent in the [[Payment-Start-v2|Payment/Start]] request to identify the scenario. This is crutial for the card transactions othherwise the  
+
Once the <code>TraceId</code> is acquired it must be sent in the [[Payment-Start-v2|Payment/Start]] request to identify the scenario. This is crucial for the card transactions otherwise they could be declined.
 +
 
 +
{{NotificationBox|title=CHANGE|text=The TraceId must specified in the [[Payment-Start-v2|Payment/Start]] for the subsequent token charges. |color=#20c400}}
 +
 
 +
== 3DS v2 authentication ==
 +
 
 +
The new more secure 3DS v2 authentication must be conducted for every online card payment. These token payment scenarios also need to use these new secure way of authentication.
 +
The initial payment must be authenticated every time although the subsequent payments may be exempted in certain cases.
 +
 
 +
 
 +
= Technical changes required =
 +
The technical changes depend on what type of token scenario is needed for the business. It is important to notice that these scenarios can be implemented beside each other, a merchant is not required to choose only one type of token payment. The main goal is to appropriately use each scenario.
 +
 
 +
== Technical changes for Recurring payments ==
 +
 
 +
#''' For the token registration''' in the [[Payment-Start-v2|Payment/Start]] request the new properties have to be specified:
 +
#* <code>"RecurrenceType" : "RecurringPayment"</code> to indicate the scenario
 +
#* <code>PurchaseInformation.RecurringExpiry</code> and <code>PurchaseInformation.RecurringFrequency</code> for the limitations <br/><br/>
 +
#Once the callback is received get the response of [[Payment-GetPaymentState-v2|GetPaymentState]]. In case the charge was successful, there will be a <code>TraceId</code> property for the payment. The value of it must be saved and attached to the payment. 
 +
#'''For subsequent payments''' in the [[Payment-Start-v2|Payment/Start]] request specify the
 +
#* <code>"RecurrenceType" : "RecurringPayment"</code>
 +
#* and the <code>TraceId</code> you received for the initial payment.
 +
 
 +
== Technical changes for Merchant initiated payments ==
 +
 
 +
#''' For the token registration''' in the [[Payment-Start-v2|Payment/Start]] request the new property has to be specified:
 +
#* <code>"RecurrenceType" : "MerchantInitiatedPayment"</code> to indicate the scenario
 +
#Once the callback is received get the response of [[Payment-GetPaymentState-v2|GetPaymentState]]. In case the charge was successful, there will be a <code>TraceId</code> property for the payment. The value of it must be saved and attached to the payment. 
 +
#'''For subsequent payments''' in the [[Payment-Start-v2|Payment/Start]] request specify the
 +
#* <code>"RecurrenceType" : "MerchantInitiatedPayment"</code>
 +
#* and the <code>TraceId</code> you received for the initial payment.
 +
 
 +
== Technical changes for One-click payments ==
 +
 
 +
This modification needs the most attention since the merchant has to implement client-side functionality and add a new step at the end of the flow.
 +
 
 +
#''' For the token registration''' in the [[Payment-Start-v2|Payment/Start]] request the new property has to be specified:
 +
#* <code>"RecurrenceType" : "OneClickPayment"</code> to indicate the scenario
 +
#'''For subsequent payments''' the merchant has to integrate the barion.offsitegw.js to be able to authenticate the payer via 3DS v2 on the merchant's site. To do this read the tutorial on [[Token_payment_3D_Secure#OneClick payment|how to integrate this]].
 +
# After a successful authentication a new Barion API endpoint ([[Payment-Complete-v2|/Payment/Complete]]) must be called to finalize the process and charge the card
 +
 
 +
Please notice that in case this scenario is used there is no need to use the <code>TraceId</code> since the 3DS authentication will be performed every time.
  
 +
{{NotificationBox|title=CHANGE|text=In case of one-click token scenario the merchant has to authenticate every card payment with 3DS v2|color=#20c400}}
  
[[File:Recurring-post3ds.png|1280px]]
 
  
 +
== What happens if the merchant doesn't upgrade its implementation ==
  
{{NotificationBox|title=CHANGE|text=The TraceId must processed from the [[Payment-GetPaymentState-v2|GetPaymentState]] response and should be sent during the subsequent charges. |color=#20c400}}
+
There will be a two-phase ramp-up period to make sure that integrations can be upgraded.
  
 +
'''Until December 31, 2020'''
  
== Prepare for 3DS authentication ==
+
In this period the integrations that are not up-to-date and are not capable to handle 3DS v2 transactions '''will work'''.
 +
* New tokens can be initiated (without RecurrenceType and TraceId) and the 3DSv2 authentication will be performed by the Barion Smart Gateway.
 +
* Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId.
  
The new more secure 3DS v2 authentication must be conducted for every online card payment. These token payment scenarios also need to use these new secure way of authentication. The initial payment must be authenticated every time although the subsequent payments may be exempted in certain cases. This table displays the different scenarios and the 3DS authentication requirements.
 
  
{|class="wikitable"
+
'''Between January 1 and January 31, 2021 '''
|-
 
! Scenario
 
! Initial payment
 
! Subsequent payments
 
|-
 
| One-click payment || ✔️ || ✔️
 
|-
 
| Recurring payment || ✔️ ||
 
|-
 
| Merchant initiated payment || ✔️ ||
 
|-
 
|}
 
  
 +
In this period the integrations that are not up-to-date and are not capable to handle 3DS v2 transactions '''will work'''. However, to comply with the card scheme mandates Barion has to substitute the missing information.
 +
* New tokens can be initiated (without RecurrenceType and TraceId) and the 3DSv2 authentication will be performed by the Barion Smart Gateway. The payment will be marked as an initial MIT transaction. The MerchantInitiatedPayment RecurrenceType will be used as a fallback.
 +
* Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId. They will be handled as the subsequent MIT payment of the initial transaction. The TraceId will be filled in by Barion.
 +
* This period allows all merchants to finish upgrading their integrations, receive TraceIds during subsequent payments, and send it back with the next subsequent payment, so Barion doesn't have to substitute it with a static value anymore.
  
  
 +
'''From February 1, 2021'''
  
{{NotificationBox|title=IMPORTANT|text=Starting from January 1 the [[3DSecure|3DS authentication]] will be mandatory for all of our partners!|color=#20c400}}
+
Until this date, all integrations must be upgraded.
 +
* New tokens can only be initiated with the appropriate 3DSv2 information (RecurrenceType set). Otherwise, the payment/start will result in a validation error.
 +
* Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId. They will be handled as the subsequent MIT payment of the initial transaction. The TraceId will be filled in by Barion. This can be used until the card schemes allow this kind of TraceId substitution.
  
  
== What happens if I don't change my implementation ==
+
{{NotificationBox|title=SUPPORT|text=In case you have difficulties with the upgrade please contact our developers at [email protected] |color=#1993c7}}
TODO
 

Latest revision as of 08:56, 2 March 2021

Upgrading token payment implementation to comply with 3DS


NOTE
This tutorial was created to help merchants that already have token payment integration with Barion. First, please read through the detailed description of the new token payment with 3DS!

Background

Token payment is a solution that enables the merchant to charge the payer without the presence of them. It is a powerful tool to conduct subscription-like or payer-not-present scenarios. This scenario requires the merchant to create a token that would act as an identifier for the payer's funding source. To attach that token to a valid funding source the merchant had to do several things:

  1. Create an alphanumeric token
  2. Conduct an initial payment in which this token gets registered in the Barion system
  3. Refer to this token in a subsequent payment attempt

Recurring-pre3ds.png

This meant that as far as this token referenced a valid (and still available) funding source the merchant could create payments without any limitations. Basically, this token symbolized the funding source. It was up to the merchant to decide what it is used for, neither Barion nor the card issuer was aware of the nature of the subsequent payments.

This funding source can be either a card or an e-money wallet and this is up to the payer to choose. In case the payer chooses to fund the payment from their e-money wallet there is no further need for extra security. On the other hand, when it comes to card payment the authentication process changed with the new Strong Customer Authentication directive and the 3DS v2 protocol.

Changes

To make sure that the payer has more control over these token scenarios and the card issuer knows more about the payment scenarios several things need to be changed.

Token payment scenarios

First of all the merchant has to decide what kind of token payment scenario is suitable. These scenarios are the following:

  • One-click payment: The payer clicks on the "Purchase" button but the charge happens in the background without the payer leaving the merchant's site.
  • Recurring payment: The payer authorizes the merchant (at the initial payment) to charge their card periodically without being present with the same amount.
  • Merchant initiated payment: The payer authorizes the merchant to charge their card without restrictions (eg. amounts can vary).

To decide on a suitable scenario, please read this detailed description

CHANGE
The intended scenario must be specified in the new ReccurenceType property (located in the Payment/Start request)

Usage of TraceId

3DS authentication requires another identifier. This new identifier is used to differentiate these token payment scenarios and help the issuer control what is a non-fraudulent transaction.

So from now on, there will be two IDs for every payer-not-present scenario:

  • RecurrenceId for the funding source: this identifies the source of the money (could be card or wallet)
  • TraceId (new) for the nature of the charge: this identifies the type of token payment scenario the merchant is conducting.

This new TraceId is generated and stored by the card issuer. The Id is available in the GetPaymentState response once the charge is successfully completed.

CHANGE
The TraceId must processed from the GetPaymentState response and must be attached to the payment in merchant's system.

Once the TraceId is acquired it must be sent in the Payment/Start request to identify the scenario. This is crucial for the card transactions otherwise they could be declined.

CHANGE
The TraceId must specified in the Payment/Start for the subsequent token charges.

3DS v2 authentication

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


Technical changes required

The technical changes depend on what type of token scenario is needed for the business. It is important to notice that these scenarios can be implemented beside each other, a merchant is not required to choose only one type of token payment. The main goal is to appropriately use each scenario.

Technical changes for Recurring payments

  1. For the token registration in the Payment/Start request the new properties have to be specified:
    • "RecurrenceType" : "RecurringPayment" to indicate the scenario
    • PurchaseInformation.RecurringExpiry and PurchaseInformation.RecurringFrequency for the limitations

  2. Once the callback is received get the response of GetPaymentState. In case the charge was successful, there will be a TraceId property for the payment. The value of it must be saved and attached to the payment.
  3. For subsequent payments in the Payment/Start request specify the
    • "RecurrenceType" : "RecurringPayment"
    • and the TraceId you received for the initial payment.

Technical changes for Merchant initiated payments

  1. For the token registration in the Payment/Start request the new property has to be specified:
    • "RecurrenceType" : "MerchantInitiatedPayment" to indicate the scenario
  2. Once the callback is received get the response of GetPaymentState. In case the charge was successful, there will be a TraceId property for the payment. The value of it must be saved and attached to the payment.
  3. For subsequent payments in the Payment/Start request specify the
    • "RecurrenceType" : "MerchantInitiatedPayment"
    • and the TraceId you received for the initial payment.

Technical changes for One-click payments

This modification needs the most attention since the merchant has to implement client-side functionality and add a new step at the end of the flow.

  1. For the token registration in the Payment/Start request the new property has to be specified:
    • "RecurrenceType" : "OneClickPayment" to indicate the scenario
  2. For subsequent payments the merchant has to integrate the barion.offsitegw.js to be able to authenticate the payer via 3DS v2 on the merchant's site. To do this read the tutorial on how to integrate this.
  3. After a successful authentication a new Barion API endpoint (/Payment/Complete) must be called to finalize the process and charge the card

Please notice that in case this scenario is used there is no need to use the TraceId since the 3DS authentication will be performed every time.

CHANGE
In case of one-click token scenario the merchant has to authenticate every card payment with 3DS v2


What happens if the merchant doesn't upgrade its implementation

There will be a two-phase ramp-up period to make sure that integrations can be upgraded.

Until December 31, 2020

In this period the integrations that are not up-to-date and are not capable to handle 3DS v2 transactions will work.

  • New tokens can be initiated (without RecurrenceType and TraceId) and the 3DSv2 authentication will be performed by the Barion Smart Gateway.
  • Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId.


Between January 1 and January 31, 2021

In this period the integrations that are not up-to-date and are not capable to handle 3DS v2 transactions will work. However, to comply with the card scheme mandates Barion has to substitute the missing information.

  • New tokens can be initiated (without RecurrenceType and TraceId) and the 3DSv2 authentication will be performed by the Barion Smart Gateway. The payment will be marked as an initial MIT transaction. The MerchantInitiatedPayment RecurrenceType will be used as a fallback.
  • Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId. They will be handled as the subsequent MIT payment of the initial transaction. The TraceId will be filled in by Barion.
  • This period allows all merchants to finish upgrading their integrations, receive TraceIds during subsequent payments, and send it back with the next subsequent payment, so Barion doesn't have to substitute it with a static value anymore.


From February 1, 2021

Until this date, all integrations must be upgraded.

  • New tokens can only be initiated with the appropriate 3DSv2 information (RecurrenceType set). Otherwise, the payment/start will result in a validation error.
  • Subsequent payments can use existing tokens (RecurrenceId) without specifying the TraceId. They will be handled as the subsequent MIT payment of the initial transaction. The TraceId will be filled in by Barion. This can be used until the card schemes allow this kind of TraceId substitution.


SUPPORT
In case you have difficulties with the upgrade please contact our developers at [email protected]