Mobile Payment Operations
Worldline proposes to Issuing banks to apply card digitization through its tokenization services.
Worldline proposes to Issuing banks to apply card digitization through its tokenization services. A “token” is a unique set of digits which replaces the usual card PAN number and lowers the payment card risk of compromise. Those tokens of real cards are shared in a secured way with mobile/wearable devices (smartphones with Apple pay or Samsung Pay solutions, watches for Garmin Pay, etc.) so that the cardholder can use them instead of the original card for proximity NFC payments with their devices. They can also be leveraged for the recurrent “Card-on-File” transactions (e.g. Netflix). Each context (devices, e-commerce merchants, etc.) will use a different token.
Our solution exposes a set of APIs to Issuers use cases.
Mobile Banking token provisioning support:
- APP-TO-APP AUTHENTICATION – In this use case, the model is used for Mobile banking App as authentication factor, for identification and verification step
- In App Provisioning – In this use case, Encrypted pass data (for Apple Pay) or payment instrument data (Google wallets) is generated for wallet activation
APP-TO-APP AUTHENTICATION
API Name: generate-crypto-otp
In case of App to App Authentication the cardholder is authenticated via the banking app and the issuer is required to generate a ‘Mobile Banking Authentication Code’ which is delivered via the wallet provider to VTS or MDES for final activation of the token. This Api is common to all Token Requestors, and can be requested by non-sensitive field, either on a specific token (TokenReferenceId), or on a specific card. The choice depends on implementation of mobile banking app.
This service lookup locally to retrieve card data, such as PAN and expiry dates, before computing the activation code, according to either VTS – App to App authentication, or MDES – App to App authentication. We assume that on this step, these data are known, as provisioning flow is already initiated, and on ‘step-up’ before activation.
If the request is done by card, this service requests I-TSP decoupling layer to retrieve card data before computing.
Flow diagram (request by token):
Request data
For Token Reference:
"URI":"https":{
"Root Path"
}"/itsp-add/v2/issuers/9999/tokens/DNITHE301733961114298690/generate-crypto-otp
Payload":{
"tokenProviderID":"VTS"
}
For Card Reference:
"
URI":"https":{
"Root Path"
}"/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/generate-crypto-otp
Payload":{
"tokenProviderID":"MDES"
}
Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "OK",
"statusCode": 200,
"responseDateTime": "2023-01-18T14:15:40.323Z",
"timeTakenMs": 12
},
"data": {
"cryptoOTP": "TUJBQUMtMS0xLTdBRjI5MUM5MUYzRUQ0RUY5MkMxRDQ1RUZGMTI3QzFGOUFCQzEyMzQ3RQ=="
}
In App Provisioning
APPLE PUSH PROVISIONING
API Name: create-apple-tokenized-card
Background for Push Provisioning:
In case the cards are added via the banking app the issuer needs to generate the Payment Instrument Details to push the tokenization via the xPay wallet. In case of Apple Pay the issuer also has to add activation data for additional security. The Payment Instrument Details mainly contain the card number and the expiration date of the card which needs to be tokenized. The Payment Instrument Detail is pushed via the wallet server of the xPay based on the xPay interface specifications. The xPay wallet server than will forward it to VTS or MDES, and processed usually as a green flow.
Service provided by I-TSP for this purpose create-apple-tokenized-card (specific Apple variant), generates the complete Payment Data Payload for ApplePay, requested with non-sensitive card data. This service requests the Card Management System to retrieve card data, before computing the payload, according to either Visa or Mastercard flavors.
Note that Apple wallet returns Apple Certificate to mobile application. The validity of this certificate has to be controlled by Issuer (AC chain, dates, specific OID, CRL), and public key extracted, for addressing this service. They are duty of Issuer back-end. As I-TSP has no direct contractual agreement with Apple, there is no possibility to have details about format of Certificate data returned by Apple Wallet, as well as having valid test vectors. Nevertheless, Apple In-App Provisioning specification (document under NDA) gives details on this step.
Below a sample Java code to extract Public Key from Apple leaf certificate (X.509v3 / PEM format) before passing it to this I-TSP Api:
CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
X509Certificate certificate = (X509Certificate) certificateFactory.generateCertificate(new ByteArrayInputStream(certificateBytes));
System.out.println(Base64.toBase64String(certificate.getPublicKey().getEncoded()));
Flow diagram:
Request data
"URI":"https":{
"Root Path"
}"/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/create-apple-tokenized-card
Payload":{
"tokenProviderID":"VTS",
"nonce":"2E1DF468",
"nonceSignature":"401FE09091CE8CB9E8846199587E4417AAE9421F7E9BACB993C57A4E806C4F29716E350060769B0616A11164DF25229D56732A0A5BAEA388F284E5DA369BDA8A2510B86622720808FCA797AAAA8B4B2063",
"applePublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELj5cz2uasEvnoi8/rM/ec8h+hxVTlKNIFUCKiWyhijdNrGaa879iIPyGN2f0r0dQfFvCIfxKGYdNrzm0B04+uA=="
}
Response data
{
"responseMetadata":{
"correlationId":"QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage":"OK",
"statusCode":200,
"responseDateTime":"2023-01-18'T'14:15:40.323Z",
"timeTakenMs":12
},
"data":{
"encryptedPassData":"aFKevI11muy+D1roaD08NuF2HGnIN5LRKDOGC00nTnERWtkR2IzB6jxe55p8mMc10K3GEjhUPIN2/g4D0wYkzk1GMg9z...",
"activationData":"TUJQQUMtMS1GSy0xLS1UREVBLTgzQjlEOTdCMEEzM0FCRDk5RkQwQkI5NkEwMjM3NTEzNDNCMERDRDA3NTAyNTFFRTk1NTVBMzIzQUE1OTU1QjVGNjU3ODBERTZGNDk4NkI5",
"ephemeralPublicKey":"BPrz+LFGyvw3WbuveJ7rLOUKYC2S0lJXYVFXSUCjYTiiS/pT64+Wri3gp3QUIMx8W7mx+Iab5TMC2UDRqMknICY="
}
}
GOOGLE PUSH PROVISIONING
VTS Push Provisioning
API Name: create-vts-tokenized-card
Background for Push Provisioning:
In case the cards are added via the banking app the issuer needs to generate the Payment Instrument Details to push the tokenization via the xPay wallet. The Payment Instrument Details mainly contain the card number and the expiration date of the card which needs to be tokenized. The Payment Instrument Detail is pushed via the wallet server of the xPay based on the xPay interface specifications. The xPay wallet server than will forward it to VTS or MDES, and processed usually as a green flow.
Service provided by I-TSP for this purpose is create-vts-tokenized-card (generic per Visa specifications).It is used by all non-Apple wallets (for example by Google who calls structure Opaque Payment Data).
The following web service generates the complete Card Provisioning Payload as specified by VTS, requested with non-sensitive card data (issuerCardIdcardReference, that is a Surrogate of the PAN).
This service requests the Card Management System to retrieve card data, before computing the payload, according to Visa “Payment Instrument Details” structure for Push Provisioning.
Flow diagram:
Request data
URI: https://{Root Path}/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/create-vts-tokenized-card
Payload :
{
"clientWalletAccountID": "Lejk2eFZ0gPe9DOFNDAhfHy3",
"clientWalletProvider": "40010075001",
"clientDeviceId": "rdtZyP8u4O5LkQFRgPAB-sHo",
"clientAppID": "de.issuerbanking.mobil",
"country": "DE"
}
Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "OK",
"statusCode": 200,
"responseDateTime": "2023-01-18'T'14:15:40.323Z",
"timeTakenMs": 12
},
"data": {
"paymentInstrumentDetails": "ewoiYWxnIjoiQTI1NkdDTUtXIiwKInR5cCI6IkpPU0UiLAoiaXYiOiJRYVNLdG1qSUpfYnF4OHpzIiwKInRhZyI6IkFweEpuSmJNeTU1OTMzeWZBTFJTY1E9PSIsCiJraWQiOiJOMVdHMThJM1QySDYwOFZHSUZLMjEzUDVKeXdjOFF2WGRUamVBRXR1azdMN0VwZHZ3IiwKImNoYW5uZWxTZWN1cml0eUNvbnRleHQiOiJTSEFSRURfU0VDUkVUIiwKImVuYyI6IkEyNTZHQ00iLAoiaWF0IjoiMTU4NjM1MDkxNCIKfQ.tYYvs2Cdn0qkVNnE5xDAgGkjx-sBQMP7sA-yj1diVL0.1vWxDYGJs5sPqoaa.LzoOgr97kxNUMZfoKdg8L6OsK3HHQvL2dJYRUddqfD-F90LwBNv24Gc5oOfTYuHSjSYqpP82YQcfhPOYexuW7vRWgwxEQo2tT6Vz4n3Zuy5vsT5OFLMSXtMmJpMqqh3ktvZo9D6NCjqzFlIMJFnUpxiX3dUrmUuCq4bGKxoY6C5KLBDhRo4pEyRsjMNugCVSrKTmAW-SnpFmyW8L066a1HfAQoPomMycZ5U26MPPN__x8k57fDycHn8a6BwWm4ssncJP1sHVPxIpmzGkA89g62n_gxIIWkajdA9tA6t9qaokKfL1wqhVvAch-TxhdLTNORhF_UzlZAILmTe3dsDeZlwy8VOzDpih_zo3Jjj5CYbDiR1yOwnjM35pcBByKouKwYTIxlo4L2Pnfk1QaaNjdVAvA4cPMwQSSymG0hUEZfXOjHBJVUyMAlBLZrwcOlkEwV7iQyusKBqT-j0Y9ULTfYoOv5FD_HMf6pNOcVUf5MqMHlONXurje_VaCU1KahR5_F3HB_YCM7Es74DjAtM-UDJ3YHsKX2aNEX5PbCcRophcVlpkgBC1VhUqgYz0Iytq0GkfFepqrGU0hLrk-CrOm9vNRE8.6T00_EU219IJBNreH7rMnQ"
}
}
MDES Push Provisioning
API Name: create-mdes-tokenized-card
Background for Push Provisioning:
In case the cards are added via the banking app the issuer needs to generate the Payment Instrument Details to push the tokenization via the xPay wallet. The Payment Instrument Details mainly contain the card number and the expiration date of the card which needs to be tokenized. The Payment Instrument Detail is pushed via the wallet server of the xPay based on the xPay interface specifications. The xPay wallet server then will forward it to VTS or MDES, and processed.
Service provided by I-TSP for this purpose is create-mdes-tokenized-card. It is used by all non-Apple wallets (for example by Google who calls structure Opaque Payment Data).
The following web service generates the complete Card Provisioning Payload as specified by MDES, requested with non-sensitive card data (issuerCardId, that is a Surrogate of the PAN).
This service requests Card Management system to retrieve card data, before computing the payload, according to Mastercard “Issuer Initiated Digitization Data” structure for Push Provisioning (Funding Account Info + Tokenization Authentication Value).
Flow diagram:
Request data
URI: https://{Root Path}/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/create-mdes-tokenized-card
Payload :
{
"clientWalletProvider": "50120834693"
}
Response data
{
"responseMetadata":{
"correlationId":"QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage":"OK",
"statusCode":200,
"responseDateTime":"2023-01-18'T'14:15:40.323Z",
"timeTakenMs":12
},
"data":{
"issuerInitiatedDigitizationData":{
"fundingAccountInfo":{
"encryptedPayload":{
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF6A",
"publicKeyFingerprint":"4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey":"A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm":"SHA512",
"iv":"31323334353637383930313233343536"
}
},
"tokenizationAuthenticationValue":"\"ew0KICAgInZlcnNpb24iOiAiMyIsDQogICAic2lnbmF0dXJlQWxnb3JpdGhtIjogIlJTQS1TSEEyNTYiLA...”
}
}
}"
Click To Pay
Enroll
API Name: click-to-pay-enroll
This API is to enroll a card into click-to-pay. If account does not exist it will be created. For an account creation (first card) full data must be provided:
Consumer data: name, email, phone, locale, country
Billing Address
For a card enrolment into an existing account, only billing address needs to be provided
I-TSP retrieves card details from CMS (pan, expiry, embossing name, consumerId), acknowledge caller, and will process with Visa APIs asynchronously.
Request data
URI: https://{Root Path}/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/click-to-pay-enroll
Payload :
{
"consumerInformation": {
"name": "John F Doe",
"phoneNumbers": ["+33612345678"],
"emailAddresses": ["john.doe@mydomain.com"],
"locale": "en_US",
"countryCode": "FRA",
"timeOfConsent": "2024-01-12T10:15:20.374Z"
},
"billingAddress": {
"line1":"12 rue Stine",
"postalCode":"37200",
"city":"Tours",
"country ":"FRA"
}
} Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": " ACCEPTED",
"statusCode": 202,
"responseDateTime": "2024-04-18T14:15:40.323Z",
"timeTakenMs": 12
}
}Remove card or account
API Name: click-to-pay-remove
This API is to remove a card or complete account from click-to-pay.
I-TSP retrieves card info from CMS (pan), acknowledge caller, and will process with Visa APIs asynchronously.
If this card is the last one under a click-to-pay account, the complete account will be requested to be removed.
Request data
URI:
POST {rootpath}/itsp-add/v2/issuers/{issuerId}/cards/{cardReference}/click-to-pay-remove?removeAll=(true|false) Response data (Response data is empty, only metadata is provided. )
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "ACCEPTED",
"statusCode": 202,
"responseDateTime": "2024-04-18T14:15:40.323Z",
"timeTakenMs": 12
}
}
Return data
API Name: click-to-pay-account-data
This API will return all data stored into Visa Click-to-Pay for a given card :
Consumer data : name, email, phone, consent info
Payment data : pan last digits, expiry, billing address
It is recommended to be called before any other Click-to-Pay enrollment or management request, in order to avoid desync or failure. I-TSP retrieves card details from CMS (pan, consumerId), then calls Visa API getData, and returns synchronously the content. No data is stored or updated locally at I-TSP.
If more than one card is returned as enrolled into click-to-pay under the same account (consumerId), the cardReference (SurrogateId) of the other cards is not retrieved, only 4 last digits of pan.
Request data
URI:
GET {rootpath}/itsp-add/v2/issuers/{issuerId}/cards/{cardReference}/click-to-pay-account-data
Request Body is empty. Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "OK",
"statusCode": 200,
"responseDateTime": "2024-04-18T14:15:40.323Z",
"timeTakenMs": 12
},
"data": {
"c2pProvider":"Visa",
"cardholderReference":"66012000010001884143",
"consumerInformation": {
"name": "John F Doe",
"phoneNumbers": ["+33612345678"],
"emailAddresses": ["john.doe@mydomain.com"],
"locale": "en_GB",
"countryCode": "FIN",
"timeOfConsent": "2024-01-12T10:15:20.374Z"
},
"cardDetails":[
{
"cardReference":"42936061AAAP8026",
"cardLastDigits":"8026",
"cardExpiryMonth":"06",
"cardExpiryYear":"2025",
"nameOnCard ":"John Doe",
"billingAddress": {
"line1":"1000 Market Street",
"line2":"Building 56",
"line3":"Suite 101",
"postalCode":"94105",
"city":"San Francisco",
"state": "CA",
"country ":"USA"
}
},
{
"cardLastDigits":"4762",
"cardExpiryMonth":"02",
"cardExpiryYear":"2026",
"nameOnCard ":"John Doe",
"billingAddress": {
"line1":"12 rue Stine",
"postalCode":"37200",
"city":"Tours",
"country ":"FRA"
}
}]
}
}
Token Selfcare
Get Token Data / Token List
API Name: token-list
This webservice allows local lookup for tokens attached to a given card. It does not call VTS or MDES, so the result might be desynchronized from Scheme’s repository. But due to its local lookup, this service is faster than inquiring Visa or Mastercard through TLCM Apis. This service can be used for example in front of banking app provisioning, to retrieve list of tokens belonging to a card and do cross-check with known tokens on user device.
Request data
URI:
GET {Root Path}/itsp-add/v2/issuers/{issuerId}/cards/{cardReference}/token-list
Request Body is empty. Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "OK",
"statusCode": 200,
"responseDateTime": "2023-01-18T14:15:40.323Z",
"timeTakenMs": 12
},
"data": {
"tokenDataList": [
{
"tokenProviderID": "VTS",
"tokenReferenceID": "DNITHE462034250054974519",
"tokenStatus": "ACT",
"tokenRequestorID": "40010051602",
"tokenExpiryYear": "2023",
"tokenExpiryMonth": "04",
"tokenType": "COF",
},{
"tokenProviderID": "VTS",
"tokenReferenceID": "DNITHE302034249991296629",
"tokenStatus": "ACT",
"tokenRequestorID": "40010030273",
"tokenExpiryYear": "2023",
"tokenExpiryMonth": "12",
"tokenType": "SE",
"deviceID": "043D050B47508001900614097894935387C61DD337B208C0",
"walletID": "A4DF297BD8466140",
}
],
"cardLastDigits":"1935",
"cardExpiryYear": "2023",
"cardExpiryMonth": "11"
}
} Token details
API Name: details
This webservice allows local lookup for a specific Token Reference Id and if the token is known locally (in I-TSP), then an LCM token inquiry (VTS or MDES) is triggered and latest useful data provided back. This could help Issuer to take some decisions regarding the token management
Request data
URI – by token
GET {Root Path}/itsp-add/v2/issuers/{issuerId}/tokens/{tokenReference}/ tokenRequestors/{tokenRequestorId}/details?provider={tokenProviderID}
For this request the body is empty.
Example:
GET
{Root Path}/itsp-add/v2/issuers/9999/tokens/DNITHE301733964444298690/ tokenRequestors/40010030273/details?provider=VTS Response data
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "OK",
"statusCode": 200,
"responseDateTime": "2023-01-18T14:15:40.323Z",
"timeTakenMs": 12
},
"data": {
"tokenSuffix ": "1234",
"tokenStatus": "SUSPENDED",
"tokenActivationDate": "2024-01-24T10:23:56.SSZ",
"lastTokenStatusUpdatedDate": "2024-01-24T11:23:56.SSZ",
"tokenExpiryDate": "2027-11",
"deviceID": "043D050B47508001900614097894935387C61DD337B208C0",
"walletID": "A4DF297BD8466140",
"deviceName": "My super phone",
"deviceType": "PHONE"
}
} Update token
API Name: update
This webservice allows local lookup for a specific Token Reference Id and if the token is known locally (in I-TSP), then an LCM token inquiry (VTS or MDES) is triggered to request for a token_status update*.
Note: (*) all operationTypes are possible, but for ‘ACTIVATE’, there are some additional rules applied on I-TSP level: for riskLevel=ORANGE or RED, the token activation is not possible.
Request data
URI – by token
POST {rootPath}/itsp-add/v2/issuers/{issuerId}/tokens/{tokenReference}/update?provider={tokenProviderID}
For this request the body is empty.
Example:
POST https://{Root Path}/itsp-add/v2/issuers/9999/tokens/ DNITHE416552825982484844/update? provider=VTS Response data
When token is found on I-TSP and on TSP
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "ACCEPTED",
"statusCode": 202,
"responseDateTime": "2023-01-18T14:15:40.323Z",
"timeTakenMs": 12
}
}
When token /TRID is not found on I-TSP or on TSP
{
"responseMetadata": {
"correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
"statusMessage": "NOT_FOUND",
"statusCode": 404,
"responseDateTime": "2023-01-18T14:15:40.323Z",
"timeTakenMs": 12
}
} 
