API technical configuration
API technical configuration
1. Overview
WL ACS platform exposes unified APIs for host-to-host communications.
The methods are exposed through a RESTful API built on HTTP and JSON.
The data exchanged is serialized using JSON format (RFC 7159).
The character set supported for input and output data is UTF-8 (RFC 3629).
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
HTTP headers are used to carry information related to the API protocol: authentication, pagination, API versioning…
All the services are exposed through the HTTPS protocol (RFC 2818) TLS 1. 2.
No HTTP compression (RFC 2616) is activated.
In order to secure the communication channel between the bank and WL ACS platform, a mutual authentication mTLS is required.
In addition, an Ouath 2.0 security channel could be implemented for Client APIs.
2. API Server
2.1. Security
In order to secure the communication channel between the bank and WL ACS platform, a mutual authentication mTLS is required.
Clients must provide a mutual authentication (client) certificate that complies with the following rules.
2.1.1. Testing environment
The certificate file must comply with the PKCS10 format and be base-64 encoded.
Important note: the use of ‘&’ and ‘<’ characters in the certificate fields is prohibited.
Field | Description |
Validity | 2 or 3 years |
Key length | 2048 |
Key type | RSA SHA-256 |
Common Name (CN) | Your API-Key must be provided here. |
Organizational Unit (OU) | Free content |
Organizational Name (O) | Free content |
Country (C) | Country of the requestor (ISO 3166 2 format) |
State (ST) | State (should not be abbreviated) |
Locality (L) | Locality |
Email address | An email address to contact the organization. Usually the email address of the certificate administrator or IT department |
2.1.2 Production
Important note: the use of ‘&’ and ‘<’ characters in the certificate fields is prohibited.
Field | Description |
Validity | 2 or 3 years |
Key length | 2048 |
Key type | RSA SHA-256 |
Common Name (CN) | Your API-Key must be provided here. |
Organizational Unit (OU) | Free content |
Organizational Name (O) | Free content |
Country (C) | Country of the requestor (ISO 3166 2 format) |
State (ST) | State (should not be abbreviated) |
Locality (L) | Locality |
Email address | An email address to contact the organization. Usually the email address of the certificate administrator or IT department |
2.2 Versioning
For WL Server APIs, the version number has been included in the service URI.
By default, when the version is not provided in the URI, the initial 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 |
2023R3-1.0 | 2023R3.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
2.3 Message format
2.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 |
2.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 |
3. API Client
3.1. Security
In order to secure the communication channel between the bank and WL ACS platform, a mutual authentication mTLS is recommended.
In replacement or addition to mTLS, an Oauth 2.0 authentication could be used (cf. paragraph 5)
For mTLS,
Client certificate :
WL 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.
Server certificate:
Bank must provide SSL certificates (root/ac) used to sign the URL name of the API.
3.2 Versioning
Client APIs can be modified during major product releases.
However, to avoid server-side impacts, changes are limited to the addition of optional supplementary fields.
Additionally, APIs are versioned and configurable by the bank, so upgrading to a new version is not mandatory. The new fields will only be transmitted starting from the version in which they are implemented (see the "since release" label in the Swagger file).
A bank wishing to have the latest version of the API must thus request it from their WL contact; by default, no API changes will be made without an explicit request.
3.3 Message Format
3.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
3.4. Signature
Signature is currently only available for Authentication and Credential API.
3.4.1. Signature content
The signature fields are optional and are only filled and/or checked if explicitly required.Otherwise, signature values will be ignored in responses and left empty in requests. Signatures can be activated for each issuer, sub-issuer individually and at a method level.
To pass validation, the signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant. As such a typical signature should look like this [header]..[signature] where:
- [header] : a Base64 URL encoding of the JOSE header which contains the key ID, algorithm and object type. For example: eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ which in clear JSON gives: {"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}. The "kid" (Key ID) and "alg" header fields are both required to perform the check. An additional "jku" parameter in which a JWKS URL where to retrieve the public key can also be specified, if not it should be expected for public keys to have been exchanged beforehand. The "typ" is only there by convention and should only be set as JOSE or JOSE+JSON since were are not dealing JWT (tokens) here.
- [signature] : a Base64 URL encoded value representation of the signature output. The payload used to generate the signature consists of the JSON serialization of the whole object, excluding old signatures and null values, which is then Base 64 URL encoded as well.
If the signature from the response contains a payload value then it will be ignored in favor to the actual object.
3.4.2. Supported algorithm
Currently supported algorithms are RS256, RS384, RS512, ES256, ES256K, ES384, and ES512.
3.4.3. Samples
{
"header": {
"issuerCode": "123456",
"subIssuerCode": "987654",
"service": "ACS_TEST",
"requestId": "5850e990-a21e-4925-8483-a407ef609e30",
"keyTag": "01"
},"body": "Hello",
"signature": "eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ..QslvRsAf7favTzmZACC6l1UbjySjezKwCIJ0T-qxWkla0GjACsp-5TzannnBoTYzpZfa9BasNVRe1UZyTKEF8ViQX_LL_XnMoDttzB15zCoKkLhgcTOqSmrUa2p_hPOTnmL40TAnlykqNA0MlOQ9nox3K7a-rlfAG4FVXypyaHN71rCBfMQiw5eY-57e3DEdcjDAIWMxKh2zaM4HZ43K2fc1DQHGB-k9aTljOZAEhe6D7dgTYV0EGAHzRw51x15xnPD7_z-sJGpun9iVZpf8fHu9dTn5lhMChQvEBqElxWpm6fET7Izm8hqMa1oUkf2l5ue9h-WotzIbzE4PQuLOxw"
}3. Data 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.
3.1. Encryption
Sensitive data will be encrypted with AES256bits (RFC 3565) encryption in GCM mode with an random initial vector or set with the requestId (without “-“ character).
Notes that usage of CBC mode and IV =0 is deprecated for security reason.
The encrypted field is always exchanged in Hexadecimal format.
The main steps are:
- Depending on config, IV is either the session ID without dashes, a random value,
or null (only zeros); - IV is truncated to the algorithm's corresponding IV length (12 bytes / 24 hex char);
- IV's chars are converted from hex to bytes array;
- data is converted to bytes array, using UTF-8 char-set;
- data is encrypted using the key, the IV and the algorithm ("AES256GCM_NOPADD") corresponding to the configured key;
- encrypted data is converted from bytes array to an hex string.
Whatever the implementation, it must be able to produce the same result depending on algo, key and IV chosen.
3.2. Samples
Key
XOR1: B3EE911BA049ADBEE36B0445C8FC8A2832E7646316F111BCFA3EE062B0379E23
CCV1: BF36D7
XOR2: 50A813F0A59FFADDFEFE06904A4E4E42DF30026CE63FECEEAB92043C667FBC0C
CCV2: DA684A
Clear key: E34682EB05D657631D9502D582B2C46AEDD7660FF0CEFD5251ACE45ED648222F
KCV: 84A0D9
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
Encryption (GCM)
IV: 384000008CF011BDB23E10B96E4EF00E
Data to encrypt (Clear PAN): 4263540111825682
Data encrypted – in hexadecimal: b045162d84b792ee2c89e098d05369defa09bd5eaea899058c8f83da3395f663 (value and tag concatenated)
Decryption: "b045162d84b792ee2c89e098d05369de" and tag "fa09bd5eaea899058c8f83da3395f663" → "4263540111825682"
