Referential WS Client is the standard referential interfaces exposed by the Issuers' Bank.
ACS is therefore client of the Bank Information System.

Thanks to this API ACS can  :

• get card information from the Bank Information System ;
• update cards/users/credentials information to the Bank Information System.

Referential WS Server is the standard referential interfaces exposed by ACS.
The bank is therefore client of ACS.

Thanks to this API the bank can  :

• get card information from ACS ;
• update cards/users/credentials information to ACS.

Version 24R2-1.2 of May 14th 2024

The referential card of an issuer is required. It is used for enrollment and authentication needs of cardholders.

In mode batch the issuer sends a periodic file to the platform in order to operate the provisionning of cardholder data.

The referential management is based on a XML file. This file takes in charge the creation of cardholders, cards and authentication data.

Retro compatibility with old XML and flat file formats is managed.

Glossary :

The following list gives a description of acronyms used :

• WLP-AHB: Worldline Product – Authentication HuB
• PAN: Primary Account Number
• CAP: Chip Authentication Program
• DDN: Birthdate
• PWD: Password
• SSN: Social Security number
• PAM: Personal Assurance Message
• PGP: Pretty Good Privacy
• GPG: GNU Privacy Guard
• PCI: Payment Card Industry

1. Historic

2. Description of referential file in format xml

The structure of file is given by the following figure. The possible values of each field and potential error codes are described in the following tables.

The maximum number of cardholders in a file is limited to 999 999 records.
An example of a report with errors is also available.

  2.1. File transfer mode

File transfers are carried out through a VPN tunnel or on Internet. Two protocols are available FTPs or PesitSSL.

  2.2. Security of exchanges through file transfers

    2.2.1 File encryption/decryption

Files containing sensitive data can be encrypted using PGP.

GPG is used.

The Issuer must use an encryption program that is compatible with the free GPG program used by equensWorldline, which makes it possible to ensure the authenticity and confidentiality of the transferred file with an RSA key.

GPG is a free implementation of the RSA algorithm that complies with the OpenPGP standard (RFC2440).

A REAL NAME (e.g. IssuerName_3DSAtos), a COMMENT (e.g. Atos 3DS signature by Issuer Name) and an E-MAIL ADDRESS will be specified to generate the keys.

The encryption algorithm used is AES256.

The ISSUER and equensWorldline exchange the public keys via e-mail in ASC format.

Keys are valid for 19 months. 

To comply with PCI, the key must not be used for encryption for more than 12 consecutive months. The expiry date is set to 19 months to allow restoration for 6 months; an extra month is added to the validity period of the key.

File encryption/decryption procedure:

Exchange of keys (carried out every 12 months):

• ISSUER generates a pair of keys: Public Key (P1) and Secret Key (S1);
• equensWorldline generates a pair of keys: Public Key (P2) and Secret Key (S2);
• Issuer and equensWorldline exchange their P1 and P2 public keys.

For the encryption/decryption of a file sent by ISSUER to equensWorldline, the file is encrypted with equensWorldline’s P2 key and signed with ISSUER’s S1 private key.

For the encryption/decryption of a file sent by equensWorldline to ISSUER, the file is encrypted with ISSUER’s P1 key and signed with equensWorldline’s S2 private key.

Keys are renewed through equensWorldline’s change tool. The application manager will get in touch with the customer contact appointed during the creation of the key to ask them to send the new public key; in return, they will provide equensWorldline’s new public key. The content to exchange will be the result of the export of the public key into ASCII. This will be sent via e-mail. To validate the public keys exchanged, each person involved will have to phone their appointed contract to obtain and validate the fingerprint of the key. It is imperative that the fingerprint be validated before the public key is used.

    2.2.2. Data security

The sensitive data contained in the file must be encrypted. Authentication data and card information are considered as sensitive.

For the repository file, the data to encrypt are:

• The PAN of the Card element;
• The value of the Authentication element (Phone number, email, date of birth, etc.).

All encrypted data will be encoded in Base64.

Symmetric encryption uses the AES algorithm.

The data are encrypted using 256-bit AES in CBC mode (Cipher Block Chaining); more precisely, it uses a Java implementation called javax.crypto.Cipher "AES/CBC/PKCS5Padding".

Upon each encryption operation, an IV (Initialization Vector) set to empty is used.

The encryption and decryption keys are identical.

The AES key is generated by the Issuer.

A different key will be used for each environment.

The exchange of such key whose generation remains at the responsibility of the issuer is not specified in this document.

  2.3. XML file for updating the cardholder repository

XML format è equensWorldline provides the Issuer with the .XSD file that makes it possible to generate this format.

The format will be XML in “MAJ” format according to the particularities of equensWorldline.

A different file transfer identifiers have to be defined for acceptance and production.

Description of referential file in a XML format

The structure of file is given by the following figure. The possible values of each field are described in the following tables. The maximum number of cards in a flat file is limited to 999 999 records.

  2.4. Description of fields

Each field must respect constraints in order not to be rejected. The following list gives a description of possible format controls:

• AN: Alphanumeric
• A: Alphabetic
• N: Numeric
• H: Hexadecimal
• B64: Base 64

    2.4.1. Record « Header »

    2.4.2. Structure « Header »

The field FileNumber is incremental and depends on the day when the file is received. So, if this field is valued by 728502, it means that the file is the 2nd file of day 285 of the year 2007. The batch can controls that there does not exist two files with the same identifier and reject it in case of duplication. The batch does not control the field FileNumber.

    2.4.3. Record « CardHolder »

    2.4.4. Structure « CardHolder »

    2.4.5. Structure « Card »

    2.4.6. Authentication Data

To process the authentication flow, several authentication data can be stored: 

• PHONE: the phone number (Deprecated)
• SMS : mobile phone number
• SVI : fix phone number for IVR authentication
• EMAIL: the email address
• SSN: the Social Security Number, person identifier
• PAM: the Personal Assurance Message
• TOKEN: the identifier of the token
• DDN: the birthdate
• PWD: the password
• TA: trusted authentication

HUB phone number must be in international standard E.164 format.
E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits.

    2.4.7. Structure « CardData »

Note: CardData is not currently used.

    2.4.8. XML message example

Here is an example with:

• A card where all authentication data are replaces with provided ones,
• Another card where only EMAIL authentication data is created/updated,
• And a last one where nothing is created/updated/deleted (since no authentication data is provided)

Here is another example with:

• A card to which we delete the value of a credential,
• A card where all authentication data are replaces with provided ones

    2.4.9. File processing report

During the integration process of XML, a log file can be provided by file transfer. This file contains all rejected records with an error label associated to each reject. The file describes a global report of execution of integration and each error is formatted according to the following rules:

• If the reject happens in the section Header:
  • Format: Error on Header : Error Label
  • Example: Error on Header : Issuer is invalid
  • Signification: The issuer code mentioned in the Header has invalid format.
• If the reject happens in the section CardHolder
  • Format: Error on CardHolder(identifier): Error Label
  • Example: Error on CardHolder(identifier=12345678901234567890123456789012345678) : The length of the identifier must be between 1 and 36
  • Signification: The Cardholder with identifier 12345678901234567890123456789012345678 has a field Identifier whose length is too long.
• If the reject happens in the section Card
  • Format: Error on CardHolder(identifier) - Card# : Error Label
  • Example: Error on CardHolder(identifier=111447612) - Card#1 : PAN is invalid Signification: The PAN of card having the IdElement=1 in section CardHolder having identifier=111447612 is invalid or missing.

    2.4.10. Example file log report

    2.4.11. Description

For each batch, the report file starts by “start execution date” and “file name” and finishes by “returned code”, “job Id”, “end execution date” and “duration”.

Between the start and the end of execution, we have all reported data errors, as described in previous section. This is followed by a summary of the number of cards treated, and number of found records for each kind of movement.

3. Validation rules for xml format

  3.1. Header

  3.2. CardHolder

  3.3. Card

  3.4. AuthenticationData

4. Functional Validation rules

4.1.  File reject

If more than 5% of lines are in error the file is rejected with an error code 12 : “Batch KO, number of line errors greater than 5%”.

The blocking errors :

If the header is empty the file is rejected with an error code 40 : "No header specified"
If the header format is invalid the file is rejected with an error code 41 : "Specified header is incorrect"
If the header format is invalid the file is rejected with an error code 18 : "Error read input file xml"

Non-blocking errors threshold:

A skip limit can be defined for the non-blocking exceptions if this limit is reached the file is rejected.
By default the parameter is set to 100%.

Skip limit parameter : ${app-skip-limit}

4.2.  Skipped requests

On batch process, the skipped card are corresponding to the specific use case :

• On ACS3 XML format
  • Record Card in UpdateMode = CREATE_ONLY but the card is already exist in Data Base, so we can’t create it , so request is skipped

• On ACS1 XML or CSV format

  • Record Card with ModificationType = RENEWAL but the card doesn’t exist in Data Base, so we can’t renewal it, so request is skipped
  • Record Card with ModificationType = DELETION but the card doesn’t exist in Data Base, so we can’t delete it, so request is skipped
  • Record Card with ModificationType = REPLACE but the card doesn’t exist in Data Base, so we can’t replace it and retrieve the initial credentials, so request is skipped

   

The card referential contains card holder information, PAN and credentials.

The master referential can be on ACS side or on bank side.

When the master referential is on ACS side the provisioning can be done by batch or/and an API the Referential WS Server.

When the master referential is on bank side ACS retrieves information by an API the Referential WS Client.

This API based service is for requesting PSPs in the Worldline VoP Hub ecosystem and EPC scheme. It allows to process the verification of a payee identity via a single request to the Worldline VoP Hub, based on identification data and account data entered bv the Requester (Payer) in any payment channel of the PSP.

Features

The service will route the request to the corresponding responding bank using its dedicated directory service, obtain or compute a matching result (depending on the source of account holder information data or direct match result), and return it to the requesting PSP under 3 seconds (or timeout).

The API supports name + IBAN matching (returning a corrected name in case of a close match) as well as additional identifiers when supported by the responding bank.

Process

1. The Requesting bank gathers information from the Requester (payer) about the subject of the VoP (Payee), before initiating a payment from any Sepa Credit Transfer channel.
2. The API client authenticates towards VoP Hub and sends a request containing the gathered identification data and account reference.
3. The VoP Hub routes the request to the corresponding responding bank, part of its reachable VoP interfaces.
4. The VoP Hub receives the match result or necessary account holder information from the responding PSP.
5. The API client receives the resulting API response, which may include the corrected name according to the responding bank, in case of close matches. 
6. The Requester is informed of the matching result, applies potential corrections and proceeds with payment initiation.

API Security

• Authentication: The Worldline VoP Hub uses an authentication service that adheres to the OIDC standard protocol. 
  For enhanced security, the client must present an (qualified) SSL certificate to authenticate.

• Secure Communication: All communications utilize MTLS with TLS 1.2 or higher, ensuring that data in transit is secure.

   

  To learn more about how security at the transport layer is implemented through encryption, token management, and digital signatures to protect communication and authentication processes, please visit our Security pages.

   

In the EPC VoP scheme

According to the EPC Document 218-23, "Verification Of Payee Scheme Rulebook" first version for public consultation :

The Responding PSP is the Participant that receives the VOP Request from the Requesting PSP and Instantly processes that VOP Request. 
The Responding PSP is also obliged to Instantly send a VOP Response containing a matching result about the received details of the Payment Counterparty or another reason, back to the Requesting PSP.
The Responding PSP may also be the Payment Counterparty.

Worldline provides API and file exchange based services for scheme participants who need to fulfil this role and intend to comply with all its rules.

The following simplified diagram represents how the Worldline VoP services operate on behalf of Responding PSPs in the EPC scheme :

Services

To produce match results on behalf of the Responding PSP, Worldline needs access to account related information of the subject of the Verification of Payee.

Two services are available for that purpose, and are detailed at the following locations in this developer portal :

• Responding PSP API : a real time API definition to expose account holder data to the Worldline VoP Services.
• Account Data Management : an API or file exchange based service for responding PSPs to delegate the storage of account holder data to the Worldline VoP services, then used to produce match results when answering VoP requests.

To learn more about how security at the transport layer is implemented through encryption, token management, and digital signatures to protect communication and authentication processes, please visit our Security pages.