Token payment upgrade to 3DS

Upgrading token payment implementation to comply with 3DS

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.

NOTE

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 this description!

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

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.
• Merchant initiated payment: The payer authorizes the merchant to charge their card without restrictions.

These scenarios have different properties and requirements, this table below summarizes the key differences.

Scenario	Payer present?	Amount	Frequency	Liability
One-click payment	Yes	Various	Various	Card issuer
Recurring payment	No	Fixed	Various	Card issuer
Merchant initiated payment	No	Various	Various	Merchant

Explanation:

---

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.
Amount: specifies whether the amount of the payments can change from payment to payment or must be the same.
Frequency: specifies whether it is mandatory to wait a fixed number of days between payments or the charges can happen ad-hoc.
Liability: describes the entity who is liable for the payment in case of fraud

The Recurring Payment scenario has some extra restrictions. The merchant has to specify two additional properties in the Payment/Start request:

• RecurringExpiry: The date after the subsequent charges should not accepted.
• RecurringFrequency: The minimum days the merchant has to wait between payments.

Both properties are located in the PurchaseInformation property and must be specified if this scenario is selected.

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

File:3ds-recurrencetype-decision.jpg

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. A TraceId can only be used again if:

• the funding source is the same (technically the RecurrenceId is the same)
• the token payment scenario is the same (technically the RecurrenceType is the same)
• the request complies with the scenario restrictions

CHANGE

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

If any of these parameters change the merchant has to request new IDs. What to request depends on what needs to change. This is described in the Changing the existing token IDs section.

Since the RecurrenceId identifies the funding source it is possible that with the same RecurrenceId the merchant uses several different TraceId tokens. This is required in a scenario when the merchant wants to provide a new type of token payment for the payer but does not wants to redirect them to Barion again. This is described in the Multiple Trace IDs section.

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.

• For One-click scenarios the payer is always present so for every purchase the payer must be authenticated via 3DS v2 (this does not mean that they will be challenged every time)
• For Recurring scenarios the initial payment must be authenticated and as long as the TraceId remains the same the subsequent payments are exempted from authentication.
• For Merchant initiated scenarios the initial payment must be authenticated and as long as the TraceId remains the same the subsequent payments are exempted from authentication.

This table summarizes the 3DS authentication requirements for different token scenarios.

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

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.offsite.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/CompletePayment) 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.

Changing the existing token IDs

Sometimes it is important to re-register already existing token IDs. Let's go over these possible scenarios

Changing the funding source

This could happen if the funding source becomes invalid for some reason (card gets deleted or expires) or the merchant decides to use that token for another payer. In this case, the merchant has to register the RecurrenceId again. To do this a new payment must be started and in the Payment/Start request the following setup should be specified:

• the InitiateRecurrence field has to be set to true
• the RecurrenceId has to be specified.
• and the TraceId should not be specified.

Since the TraceId is bound to the payer and the process if the funding source changes new TraceId will be generated. This new ID must be saved to this payment and must be used from this moment on for subsequent payments.

Changing the token payment scenario

This could occur when the merchant wants to get authorization from the payer to a new token scenario for the already registered funding source. To be able to do this the merchant has to have a valid and registered RecurrenceId. Let's see some examples when this may be necessary:

• The payer subscribed to the merchant's service beforehand and the merchant decided to use the recurring payment token scenario. The payer wants to subscribe to another service and this requires a different payment schedule. This means that the RecurringFrequency that was specified initially can not be maintained so it is required to acquire a new TraceId
• The payer bought something on the merchant's website and uses the one-click feature for subsequent fast non-redirect payments. After a while, the payer decides to subscribe to a service provided by this same merchant. This means that the merchant has to create a new token scenario (not a one-click payment but a recurring payment). For this, the merchant has to acquire a new TraceId. This can be done without redirecting the payer to Barion using the existing RecurrenceId and performing a 3DS authentication on the merchant's website.

To do these a new payment must be started and in the Payment/Start request the following setup should be specified:

• the InitiateRecurrence field has to be set to false
• the RecurrenceId has to be specified.
• and the TraceId should not be specified.

After this, a 3DS authentication has to be completed to acquire a new trace ID.

Multiple Trace IDs

TODO

What happens if the merchant doesn't upgrade its implementation

TODO