WL SIPS DOCS

Release 25.4

go directly to content

Search by keywords

  1. Tokenisation
  2. Scheme token
  3. On behalf merchant token

On behalf merchant token

To search in the page use Ctrl+F on your keyboard

Introduction

The aim of this document is to present the integration of the use of scheme tokens in the payment process with merchant token.

Who does this document target?

This document is aimed at merchants and their technical teams who wish to use scheme tokens in their CIT (Customer Initiated Transaction) or MIT (Merchant Initiated Transaction) in a Card-on-file (COF) context with a merchant token.

To have an overview of Worldline Sips solution, we recommend that you consult the following documents :

Functional schema

This diagram describes the technical relationships between the merchant, Worldline Sips and TSPs (Token Service Provider).


Schema describing relationships between the merchant, Worldline and various TSP

Worldline Sips communicates with the TSPs on behalf of the merchant, who does not directly interact with the TSPs.

Registration with TSP

Registration with the TSP is done through Worldline Sips. However, it is preferable to inform your acquirer in advance.

List of items to provide :

  • Trade name of the webshop ;
  • Webshop identification number :
    • VISA and Mastercard : VAT identification number ;
    • CB : Token Requestor ID (Initial temporary operation) ;
    Note:

    Initial CB process specifics : You must contact your acquirer to request registration with the CB TSP. Once this registration is completed, the CB GIE will send the merchant (via their acquirer) an identifier (Token Requestor ID) that must be communicated to Worldline Sips.

  • Scheme token notifications reception URL

Use cases

Here are the use cases of the scheme token on Worldline Sips when using merchant token.

Scheme tokenization on CIT with merchant token

To benefit from scheme tokenization on CIT, it is imperative to have the option merchant token enabled.

Scheme tokenization applies from a transaction under the following conditions :

  • Authenticated (3-D Secure)
  • Authorized
  • Merchant token provided
Note:

No recovery of card-on-file stock is possible.

The merchant token can be provided :

  • by the merchant
  • After a transaction if the option to generate it is enabled

Here is the diagram of scheme tokenization with a merchant token in input :


Diagram explaining the generation of a scheme token by performing a merchant token payment

The merchant performs a payment using a merchant token by requesting Worldline Sips. If the transaction is properly authenticated with 3-D Secure, the authorisation request is performed using the card data associated with the merchant token as well as the authentication data, and the merchant receives the authorisation response with the merchant token and the authentication data. Once the authorisation has been performed, Worldline Sips asynchronously requests the TSP to generate a scheme token, then stores it by associating it with the merchant token used for the payment. Once the scheme token has been activated by the TSP, the TSP notifies Worldline Sips, who in turn sends a scheme token update notification to the merchant.

Here is the diagram of scheme tokenization without a merchant token as input but with the generation on transaction option activated :


Diagram explaining the generation of a scheme token by performing a card payment

The merchant performs a payment using card data by requesting Worldline Sips. If the transaction is properly authenticated with 3-D Secure, the authorisation request is performed using the card data as well as the authentication data, a merchant token linked to this card is generated, and the merchant receives the authorisation response with the generated merchant token and the authentication data. Once the authorisation has been performed, Worldline Sips asynchronously requests the TSP to generate a scheme token, then stores it by associating it with the generated merchant token. Once the scheme token has been activated by the TSP, the TSP notifies Worldline Sips, who in turn sends a scheme token update notification to the merchant.

Payment with the scheme token

As described previously, the first transaction using a merchant token will not use the scheme token, and only the generation of the scheme token will be performed.

The next time this merchant token is used, it will be replaced by the associated scheme token.

Here is a diagram describing this operation :


Diagram describing a scheme token payment using a merchant token

The merchant requests Worldline Sips with a merchant token to perform a payment. Worldline Sips retrieves the scheme token associated with this merchant token, then performs the authorisation request using the scheme token instead of the card data, then responds to the merchant with the authorisation result.

If an error occurs during the process before the authorization request, Worldline Sips will fallback to the PAN associated to the merchant token instead of using the scheme token.

Follow the scheme token lifecycle

Once created, the scheme tokens follow a lifecycle, as described in the diagram below. The status changes can be triggered by the TSPs, for example in the case of a scheme token expiration.


scheme token lifecycle diagram

Once created, the scheme token has the "NOT_YET_ACTIVE" status. Upon activation by the TSP, the scheme token switches to the "ACTIVE" status. From this status, the scheme token transits into the final "DELETED" status upon the "DELETE" action, or into the "SUSPENDED" status upon the "SUSPEND" action. A scheme token with the "SUSPENDED" status switches back to the "ACTIVE" status following the "ACTIVATE" action, or switches to the final "DELETED" status following the "DELETE" action.

Receiving the scheme token update notification

The Worldline Sips server sends an update notification when a scheme token status changes, or when its associated card data are updated. This notification is a HTTP(S) POST request, with a format similar to the one of Sips Paypage automatic response, and secured by the computation of a signature, the Seal.

The scheme token update notification is directly sent to the scheme token notification URL address configured in your contract. The Worldline Sips server does not expect any response after the notification has been sent.

It is your responsibility to retrieve the various data of the notification, check the signature to make sure the fields of the notification have not be tampered with, and update your back office.

Attention:

The scheme token update notification is systematic, asynchronous and sent through the network. It is inherently dependent on potential technical troubles on the various network elements and can now and then be received with a more or less substantial delay, or never be received at all. The notification is sent in case of a scheme token update. However, if no notification URL is configured in your contract, the Worldline Sips server does not send the notification.

In the manner of Sips Paypage automatic response, the notification consists of the four below fields:

Field Comments/rules
Data Notification data in JSON format.
Encode Type of encoding used to encode the Data field. Since the scheme token update notification is not encoded, this field is not filled in.
Seal Notification signature.
InterfaceVersion Connector interface version. Since the Data field uses the JSON format, this version has the following format: JS_3.x.
Verifying the Seal data element

If you carry out the authentication steps by means of an electronic seal, you should make sure the seal you received in the notification actually matches the seal you recomputed using the response fields.

The seal is computed using the most recent active secret key from your contract. The version of the secret key used to compute the Seal data element is indicated by the notification keyVersion field. In the case of a service provider acting on behalf of a merchant, the employed secret key corresponds to the provider's one, and the provider identifier is specified in the intermediateServiceProviderId field. This identifier corresponds to the one provided upon the scheme token option enrollment.

In case the seal you received does not match the seal you recomputed, the received notification must be considered as invalid.

The Seal data element is computed as follows:

  • use of the secret key corresponding to the specified keyVersion field to compute the HMAC variant of the message;
  • use of the Data field only;
  • UTF-8 encoding of the data constituting the result of the previous operation;
  • HMAC-SHA hashing of the bytes obtained.

This procedure can be summarized as follows:

HMAC-SHA256(UTF-8(Data), UTF-8(secretKey))

Some seal computation code examples are available in the Sips Paypage documentation.

IMPORTANT:

The scheme token update notification Seal data element is systematically computed using the HMAC-SHA-256 algorithm. It is important not to sort the content of the Data field to compute the scheme token update notification seal. Keep the fields in the same sequence you received them.

Retrieving the notification fields

The notification data contained in the Data field uses the JSON format, which has the following structure: {"key1":"value1","key2":"value2",...}.

Notification data example:

{
	"keyVersion": 1,
	"merchantId": "029000254447216",
	"sealAlgorithm": "HMAC-SHA-256",
	"merchantToken": "AbcdEfghIjkLmNo/",
	"schemeTokenReference": "V:a123bc4d-5678-9efg-hi01-jk2l3mn456o7",
	"schemeTokenStatus": "ACTIVE",
	"schemeTokenExpiryDate": "203002",
	"schemeTokenSuffix": "0800",
	"schemeTokenRequestorId": "12345678901",
	"schemeTokenUpdateDateTime": "2025-04-01T12:12:35Z",
	"cardScheme": "VISA",
	"cardCobadgedScheme": "CB",
	"cardExpiryDate": "202601",
	"cardSuffix": "0400",
	"paymentAccountReference": "5577729c2fff49698bbce797637bc"
}

The scheme token update notification data fields list and their description are available on this page.

Among these fields, the one described in the table below let you identify the scheme token and retrieve its status:

Field Description
merchantToken Identifies the merchant token linked to the updated scheme token
schemeTokenReference Scheme token reference, to be used to identify the token when calling Sips Office scheme token service's getCardMetaData function.
schemeTokenStatus Indicates the scheme token status.

The possible scheme token statuses sent by the notification are described in the table below:

Scheme token status Notification field Description
Awaiting activation schemeTokenStatus = NOT_YET_ACTIVE The scheme token is awaiting activation by the TSP
Active schemeTokenStatus = ACTIVE The scheme token is active and can be used for payment purposes
Suspended schemeTokenStatus = SUSPENDED The scheme token is suspended and cannot be uses for payment purposes, unless it is reactivated
Deleted schemeTokenStatus = DELETED The scheme token is deleted and cannot be used anymore

Scheme token lifecycle management methods

The lifecycle of a Scheme token can be managed by a new Scheme Token service via Sips Office.

GetCardMetaData

When Worldline Sips sends you a notification regarding a change associated with the lifecycle of the scheme token, this method allows you to retrieve information related to the scheme token using its reference.

You can notably retrieve information such as:
  • Payment account reference
  • Card expiration date
  • Scheme token expiration date
  • Card suffix
  • Token status
More information available on the dedicated page here.

Disable the scheme token option

If the option is disabled, payments will no longer be made with a scheme token linked to the merchant token. The payment process will be as it was before its activation.

Back to top Need help?

This site uses trackers to improve your experience, perform analysis and researches on your use of WL Sips documentation website.
You have several options:
Closing this banner you refuse the use of trackers on your device.

Configuration