API version 2.24.0
Release Notes: Recent Update
Version 2.23.1 to 2.24.0
What's New
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/corporate-contract
Retrieve corporate contract for an account by external reference (beta)
The API enables the corporate contract data for a given account to be retrieved.
POST
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/inquire-operation
Retrieve an operation by external references triplet and account external reference (beta)
The API allows to retrieve an operation using its external operation references for the given account by using issuer account external reference or the account reference (generated by WL).
GET
/issuers/{issuerId}/accounts/{accountReference}/corporate-contract
Retrieve corporate contract for an account (beta)
The API enables the corporate contract data for a given account to be retrieved.
POST
/issuers/{issuerId}/accounts/{accountReference}/inquire-operation
Retrieve an operation by external references triplet (beta)
The API allows to retrieve an operation using its external operation references for the given account by using issuer account external reference or the account reference (generated by WL).
GET
/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/corporate-contract
Retrieve corporate contract for a card contract by external reference (beta)
The API allows the corporate contract detail of a card contract to be retrieved.
GET
/issuers/{issuerId}/card-contracts/{cardContractReference}/corporate-contract
Retrieve corporate contract for a card contract (beta)
The API allows the contract detail of a corporate card contract to be retrieved.
PATCH
/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-contract-entities/{companyEntityExternalReference}
Modify an entity of a Corporate contract (beta)
The API allows certain data of an existing entity of a corporate contract to be updated such as
- the allowed advertisement channels (flags)
- the allowed delivery channel for possible letters
As a result the corporate contract entity is immediately updated with provided data in our system.
PATCH
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-contract-entities/{companyEntityExternalReference}
Modify an entity of a Corporate contract by external reference (beta)
The API allows certain data of an existing entity of a corporate contract to be updated such as
- the allowed advertisement channels (flags)
- the allowed delivery channel for possible letters
As a result the corporate contract entity is immediately updated with provided data in our system.
GET
/issuers/{issuerId}/corporate-contracts/{contractReference}/contract-owner
Retrieve contract owner for a corporate contract (beta)
This API allows the contract owner for a corporate contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
GET
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/contract-owner
Retrieve contract owner for a corporate contract by external reference (beta)
This API allows the contract owner for a corporate contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
What's Changed
POST
/issuers/{issuerId}/disputes/{disputeFolderReference}/documents
Request body :
- Added property
documentTypeId
(string)
POST
/issuers/{issuerId}/disputes/external-disputes/{issuerDisputeExternalReference}/documents
Request body :
- Added property
documentTypeId
(string)
POST
/issuers/{issuerId}/cards/block-all
Request body :
- Added property
cancelScheduledCardBlocking
(boolean)
POST
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/block
Request body :
- Added property
cancelScheduledCardBlocking
(boolean)
POST
/issuers/{issuerId}/cards/{cardReference}/block
Request body :
- Added property
cancelScheduledCardBlocking
(boolean)
POST
/issuers/{issuerId}/operations/{externalOperationReference}/disputes
Request body :
- Changed property
disputeDocuments
(array)- Changed items (object
CreateDocumentRequest
)- Added property
documentTypeId
(string)
- Added property
- Changed items (object
POST
/issuers/{issuerId}/cards/{cardReference}/create-emergency-card
Response:
- Changed property
data
(objectCreateEmergencyCardResponse
)- Added property
maskedPan
(string)
- Added property
POST
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/create-emergency-card
Response:
- Changed property
data
(objectCreateEmergencyCardResponse
)- Added property
maskedPan
(string)
- Added property
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}
Response:
- Changed property
data
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations/{operationId}
Response:
- Changed property
data
(objectOperation
)- New required properties:
status
- New required properties:
GET
/issuers/{issuerId}/accounts/{accountReference}
Response:
- Changed property
data
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
GET
/issuers/{issuerId}/accounts/{accountReference}/operations/{operationId}
Response:
- Changed property
data
(objectOperation
)- New required properties:
status
- New required properties:
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations
Parameters:
Added: sort
in query
Changed: printOnStatement
in query
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/next/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/{accountReference}/operations
Parameters:
Added: sort
in query
Changed: printOnStatement
in query
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/{accountReference}/statements/last/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/{accountReference}/statements/next/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
GET
/issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}/operations
Response:
- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
POST
/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/block-and-replace
Request body :
- Changed property
blockCardRequest
(objectBlockCardRequest
)- Added property
cancelScheduledCardBlocking
(boolean)
- Added property
POST
/issuers/{issuerId}/cards/search
Request body :
New optional properties:
pan
Added property
panReference
(string)
POST
/issuers/{issuerId}/cards/{cardReference}/block-and-replace
Request body :
- Changed property
blockCardRequest
(objectBlockCardRequest
)- Added property
cancelScheduledCardBlocking
(boolean)
- Added property
GET
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/accounts
Response:
- Changed property
data
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
GET
/issuers/{issuerId}/contracts/{contractReference}/accounts
Response:
- Changed property
data
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
GET
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/accounts
Response:
- Changed property
data
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
GET
/issuers/{issuerId}/customers/{customerReference}/accounts
Response:
- Changed property
data
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
GET
/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/contract
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/accounts/{accountReference}/contract
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/card-contracts/{cardContractReference}/contract
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}
Response:
- Changed property
data
(objectCorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
- Changed property
data
(objectCorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
- Changed property
data
(objectCorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}
Response:
- Changed property
data
(objectCorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
PATCH
/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-contract-entity/{companyEntityExternalReference}
OperationId:
modifyCorporateContractEntity
-> modifyCorporateContractEntityDeprecated
PATCH
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-contract-entity/{companyEntityExternalReference}
OperationId:
modifyCorporateContractEntityByIssuerExtRef
-> modifyCorporateContractEntityByIssuerExtRefDeprecated
POST
/search-operations
Response:
- Changed property
data
(objectApiResponseEntityListOperation
)- Changed property
data
(array)- Changed items (object
Operation
)- New required properties:
status
- New required properties:
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/contracts/{contractReference}
Response:
- Changed property
data
(objectContract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/{contractReference}
Response:
- Changed property
data
(objectCorporateContract
)- Changed property
rootAccount
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
corporateContractEntities
(array)- Changed items (object
CorporateContractEntity
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
corporateEmployeeAccounts
(array)- Changed items (object
CorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}
Response:
- Changed property
data
(objectCorporateContract
)- Changed property
rootAccount
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
corporateContractEntities
(array)- Changed items (object
CorporateContractEntity
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
corporateEmployeeAccounts
(array)- Changed items (object
CorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
POST
/issuers/{issuerId}/contracts/create-consumer-contract
Request body :
- Changed property
addCardsAccounts
(objectCreateConsumerContractRequest.AddCardsAccounts
)- Changed property
accounts
(array)- Changed items (object
CreateConsumerContractRequest.Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
POST
/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/add-cards-accounts
Request body :
- Changed property
accountHierarchy
(objectAddCardsAccountsRequest.AccountHierarchy
)- Changed property
accounts
(array)- Changed items (object
CreateConsumerContractRequest.Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array) - Response:
- Changed property
data
(objectAddCardsAccountsResponse
)- Added property
originalContract
(object) - Added property
changedContract
(object) - Added property
productChangeInformation
(object)
- Added property
- Added property
- Changed items (object
- Changed property
POST
/issuers/{issuerId}/contracts/search
Response:
- Changed property
data
(array)- Changed items (object
Contract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
- Changed items (object
POST
/issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts
Request body :
- Changed property
accountHierarchy
(objectAddCardsAccountsRequest.AccountHierarchy
)- Changed property
accounts
(array)- Changed items (object
CreateConsumerContractRequest.Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array) - Response:
- Changed property
data
(objectAddCardsAccountsResponse
)- Added property
originalContract
(object) - Added property
changedContract
(object) - Added property
productChangeInformation
(object)
- Added property
- Added property
- Changed items (object
- Changed property
GET
/issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts
Response:
- Changed property
data
(array)- Changed items (object
Contract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
- Changed items (object
GET
/issuers/{issuerId}/customers/{customerReference}/contracts
Response:
- Changed property
data
(array)- Changed items (object
Contract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
- Changed items (object
GET
/issuers/{issuerId}/companies/{customerReference}/corporate-contracts
Response:
- Changed property
data
(array)- Changed items (object
CorporateContract
)- Changed property
rootAccount
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
corporateContractEntities
(array)- Changed items (object
CorporateContractEntity
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
corporateEmployeeAccounts
(array)- Changed items (object
CorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
- Changed items (object
GET
/issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/corporate-contracts
Response:
- Changed property
data
(array)- Changed items (object
CorporateContract
)- Changed property
rootAccount
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
corporateContractEntities
(array)- Changed items (object
CorporateContractEntity
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
corporateEmployeeAccounts
(array)- Changed items (object
CorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
- Changed items (object
POST
/search-contracts
Response:
- Changed property
data
(objectApiResponseEntityListContract
)- Changed property
data
(array)- Changed items (object
Contract
)- Changed property
accounts
(array)- Changed items (object
Account
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed items (object
- Changed property
- Changed items (object
- Changed property
POST
/search-corporate-contracts
Response:
- Changed property
data
(array)- Changed items (object
CorporateContract
)- Changed property
rootAccount
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
corporateContractEntities
(array)- Changed items (object
CorporateContractEntity
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
corporateEmployeeAccounts
(array)- Changed items (object
CorporateEmployeeAccount
)- Changed property
account
(objectAccount
)- Added property
externalVelocityLimits
(array) - Added property
externalAuthorizationsRestrictions
(array)
- Added property
- Changed property
- Changed items (object
- Changed property
- Changed items (object
What's Deleted
No API deleted.
What's Deprecated
PATCH
/issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-contract-entity/{companyEntityExternalReference}
Modify an entity of a Corporate contract (beta) - deprecated
The API allows certain data of an existing entity of a corporate contract to be updated such as
- the allowed advertisement channels (flags)
- the allowed delivery channel for possible letters
As a result the corporate contract entity is immediately updated with provided data in our system.
PATCH
/issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-contract-entity/{companyEntityExternalReference}
modify an entity of a Corporate contract by external reference (beta) - deprecated
The API allows certain data of an existing entity of a corporate contract to be updated such as
- the allowed advertisement channels (flags)
- the allowed delivery channel for possible letters
As a result the corporate contract entity is immediately updated with provided data in our system.
Data Export
Data export solution description
The data export solution is a new external Push Service totally independent from the existing scoring notification request, containing a maximum of information of the transaction and the authentication process.
The platform HUB purposes two kinds connectivity with banks for this purpose.
- The data are sent by Webservice to API REST bank Server end-point
or
- The data are sent by file to bank file Server
Data export scheme
The data export solution defined is based on data conveyed in the AReq and RReq messages + Scoring and authentication process.
It takes advantage of the HUB to provide the necessary available data from those messages.
The HUB is the key module to collect and to treat those data as it is the central module involved in the 3DS authentication process.
The messages contain most of the relevant information needed to get the context of a transaction and to provide enough information to consolidate and refine the authorization process.
Workflow of the process:
- The HUB collect data from Areq and Rreq messages.
- The datas are encrypted and sent through messages to the transaction export gateway.
- The data are sent through a specific gateway to the IS bank according to the selected option (batch file or real time).
Real-time push option
With this solution, bank will be able to receive the data just after the authentication transaction ending (after RReq/RRes message).
The data are pushed to bank through a dedicated Webservice API.
The data will be sent on a REST JSON format. The Web Services will be transmitted in HTTPS - TLS 1.2 and will be configured on the Worldline PCI-DSS Proxy as followed:
- By default on internet with a mandatory mutualized authentication
- If asked by the bank, on a VPN or LS
A rate limiter is defined (max TPS) on the HUB push platform and must be configured depending on Issuer Bank transaction volume and IS Bank Server capacity.
If the HUB cannot reach the bank Webservice, a retry process is forecasted. This retry flow is ordered by a FIFO rule.
Two kind of errors are defined, some are due to context and triggers a retry attempt, some are due to data or configuration error and will no triggered any retry. Cf. 3.5.1.2
The retention of data is fixed for a 4 days period. During this time laps the transactions are systematically pushed to the bank until the bank module responds.
After 4 days, the transaction and data not transmitted are deleted from the queue.
Batch file option
With this solution, bank will receive the data through a file.
The file will be generated with a frequency of at least 2 files per day (one per site).
A ‘pull’ or ‘push’ process could be implemented to share the files with IS Bank.
A file system solution will allow Worldline to keep the file during 2 weeks. After this period, the files will be deleted.
The data will be sent on a JSON format through the PCI-DSS gateway on sFTP or PESIT SSL. File could be encrypted in GPG or SMIME.
Data Export WS Client
Referential WS Client
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 Batch
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
DATE | VERSION | TYPE DE UPDATE | REASONS FOR THE UPDATE |
20/03/2017 | AA | Creation | Document creation |
17/08/2017 | AB | Update | Update length |
19/09/2017 | AC | Update | Add CSV and Positional Format |
17/01/2018 | AD | Update | Add missing KeyTag attribute in some XML elements Update some French labels Remove CSV and Positional Format (refers to old specifications) |
26/03/2018 | AE | Update | Add/update xml messages examples |
16/05/2018 | AF | Update | Update length and comments for some fields Add TA Authentication |
01/10/2018 | AG | Update | Add Issuer and SubIssuer at card level |
05/02/2019 | AH | Update | Check rules |
19/02/2019 | AI | Update | Better handling of invalid inputs |
03/01/2020 | AJ | Update | Add skipped use case |
05/10/2020 | AK | Update | Added the DeleteTime attribute in “Card” record and structure. Change email control |
02/12/2020 | AL | Update | Change profil regex |
16/02/2021 | AM | Update | Change field status on card Level Update authentication means list |
06/05/2021 | V21R2 1.0 | Update | Change versioning norm |
29/06/2021 | V21R2 1.1 | Update | Fix typo “deletedTime” |
13/07/2021 | 21R3 1.0 | Update | Update cardholder ID constraints |
18/08/2021 | 21R3 1.1 | Update | Added QMYST example into “AuthentiactionData” |
18/08/2021 | 21R3 1.1 | Update | Added “cardId” attribute in “Card” structure |
10/09/2021 | 21R3 1.2 | Update | AuthenticationDataUpdateMode = Update to delete a credential : definition and example |
05/10/2021 | 22R1 1.0 | Update | Published version with new graphical charter |
24/03/2022 | 22R2 1.0 | Publication | First 22R2 Official version |
23/05/2022 | 22R2 1.1 | Update | Add cardID sample and in structure description |
04/07/2022 | 22R3 1.0 | Publication | First 22R3 Official version Remove DELETED card status |
13/07/2022 | 23R1 1.0 | Update | Fix back “DeleteTime” Fix various format controls |
13/12/2022 | 23R1 1.1 | Update | Complete paragraph “File reject” |
20/01/2023 | 23R2 1.0 | Update | Add optional field effectiveUpdateDate |
30/03/2023 | 23R2 1.0 | Publish | First 23R2 official version |
05/07/2023 | 23R3 1.0 | Publish | First 23R2 official version – no change |
11/09/2023 | 24R1 1.0 | Update | Removed references to QMYST |
23/02/2024 | 24R2 1.0 | Publish | First 24R2 official version – no change |
03/05/2024 | 24R2 1.1 | Update | The batch does not control the field FileNumber. |
14/05/2024 | 24R2 1.2 | Update | UpdateMode can be set by CREATE_OR_UPDATE and not CREATED_OR_UPDATE Add SMS as label in AuthenticationData |
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 »
Name | Mandatory | length | Pattern / Values / Contraints | Comments | |
Header (mandatory 1-1) | Issuer | Y | 5 | N | Issuer Code / Issuer Identifier |
SubIssuer | N | 5 | N | SubIssuer Code / SubIssuer Identifier | |
FileNumber | Y | 6 | N | See specification below | |
Updated | Y | 8 | N (format YYYYMMDD) | Date of generation of the file | |
UpdateMode | Y | - | AN (CREATE_ONLY or CREATE_OR_UPDATE) | CREATE_ONLY: this mode will create only new cards. If card already exists, do nothing.CREATE_OR_UPDATE: create new cards, update existing one | |
CardHolderCount | Y | 1-6 | N (< 999 999) | Number of cardholders records presents in the file |
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 »
Name | Mandatory | Length | Pattern / Values / Contraints | Comments | |||
Cardholder (optional 0-999 999) | IdElement | Yes | 1-6 | N | Counter of cardholder in the file (incremental) | ||
CardCount | Yes | 1-2 | N | Number of cards declared for this cardholder | |||
Identifier | Yes | 1-36 | AN + ‘-‘ | Cardholder identifier | |||
Name | No | 1-50 | A – Clear value | Lastname of the cardholder | |||
- | B64 – encrypted value | ||||||
FirstName | No | 1-50 | A - Clear value | FirstName of the cardholder | |||
- | B64 – encrypted value | ||||||
Language | No | 2 | A - ISO 639-1 | Language | |||
Card (optional 0-X) | IdElement | Yes | 1-2 | N | Counter of card for the current CardHolder (incremental) | ||
PAN | Yes | - | B64 – encrypted value | Card Number (encrypted and base64 or in clear) | |||
16-19 | N – clear value | ||||||
OldPAN | No | - | B64 – encrypted value | Old Card Number (encrypted and base64 or in clear) | |||
16-19 | N – clear value | ||||||
ExpiryDate | No | 24 | B64 – encrypted value | Expiry date (encrypted and base64 or in clear). Clear value must have the following pattern: YYYY-MM | |||
7 | YYYY-MM – clear value | ||||||
ProfilSetName | No | 1-32 | AN + ‘-‘ | Specific profileset to assign to the card instead of bin range profileset | |||
DeleteTime | No | 14 | yyyyMMddHHmmss | Date and time of card deletion. | |||
AuthenticationDataUpdateMode | Yes | - | « UPDATE » or « DELETE_AND_CREATE » | When a card already exists (and UpdateMode is CREATE_OR_UPDATE), specify what to do with AuthenticationData · UPDATE: if AuthenticationData is provided for an authentication mean, replace existing values (if any) with provided one. Other authentication means (not provided in file) will be kept. If AuthenticationData is provided with one specific authentication mean and value = DELETED, the credential will be deleted of all the attached value. · DELETE_AND_CREATE: Existing AuthenticationData (for all authentication means) will be deleted and replaced by provided one. When the card doesn’t exist yet, you can provide any of the two values (result will be the same). | |||
Status | No | 6-9 | A | ACTIVE orINACTIVE. In case of null or invalid value, ACTIVE is chosen by default | |||
Issuer | No | 5 | N | Issuer Code / Issuer Identifier | |||
SubIssuer | No | 5 | N | SubIssuer Code / SubIssuer Identifier | |||
CardId | No | 2-36 | AN + ‘-‘ | Unique Card identifier | |||
EffectiveUpdateDate | No | 14 | yyyyMMddHHmmss | Date used to update user, card and credential. If effectiveUpdate date is superior to cardHolder/card/authenticationData updatedTime field in database, the data will be updated otherwise not. Only work with AuthenticationDataUpdateMode = UPDATE. | |||
AuthenticationData (optional 0-X) | IdElement | Yes | 1-2 | N | Counter of Authentication data for the current Card (incremental) | ||
Label | Yes | 0-20 | AN | Authentication data label | |||
Value | Yes | 1-50 | AN – clear value | Authentication data value (encrypted and base64 or in clear) | |||
B64 – encrypted value | |||||||
Pattern | No | 0-25 | AN + ‘-‘ | NONE, DD/MM/YYYY… | |||
Miscellaneous | No | 0-200 | AN | Future use | |||
CardData (optional 0-1) | RID | No | - | H | Future use | ||
PIX | No | - | H | ||||
DKI | No | 2 | H | ||||
PSN | No | 2 | H | ||||
ATC | No | 4 | H | ||||
AIP | No | 4 | H | ||||
CVN | No | 2 | N | ||||
ExpiryDate | No | ? | ? | ||||
? | B64 – encrypted value | ||||||
Mode | No | - | A |
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
Section | Field | Presence | Controls | Type of reject | Error Label |
Header (Mandatory) | Issuer | Mandatory | 5 digits | File | Issuer is missing Issuer is invalid |
Existing in DB | File | Error on Issuer/Subissuer retrieval | |||
SubIssuer | Optional | 5 digits | File | SubIssuer is invalid | |
Existing in DB | File | Error on Issuer/Subissuer retrieval | |||
FileNumber | Mandatory | 6 digits | File | File number is missing File number is invalid | |
Updated | Mandatory | Date in YYYYMMDD format | File | Updated is missing | |
UpdateMode | Mandatory | Equals to CREATE_ONLY or CREATE_OR_UPDATE | File | Update mode is missing UpdateMode is invalid | |
CardHolderCount | Mandatory | Numeric >0 | File | The number of cardholder is missing The number of cardholder cannot be less than 1 |
3.2. CardHolder
Section | Field | Presence | Controls | Type of reject | Error Label |
CardHolder | IdElement | Mandatory | Numeric >0 | CardHolder | The idElement is missing The idElement must be numeric >0 |
CardCount | Mandatory | Numeric >0 | CardHolder | The cardCount is missing The cardCount must be numeric >0 | |
Identifier | Mandatory | Alphanumeric (and ‘-‘) of length [1;36] | CardHolder | The identifier is missing The length of the identifier must be between 1 and 36 | |
Name | Optional | Alphanumeric of length [0;50] | CardHolder | Name length cannot be more than 50 characters | |
FirstName | Optional | Alphanumeric of length [0;50] | CardHolder | FirstName length cannot be more than 50 characters | |
Language | Optional | Alphabetic of length [2] | CardHolder | Language is invalid |
3.3. Card
Section | Field | Presence | Controls | Type of reject | Error Label |
Card | IdElement | Mandatory | Numeric >0 | CardHolder | The idElement is missing The idElement must be numeric >0 |
PAN | Mandatory | Numeric of length [16;19] | CardHolder | PAN is invalid | |
OldPan | Optional | Numeric of length [16;19] | CardHolder | Old PAN is invalid | |
Existing in DB | CardHolder | Can't replace Card because old card doesn't exist with given PAN! | |||
ExpiryDate | Optional | Format YYYY-MM | CardHolder | ExpiryDate is invalid | |
ProfilSetName | Optional | Alphanumeric (and ‘-‘) of length [1;32] | CardHolder | The profilSetName is invalid | |
AuthenticationDataUpdateMode | Mandatory | Equals to UPDATE or DELETE_AND_CREATE | CardHolder | The authentication data update mode is missing The authentication data update mode is invalid | |
Issuer | Optional | 5 digits | CardHolder | Issuer is invalid | |
Existing in DB | CardHolder | Error on Issuer/Subissuer retrieval | |||
SubIssuer | Optional | 5 digits | CardHolder | SubIssuer is invalid | |
Existing in DB | CardHolder | Error on Issuer/Subissuer retrieval | |||
Status | Optional | - | - | - | |
CardId | Optional | Alphanumeric (and ‘-‘) of length [2;36] | CardHolder | The length of the card identifier must be between 2 and 36 | |
DeleteTime | Optional | yyyyMMddHHmmss | CardHolder | - | |
EffectiveUpdateDate | Optional | yyyyMMddHHmmss | CardHolder | - |
3.4. AuthenticationData
Section | Field | Presence | Controls | Type of reject | Error Label |
AuthenticationData | IdElement | Mandatory | Numeric >0 | CardHolder | The idElement is missing The idElement must be numeric >0 |
Label | Mandatory | Alphanumeric (and ‘-‘) of length [0;20] | CardHolder | The authentication label is missing The authentication label is invalid | |
Equals to SMS, PHONE, EMAIL, PWD, SSN, TOKEN, PAM, DDN, … | AuthenticationData | An unknow authentication mean ([LABEL]) appears in the file (once or more). It will be ignored. | |||
Pattern | Optional | Alphanumeric (and ‘-‘) of length [0;25] | CardHolder | The pattern is invalid | |
Value | Mandatory | PHONE, SMS, SVI: has phone number format (according to the Google API PhoneNumberUtil) EMAIL: corresponds to regular expression: ^(\w[-.\w]*)@([-\w]+(?:\.[-\w]+)*)\.([A-Za-z]{2,20})$ CCP: corresponds to regular expression: ^[A-Za-z0-9]{11}$ | CardHolder | Authentication value format isn't correct The value is missing The pattern is invalid |
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
Card Referential
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.
General Terms
General Terms
1. Terminology
Here below you will find the acronyms used and their meanings:
Acronym/Common Name | Meaning |
---|---|
AC / CA | Certification Authority |
ADS | 3D Secure service use case |
AES | Advanced Encryption Standard |
API | Application Programming Interface |
APM | Authentication Process Management |
CAP | Chip Authentication Program |
GCM | Galois/Counter Mode |
CH | Card Holder |
CR | Central Repository |
GZip | GZip is a compressed file format base on the deflate algorithm. Please refer to RFC 1952 for more information |
HTTPS | HyperText Transfer Protocol Secure |
ITA | Identity, Trust and Authentication |
JSON | JavaScript Object Notation |
OOB | Out Of Band |
OTP | One Time Password |
OTRC | One Time Registration Code |
PAN | Primary Account Number |
PCI | Payment Card Industry |
REST | reStructuredText |
UCR | Unconnected Card Reader |
URL | A Uniform Resource Locator (also known as web address, particularly when used with HTTP), is a specific character string that constitutes a reference to a resource. Please refer to RFC 3986 for more information. |
UUID | Universally Unique Identifier. Please refer to RFC 4122 for more information. |
REINIT | 3D Secure service use case |
WL | Worldline |
2. Overview
ITA Sec Authentication Hub exposes a unified API for host-to-host communications.
The methods are exposed through a RESTful API built on HTTP and JSON.
As per the REST principles:
- All the methods are accessed by performing an HTTP request to the web service endpoint,
- URL are used to access the data
- HTTP bodies carry the representation of the business objects (elements),
- HTTP verbs are used to indicate the action to perform :
- POST: create a new element for which no identifier is known
- PUT: update an element, or create a resource for which the identifier is known in advance
- GET: retrieve one or more elements
- DELETE: delete an element
3. Versioning
From version 2019R2.0, the version number has been included in the service URI. By default, when the version is not provided in the URI, the version 2019R1.0 implementation is used.
Version URI parameter | Version used |
none | 2019R1.0 |
2019R1-1.0 | 2019R1.0 |
2019R2-1.0 | 2019R2.0 |
2021R1-1.0 | 2021R1.0 |
2021R2-1.0 | 2021R2.0 |
2021R3-1.0 | 2021R3.0 |
2022R1-1.0 | 2022R1.0 |
2023R1-1.0 | 2023R1.0 |
2023R2-1.0 | 2023R2.0 |
Examples of URI :
/referential/rest/2019R2-1.0/public/updateCardWithCredentials/669c8c64-e71f-4e87-8966-cb578a86074e
/referential/rest/2021R1-1.0/public/updateCardWithCredentials/3aaa4686-d139-4822-b193-6a0140467264
4. Connectivity
4.1. Network
All the services are exposed through the HTTPS protocol (RFC 2818) TLS 1. 2.
No HTTP compression (RFC 2616) is activated.
4.2. Security
In order to secure the communication channel between the bank and authentication HUB, the mutual authentication is recommended.
SSL Client
Authentication Hub will provide a Certificate Request based on Bank recommendation.
Bank must sign the certificate with AC of its choice.
The certificate file must comply with the PKCS10 format and be base-64 encoded.
4.3. IP Filtering
In case of IP filtering on server side firewalls, the IP address of EWL for incoming requests are provided below:
ACS3 | ||||
DEV/IAT | 160.92.7.69 | 160.92.7.70 | 160.92.184.192 | 160.92.184.193 |
CAT | 160.92.184.192 | 160.92.184.193 | 160.92.186.211 | 160.92.128.189 |
PROD | 160.92.186.93 | 160.92.152.3 | 160.92.119.160 | 160.92.135.97 |
5. Interfaces
5.1. Format
The data exchanged is serialized using
- JSON format (RFC 7159).
The character set supported for input and output data is UTF-8 (RFC 3629).
5.2. Common headers (for WS Client)
5.2.1. Hypermedia
Hypermedia is used to specify content type and charset to be used.
Currently supported values are:
- Content type: json
- Charset: UTF-8
Accept | |
Description | Header to ensure acceptance of a JSON UTF-8 response compatible with target version of the API |
Mandatory | Yes |
Format | application/json |
Example | application/json |
Table 1 - Hypermedia input header
Content-Type | |
Description | Header that denotes the API version, content type and charset of the response. |
Mandatory | Yes |
Format | application/json |
Example | application/json |
Table 2 - Hypermedia output header
5.2.2. Oauth 2.0
API could be secure by using Oauth 2.0 protocol. All API requests using Oauth 2.0 must contain at least the following headers: Date, Digest and Authorization.
In order to verify that the message was not tampered with during transit, a signature is also requested.
Two types of signature can be implemented :
- HTTP signature, in this case, API requires a "Signature" header to be supplied
- JWS signature, in this case, API requires an "X-JWS-Signature" header.
Date | |
Description | The "Date" header field represents the date and time at which the message was originated |
Mandatory | Yes |
Format | The expected format is a fixed-length and single-zone subset of the date and time specification used by the Internet Message Format in GMT |
Example | Wed, 25 Oct 2023 13:00:05 GMT |
Digest | |
Description | The "Digest" header is used to verify the integrity of the message body exchanged between Client and Server platforms. |
Mandatory | Yes |
Format | The digest is done by calculating the SHA-256 hash of the payload of the message and Base64 encoding the hash. The digest is prefixed by string “SHA-256=”. |
Example | SHA-256=8HAW5Ig3X/RCOG840pFdji5JnPGNa4i32lsilUt3qK4= |
Authorization | |
Description | Field used for request authorization on the OAuth2 side. It contains the bearer token ; A security token with the property that any party in possession of the token (a "bearer") can use the token in any way that any other party in possession of it can. The access token is returned in response of /oauth2/token endpoint |
Mandatory | Yes |
Format | String of alphanumeric characters, up to 2048 “Bearer ” + access token value |
Example | Bearer eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiZGlyIn0..yQGpzEpF3OT1y_QZUzL2Ag.mLiSvEZE ] |
5.2.2.1. HTTP signature
Signature | |
Description | The signature header requires the 4 following parameters to be supplied: - keyId - The client ID of HUB platform defined during the Oauth 2.0 project, - algorithm - The algorithm can be 'rsa-sha256', - headers - The list of the headers that will be included in the signature, currently the headers required are '(request-target) date digest', - signature - The calculated signature of the header values, using the chosen algorithm (eg. rsa-sha256). |
Mandatory | Yes for HTTP Signature |
Format | String of alphanumeric characters |
Example | keyId=\"e77d776b-90af-4684-bebc-521e5b2614dd\",algorithm=\"rsa-sha256\",headers=\"(request-target) date digest\",signature= ] |
5.2.2.2. JWS signature
X-JWS-Signature | |
Description | JWS Signature is composed of [protected header].[payload].[signature value] where : - protected header encoded in B64 - payload is empty - Signature is the B64 encoded result of Signature of JWS B64 encoded header concatenate with HTTP header String |
Mandatory | Yes for JWS signature |
Format | String of alphanumeric characters |
Example | Cf. description below |
The JWS structure shall be carried in HTTP header field named "x-jws-signature".
A JWS protected header parameter is composed of parameters :
- "b64” ; the JWS header shall include b64 header parameter set to false
- “x5t#S256” is the digest (fingerprint) of the X.509 signing certificate using SHA 256. "x5t#S256" shall be checked against the certificate used to validate the signature
- crit:["sigT","sigD","b64"] - Non-standard JWS header parameters (ie. not defined in RFC 7515), which are critical
- "sigT" shall be present and set to the time that the signature was created. The time shall be indicated in UTC (ending in "Z") and shall indicate date and time to the second.
- "sigD" header parameter shall be present and shall contain :
- “mId" set to http://uri.etsi.org/19182/HttpHeaders
- "pars" should include the following HTTP Header field names:
- "(request-target)" for HTTP Requests
- "Content-Type"
- “Digest” enables protection of the HTTP Body
- "alg" identifies the cryptographic algorithm used to create the JWS Signature Value. Use RS256
Example of protected header
{ "b64":false, "x5t#S256":"dytPpSkJYzhTdPXSWP7jhXgG4kCOWIWGiesdzkvNLzY", "crit":[ "sigT", "sigD", "b64" ], "sigT":"2023-11-26T11:26:57Z", "sigD":{ "pars":[ "(request-target)", "content-type", "digest" ], "mId":"http://uri.etsi.org/19182/HttpHeaders" }, "alg":"RS256" }
Example of protected header encoded in B64 (without line breaks or extra spaces)
eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2O
jU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ
A HTTP header parameter
- request-target :
- digest :
- content-type : application/json
Example of HTTP header
(request-target): post /initiateAuthentication content-type: application/json digest: SHA-256=+xeh7JAayYPh8K13UnQCBBcniZzsyat+KDiuy8aZYdI=
Where digest is the hash in SHA-256 of request body
All the header parameters contained in JWS Protected Header are protected by the signature.
The data must be signed with the private key (associated with the certificate identified in "x5t#S256") by using the chosen algorithm (specified in “alg” parameter).
Data to sign is the concatenation of protected header encoded in B64 and HTTP Header separated by “.”
Example of input Data for Signature
eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ.(request-target): post /initiateAuthentication
content-type: application/json
digest: SHA-256=+xeh7JAayYPh8K13UnQCBBcniZzsyat+KDiuy8aZYdI=
Example of Signed Data
Q9ZSYXJ0QWSoPBfBUR58Sqplw7BQcrcqVR6rvnqfBOvosbBLcsBjkjzi1kCF 2cJsHTJRtp6GcJmZplqRg-7_QBKQAgkUq0BGQpzZwhVYrvP0opdLEarVBrej YA05gt3qnleuS53DWmyZu9iNxhwJTYVPyXediwo3TIlSn-8XjSTZAVHa728E WK6XzRC9rEroXYPYd23iQLXetMygLaDhRT2lGhV5WvmO0wC0B6RbGiYl2zIv D0XliMP6MidX4SDY5zlzyWyFlHqX7eHpkH8xxqAsBdKb16y4IdOoRhil9yws vlzkG6-U9jmBU4y_m3mZArD22oRVXTywzFn9NUtY9w
X-JWS-Signature is the concatenation of protected header encoded in B64 and Signature value separated by “..”
Example of JWS Signature
eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ..Q9ZSYXJ0QWSoPBfBUR58Sqplw7BQcrcqVR6rvnqfBOvosbBLcsBjkjzi1kCF 2cJsHTJRtp6GcJmZplqRg-7_QBKQAgkUq0BGQpzZwhVYrvP0opdLEarVBrej YA05gt3qnleuS53DWmyZu9iNxhwJTYVPyXediwo3TIlSn-8XjSTZAVHa728E WK6XzRC9rEroXYPYd23iQLXetMygLaDhRT2lGhV5WvmO0wC0B6RbGiYl2zIv D0XliMP6MidX4SDY5zlzyWyFlHqX7eHpkH8xxqAsBdKb16y4IdOoRhil9yws vlzkG6-U9jmBU4y_m3mZArD22oRVXTywzFn9NUtY9w
5.2. Common headers (for WS Client)
5.3. Common headers (for WS Server)
5.3.1. Common headers request
Accept | |
Description | Header to ensure acceptance of a JSON UTF-8 response compatible with target version of the API |
Mandatory | Yes |
Format | ^application/json; *charset=UTF-8$ |
Example | application/json; charset=UTF-8 |
Content-Type | |
Description | Header that denotes the API version, content type and charset of the response. |
Mandatory | Yes |
Format | ^application/json; *charset=UTF-8$ |
Example | application/json; charset=UTF-8 |
Request-Identifier | |
Description | Unique identifier (UUID) of the request. Field “requestId”. Used to correlate logs between Authentication HUB and the client. Important note : as part of a protection against requests replay providing the same identifier twice within a short time range will result in the server refusing the request |
Mandatory | Yes |
Format | String of 36 characters, standard representation of a UUID ( {time_low}-{time_mid}-{time_high_and_version}-{variant_and_sequence}-{node} ) |
Example | 38400000-8cf0-11bd-b23e-10b96e4ef00e |
Request-Date | |
Description | UTC datetime at which the request has been issued. String of characters complying with the ISO 8601 datetime format |
Mandatory | Yes |
Format | YYYY-MM-DDThh:mm:ss |
Example | 2015-07-02T20:07:59 |
5.3.2. Common headers response
Date | |
Description | Date contains the date and time at which the message was generated |
Mandatory | Yes |
Format | day-name, day month year hour:minute:second GMT |
Example | Fri, 17 Sep 2021 09:34:19 GMT |
Content-Type | |
Description | Header that denotes content type of the response. |
Mandatory | Yes |
Format | application/json |
Example | application/json |
Content-Length | |
Description | Content-Length indicate the size of entity-body in decimal no of octets. |
Mandatory | Yes |
Format | decimal |
Example | 393 |
5.4. Api-Key
A parameter, called “Api-Key” is automatically added in the requests by the HUB Applicative Firewall. This value contains the certificate CN provided by Client during mutual authentication process.
This field must not set or define in the API; it’s an internal field.
5.5. Encryption
Some fields, corresponding to sensitive data, can be either encrypted or plain. In this case, there is a type, a value and a key tag attribute.
When the type is encrypted, the value attribute is a String, before encryption and after being decrypted. The encrypted result is in Hexadecimal format compliant with JSON structure. That’s why this field doesn’t need to be parsed into JSON object.
Only for plain formats, the value needs to be casted to as JSON object. As a result, all the double quotes characters need to be escaped by a backslash, resulting to the following format: "\"PWD\": {\"pwd\":\"@value\"}".
When sensitive fields are encrypted, a “keyTag” value is requested to identify the key used. The “keyTag” value must be defined per field. Same keytag value could be used for all data.
5.5.1. Encryption
Sensitive data will be encrypted with AES256bits (RFC 3565) encryption in CBC or GCM mode with an initial vector either filled with 0 (in case parameter initializationVector is not filled or at “false”) or with the requestId without “-“ character. The data to encrypt will be padded using PKC7 padding.
The encrypted field is always exchanged in Hexadecimal format.
5.5.2. Samples
Key
XOR1: B3EE911BA049ADBEE36B0445C8FC8A2832E7646316F111BCFA3EE062B0379E23
CCV1: BF36D7
XOR2: 50A813F0A59FFADDFEFE06904A4E4E42DF30026CE63FECEEAB92043C667FBC0C
CCV2: DA684A
Clear key: E34682EB05D657631D9502D582B2C46AEDD7660FF0CEFD5251ACE45ED648222F
KCV: 84A0D9
Encryption (CBC)
IV: 00000000000000000000000000000000
Data to encrypt (Clear PAN): 4263540111825682
Data encrypted – in hexadecimal: 11A18541F9C9E748F62186292BC2DB48BF407F2B049390FBE1037D00AF5FACDA
IV: 384000008CF011BDB23E10B96E4EF00E
Data to encrypt (Clear PAN): 4263540111825682
Data encrypted – in hexadecimal: 13FA6DE3AA4C939865D5095A14BE22E95E94C9933EA20F32369423270282EC97
Encryption (GCM)
IV: 00000000000000000000000000000000
Data to encrypt (Clear PAN): 4263540111825682
Data encrypted – in hexadecimal: 68e94ab51334a794c10ebdb76b7480cebb740d8d655396cf7626b1177ad9a78f
IV: 384000008CF011BDB23E10B96E4EF00E
Data to encrypt (Clear PAN): 4263540111825682
Data encrypted – in hexadecimal: 0ead51b9582223c003fcf13195fd3c83d39c2f8cb6a6000dfcc758401fb5e7ea
5.6. Response code
5.6.1. HTTP codes
HTTP codes are used as a first level of information as to know whether a request has been properly handled or not. The caller must consider these codes in compliance with the HTTP specification.
HTTP codes used:
Code | Description |
200 | OK (success) |
201 | CREATED (new url) |
202 | ACCEPTED |
204 | No Content (success) |
400 | BAD REQUEST (format error) |
403 | FORBIDDEN (failure) |
404 | NOT FOUND |
500 | INTERNAL SERVER ERROR |
504 | TIMEOUT |
520 | Web server is returning an unknown error |
5.6.2. Error body
Whenever a business management exception occurs, in addition to the HTTP code, an error representation is returned into the body in addition of the nominal content. To ensure confidentiality, only a detailed code is returned (9 digits). This code is to be matched against the dedicated documentation to be interpreted. In the event of an unexpected error, no code is provided. The error content structure is defined below.
Body Attribute | Possible values |
errorCode | 9-digits code |
The body of error message contains additional optional attributes which are only provided in order to facilitate analyzing in case of issue.
Attribute | Possible values | Format | ||
Error Body | service | C | Service provided in request | String of 1 to 255 characters |
issuerCode | C | Issuer Code provided in request | String of 5 characters | |
subIssuerCode | C | Sub issuer code provided in request | String of 5 characters | |
requestId | C | Request Identifier provided in request | UUID | |
errorCode | M | Error Code | 9-digits code | |
origin | O | For logging and analyzing | ||
message | O | For logging and analyzing | ||
originVersion | O | For logging and analyzing | ||
originHost | O | For logging and analyzing | ||
contextTemporary | O | For logging and analyzing | ||
principal | O | For logging and analyzing |
Sample of error response
{ "issuerCode": "00006", "subIssuerCode": "00006", "requestId": "b8b1d1ae-3b65-48a2-b331-9607ab295412", "service": "ACS_U5G", "errorCode": "404030000", "origin": "REFERENTIAL", "message": "com.wl.gbl.ah.utils.services.exception.AuthenticationHUBExceptionV2: Card not found", "originVersion": "21R1.5-P-37", "originHost": "tqahx002v", "contextTemporary": {} }