Referential WS Client
Current version 25R2-1.0 of September 4th 2025
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.
1. End points
1.1. echo
Echo function to test the availability of the WS.
Example
Input :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"principal": {
"type": "encryptedPan",
"value": "11A18541F9C9E748F62186292BC2DB48BF407F2B049390FBE1037D00AF5FACDA"
},
"expiry": {
"type": "encrypted",
"value": "8BF407F2B049390FBE1037D00AF5FACDA"
}
},
"footer": {}
}
Output :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"timestamp ": "2016-11-16 06:43:19.77"
},
"footer": {}
}
1.2. getCardWithCredentials
This function will be used to get a card with its credentials.
Example
Input :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"principal": {
"type": "encryptedPan",
"value": "11A18541F9C9E748F62186292BC2DB48BF407F2B049390FBE1037D00AF5FACDA"
},
"expiry": {
"type": "encrypted",
"value": "8BF407F2B049390FBE1037D00AF5FACDA"
}
},
"footer": {}
}
Output - success :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"credentials": {
"type": "plain",
"value": "{\"METHOD:PWD\":[{\"value\":\"f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9\",\"algorithm\":\"SHA-256\"}]
}"
},
"cardholderId": "00000003 ",
"cardId": "00000004",
"language": "en"
},
"footer": {}
}
Output - error :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"errorCode":"40401"
},
"footer": {}
}
1.3. updateCardCredentials
This function will be used to update a card with its credentials. In case of success, the server should only return success code HTTP 200. In case of error, no retry will be triggered on client side.
Example
Input - update data :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"principal": {
"type": "encryptedPan",
"value": "11A18541F9C9E748F62186292BC2DB48BF407F2B049390FBE1037D00AF5FACDA"
},
"expiry": {
"type": "encrypted",
"value": "8BF407F2B049390FBE1037D00AF5FACDA"
},
"credentials": {
"type": "plain",
"value": "{\"METHOD:PWD\":[{\"value\":\"f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9\",\"algorithm\":\"SHA-256\"}]}"
}
},
"footer": {}
}
Input - reset/delete data :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"principal": {
"type": "encryptedPan",
"value": "11A18541F9C9E748F62186292BC2DB48BF407F2B049390FBE1037D00AF5FACDA"
},
"expiry": {
"type": "encrypted",
"value": "8BF407F2B049390FBE1037D00AF5FACDA"
},
"credentials": {
"type": "plain",
"value": "{\"METHOD:PWD\":\"\"}"
}
},
"footer": {}
}
Output - success :
HTTP 200
Output - error :
{
"header": {
"issuerCode": "12345",
"subIssuerCode": "12345",
"service": "ACS_U1X",
"requestId": "5945b448-1fcf-41ad-9a1c-39bb16af4606",
"keyTag": "02"
},
"body": {
"errorCode": "40014"
},
"footer": {}
}
2. Credentials
The credential field have the following format
METHOD:@METHOD
value:@value, algorithm :@algorithm
algorithm is optional and provided only if the data is hashed.
In updateCardCredentials, if no value is provided then the action on server side should be delete or reset.
Kinds of credential currently available are:
- SMS (mobile phone)
- IVR (landline phone)
- SSN
- TA (Trusted Authentication on Mobile)
- PWD
- TOKEN
- OTRC
- USERCODE
- OPENID – Dedicated cardholder identifier for OpenID authentication method
Notes that 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.
Examples:
"METHOD:SMS": [{
"value": "+1234567890"
}]
"METHOD:IVR": [{
"value": "+1234567890"
}]
"METHOD:EMAIL": [{
"value": "user@email.com"
}]
"METHOD:SSN": [{
"value": "123456789012345"
}]
"METHOD:PWD": [{
"value": "f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9",
"algorithm": "SHA-256"
}]
"METHOD:PWD": [{
"value": "MyS3cr37P@55w0rd"
}]
"METHOD:OTRC": [{
"value": "MyS3cr3707RC"
}]
"METHOD:OTRC": ""
"METHOD:TA": [{
"value": "MyTAUserId"
}]
"METHOD:USERCODE":[{
"value":"123123123"
