The Create Corporate Contract API allows the creation of a new corporate contract with the company organization (complete or partial structure).

Pre-conditions:

The correlation ID, if provided by the issuer, must be unique. In case of re-use of a correlation ID from an existing corporate contract, the system will return the data from the existing corporate contract (e.g., if the API call returns a "time-out" response, the same correlation ID can be provided to retrieve corporate contract data from Worldline system for further checks).

During the corporate contract creation

1) The issuer can provide a list of new customers/companies, otherwise the references to existing customers/companies in Worldline system can be used

2) The issuer has the possibility to create

• the company organization, by adding 1 or several corporate entities such as countries, divisions, departments (this is also possible afterwards with dedicated API)
• the employees with their cards and accounts (this is also possible afterwards with dedicated API)

As a result, the contract is created:

• with its own reference calculated by our system
• with the status set to "Signed"
• with entity levels of the company organization (at least the company itself)
• with the root entity account

The API response returns

• the different identifiers related to the corporate contract, such as the contract itself, contract owner, account owner of an entity
• if requested identifiers of employee accounts, card contracts, cards and cardholders if any (each identifier is composed of the Worldline internal reference and, optionally, the external reference if provided by the issuer in the request)

The references are used to: retrieve/update/close corporate contracts, retrieve the list of entities for a corporate contract, retrieve the corporate employee account, etc.

API links

The API allows to close a corporate contract identified by the Issuer Contract external reference or the Contract reference.

The corporate contract can be closed immediately or in the future at a date provided by the issuer.

As a result,

• For immediate corporate contract closing: the corporate contract is closed, the cards within the corporate contract are deactivated, the accounts closing process is started for all accounts.
• For scheduled corporate contract closing (closing in the future): as soon as the closing date is reached then the immediate corporate contract closing process is applied.

API links

This API allows an issuer to add to an existing corporate contract an employee with a new card and a new card account. Different types of card products (e.g. MCI/VISA debit, credit, prepaid) are supported.

The issuer shall provide the required data

• employee information (new or existing one)
• the product extension, with appropriated card and account products among those available for the corporate product used to create the contract
• required data for card and account
• the entity of the company organization to which the employee should be attached (e.g. employee to be attached to department A)

The issuer can replace default membership fee and/or account setup fee (contract fees) by specific ones.

The API response returns the extended corporate contract with information related to newly created employee account(s), card contract(s) and card(s) only.

API links

This API allows an issuer to add a new entity to the company organization such a new country, division or department to an existing corporate contract.

The issuer shall provide required data to create the new entity such as

• the product extension to be used among those available for the corporate product used to create the contract
• entity and account data
• customer (person) or company information (new ones) or customer references (existing ones in Worldline system)

The API response returns the extended corporate contract with information related to the newly added entity to the company organization and its associated account(s)only.

API links

The API is used to trigger an on demand pro rata refund of Account Setup (AS) fee or Membership fee (MS) for the unutilized period.

Pre Conditions:

• In case refund for Account Setup fee is requested then card contract closure date should be less than card contract creation date + 1 year
• In case refund for Membership fee is requested, then the Membership fee should already be posted
• Account setup fee refund on demand can be received only once during contract lifecycle
• Membership fee refund on demand can be received only once between Membership fee anniversary dates

The issuer can request the refund by AS or MS fee by providing:

• The fee type: Either Account Setup fee or Membership Fee
• Card Contract Reference

As a Result:

• For Account Setup fee:
  • If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: Posted AS fee amount * (Number of days from contract cancellation till (card contract creation + 1 year) / number of days in the year),
  • In other cases, it will be calculated in the following logic:,Posted AS fee amount * (Number of days from the date when demand for refund is received till (card contract creation + 1 year) / number of days in the year)
• For Membership Fee:
  • If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: MS fee posted on last MS fee anniversary date * (Number of days from contract cancellation till next MS Fee Anniversary date / number of days in the year)
  • In other cases, it will be calculated in the following logic: MS fee posted on last MS fee anniversary date * (Number of days from the date when demand for refund is received till next MS Fee Anniversary date / number of days in the year).

The API can be used to reallocate an employee (i.e., an employee card contract) within the same or different corporate contract(s).

This reallocation

• must be allowed by the configuration (e.g. original employee product shall be in the list of allowed employee products for the new corporate contract)
• is performed immediately

As a result, when employee reallocation is performed

• the employee new account is created under the given parent account (can be within the same or different corporate contract)
• the employee card contract is reallocated
• the employee new account becomes the posting account for reallocated employee/card contract
• data such as IBAN are transferred to the employee new account
• the employee old account is closed according to standard business rules
• account set-up and membership pending fees are transferred from the employee old account to the employee new account and paid, i.e., periodic fees on the employee new account are normally continued.

This endpoint can be used to create Virtual Card Account (VCA). This is a specific service offered by MCI, VISA and Wordline service (VCE). The VCA is not used to pay transactions, instead a token is requested from MCI, VISA, Worldline service (depends on the Issuer), to fund the transactions.

It is possible to request creation of several VCA Service Cards and Accounts at the same time.

Pre Conditions

• Card Profile related to Virtual Card account should exist

The Issuer can request adding VCA Servive cards and accounts to the corporate contract, by providing:

• employee information (new or existing one)
• the product extension, with appropriated card and account products among those available for the corporate product used to create the contract
• required data for card and account
• the entity of the company organization to which the employee should be attached (e.g. employee to be attached to department A)

As a result

• Dedicated account to the Virtual Card Account is created
• Card Contract and card is created related to VCA Service

The API response returns the extended corporate contract with information related to newly created VCA Service account(s), card contract(s) and card(s).

This API allows the contract owner for a corporate contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.

The API response contains :

• either customer information if the contract owner is a person
• or company information if the contract owner is a company

The API allows a cardholder to subscribe to an additional service (e.g. new letter, travel insurance) for the corporate contract during all contract life cycle.

The list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).

The main input fields requested by the API are:

• The issuer ID
• The corporate contract for which the add-on subscription is requested: It can be provided by using the contract reference or the issuer external contract reference
• The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
• The corresponding reference of the additional service
• The service type reference defined at product level

Depending on the service type, the issuer can add additional parameters to the add-on service.

As a result:

• The new add-on subscription for the corporate contract is available and can be unsubscribed during all contract life cycle
• A fee can be generated and posted to the cardholder account if required for the product.

The API allows a cardholder to unsubscribe from an additional service (e.g. new letter, travel insurance) for the corporate contract during all contract life cycle.

The main input fields requested by the API are:

• The issuer ID
• The corporate contract for which the add-on unsubscription is requested: It can be provided by using the contract reference or the issuer external contract reference
• The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
• The reference of the additional service
• The service type reference

As a result, the existing add-on subscription for the corporate contract is no longer available.

The API allows the list of additional service subscriptions (e.g. new letter, travel insurance) for the corporate contract to be retrieved.

The main input fields requested by the API are:

• The issuer ID
• The corporate contract for which the add-on subscriptions are requested: It can be provided by using the contract reference or the issuer external contract reference

The API response contains add-on subscription information such as:

• The reference of the additional service subscription
• The service type reference
• The card contract or the account on which the subscription has been done
• The date of subscription to the add-on service
• The list of add-on service parameters if any

The API provides possibility to retrieve a list of corporate contracts, based on certain criteria.

At least the corporate name for searching must be provided and optionally company postal address information (street name, building number, zip code) can be provided.

If requested, the API input parameters allows also to:

• search from an issuer and optionally with sub-issuers OR search from a list of issuers (by default, the search is performed on all issuers allowed for the user depending on its rights)
• retrieve contract owner information
• request to enrich the response with additional data relative to the root account, the companies, the current addresses of the companies, the corporate contract entities and the corporate employee accounts by using embedded fields

The API response contains all matched corporate contracts and for each returned corporate contract some information is provided such as :

• contract identifier with the contract reference, the issuer external contract reference if originally provided
• embedded fields if requested such as root account, list of all companies with their addresses linked to this corporate contract, corporate contract entities, corporate employee accounts.

The API returns the current version of a company's address.

Information to be provided in input:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

The address identifiers, address attributes, address usages and entity reference (application domain of the address) are displayed in the response.

API links

The API allows to create either a permanent address or a temporary address for the company, identified with his reference.

To identify the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)

An address includes the following information:

• the issuer address external reference
• the label (e.g. HEAD_OFFICE)
• the type (mail address, phone number, email) and the corresponding data
• the address usages
• the start date (optional, by default the current date is used)
• the end date (conditional, is mandatory when creating a temporary address)

When creating a temporary address, If a temporary address already exists with an overlap on the activity period then only the newly created address will be kept and the old one will be removed.

The temporary address is active between its start date and end date.

One or several address usages can be added to the address (in order to retrieve this address). An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.

For information, the head office address is mandatory.

In return, the API provides the address reference calculated by the system.

API links

The API updates all the attributes of a company's address.

To identify the address of the company for which updates are required, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

All the attributes must be provided even those unchanged (except for the usages).

The API allows to validate an address ('invalid' status is set to false). But it's not possible to invalidate an address changing the value of the invalid 'flag' to true. If the user tries to do this action, an error message is returned.

One or several address usages can be added to the address (in order to retrieve this address). An address usage is used for specific business process/service. When adding a usage to an address, the usage is immediately active and if it is already assigned to another address, it is removed from this latter.

All the usages already linked to the address cannot be removed via this API.

API links

The API allows to activate on demand of an address.

To activate the address of the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

If a temporary address exists, it becomes also active.

The address identifiers, address attributes and address usages are displayed in the response.

API links

The API is used to deactivate the address.

To deactivate the address of the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

The status becomes "INACTIVE".

This action is forbidden in case of:

• the address label is the HEAD_OFFICE
• an usage is linked to the address.

API links

The address usage describes in which business case the address will be used (eg statement sending, card delivery, ...). The complete authorized values list is shared during the product configuration between the issuer and WL.

This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE).

To create an address usage, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

API links

The API deletes the address usages linked to one address.

To identify the address of the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The address reference or the issuer address reference

The address usages are filtered by the request params :

• addressUsageName (for definition see the ressource addressUsage), mandatory
• entityReference (for definition see the ressource addressUsage), optional
• serviceCode (for definition see the ressource addressUsage), mandatory

If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.

API links

The API creates a company if all the mandatory fields are provided (see company's resource).

By default, the company is considered 'ACTIVE' if the Status field is not provided.

The default address of the company must be also configured.

The API returns a customer reference (as company).

API links

The "retrieve company's information" API allows the user to get company information.

Information to be provided in input:

• The issuer ID
• The customer reference or the issuer customer reference (as company)

In addition to the company information, it is also possible to request the list of addresses and contacts of the company.

API links

The "update company" API allows the user to update the attributes of a customer (as company).

To identify the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company) for which updates are required

The customer reference can be retrieved by using the "Retrieve list of company's information" API.

All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve company's information" API to get all the current attributes.

API links

The "update company partially" API allows the user to update the attributes of a customer (as company).

To identify the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company) for which updates are required

The customer reference can be retrieved by using the "Retrieve list of company's information" API.

With this API, only attributes that need to be updated must be given in input.

API links

The "Retrieve list of company's information" API enables to get a list of customers based on multiple criteria such as corporateName, nationalFiscalNumber, address town name, address postal code.

All companies whose corporate name includes the 'corporate name' parameter are returned (e.g. 'zon' => 'amazon' + 'zon craft', ...)

API links

This API enables all the addresses associated with a given customer (as company), identified by customer reference or issuer customer reference to be retrieved.

To identify the company, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)

The address could be either a permanent address or a temporary address.

Several address types are managed. Each address can be used for a specific usage (card delivery, statement delivery, contract letter,...).

Address usage is associated to a service (card service, account service, dispute service, ..) configured in our system.

The API can retrieve only the addresses linked to a specific usage: in this case, all the mandatory 'AddressUsage' attributes must be provided (e.g. serviceCode, AddressUsage).

If the showHistory indicator is set to Y then the full history of the addresses and the future addresses are returned. If this indicator is empty (default behavior) or equals to N, then only the last active addresses are returned.

Address identifiers, Address attributes and Address usages are displayed in the response.

API links

This API enables all the contracts belonging to a given company to be retrieved.

Information to be provided in input:

• The issuer ID
• The customer reference or the issuer customer reference (as company)

The API response contains a list of contracts with related information.

API links

The API creates a contact person belonging to the company by providing information such as first name, name, department to which he is attached.

To create a contact, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)

API links

The API allows information of a contact of the company to be modified.

To update a contact, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The contact reference

All attributes must be provided (even if some of them have not been modified) else the value of missing attributes will be empty.

API links

The API allows a contact of the company to be deleted.

To remove a contact, it is needed to provide:

• The issuer ID
• The customer reference or the issuer customer reference (as company)
• The contact reference

API links

The API allows the company update history of a company to be retrieved.

The main input fields requested by the API are:

• The issuer ID
• The customer for which information is requested : It can be provided by using the customer reference or the issuer customer external reference (as company).

A start date and an end date can be provided in order to limit the search of the history.

In response, the interface provides a list of changes with the effective date of the update.

API Links

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):

   

"URI":"https":{
   "Root Path"
}"/itsp-add/v2/issuers/9999/tokens/DNITHE301733961114298690/generate-crypto-otp 
Payload":{
   "tokenProviderID":"VTS"
}

"
URI":"https":{
   "Root Path"
}"/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/generate-crypto-otp 
Payload":{
   "tokenProviderID":"MDES"
}

{
    "responseMetadata": {
        "correlationId": "QQI8qq6jIKq5gO78BocFzSSMI9cI2ReD",
        "statusMessage": "OK",
        "statusCode": 200,
        "responseDateTime": "2023-01-18T14:15:40.323Z",
        "timeTakenMs": 12
    },
    "data": {
        "cryptoOTP": "TUJBQUMtMS0xLTdBRjI5MUM5MUYzRUQ0RUY5MkMxRDQ1RUZGMTI3QzFGOUFCQzEyMzQ3RQ=="
    }

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:

"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=="
}

 
{
   "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="
   }
}

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:

    
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"
}

    {
    "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"
    }
}

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:

    URI: https://{Root Path}/itsp-add/v2/issuers/9999/cards/52936061AAAP8026/create-mdes-tokenized-card 
Payload : 
{ 
       "clientWalletProvider": "50120834693"
} 

    
{
   "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...”
         }
    }
}"