Current version 25R2-1.0 of September 4th 2025

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.

1. End points

    1.1.  updateCardWithCredentials

POST ~/referential/rest/{version}/public/updateCardWithCredentials/{requestId}

This function will be used to create or update a card with its credentials.

Examples

• Request to manage cards

Input : 

{
"cards":[
       { "id":"1",
         "principal": { "type": "pan", "value": "4000000000000002"},
         "expiry": {	"type": "plain", "value": "2023-06"}
       },
       { "id":"2",
         "principal":{ "type": "pan", "value": "8139986370259068"},
         "expiry": { "type": "plain", "value": "2020-12" }
       }
       ],
"service": "ACS_U9F",
"issuerCode": "66666",
"subIssuerCode": "66666",
"status": "ACTIVE",
"deletedTime":"2022-12-23T09:45:35",
“firstName”:“John”,
“lastName”:”Dow”,
"language": "fr",
"credentialsUpdateMode": "DELETE_AND_CREATE",
"credentials": {
                "type": "plain",
                "value":{\"METHOD:SMS\":[{\"sms\":\"+491741234567\"}],\"METHOD:DDN\":[{\"ddn\":\"19810803\",\"ddnPattern\":\"AAAAMMJJ\"}]}"
               }
}

Output :

{
    "cardResponses": [
        {
            "id": "1",
            "cardHolderId": "1e8a227f-f34a-4b1f-84d0-32fe5a1eb8d5",
            "tokenPan": "mckei58l0k504lpp",
            "language": "en"
        },
        {
            "id": "2",
            "cardHolderId": "ef9a45e1-2399-4af4-89e4-37011ab3a50b",
            "tokenPan": "mck3a8l5947lecip",
            "language": "en"
        }
    ]
}

• Request to manage cards

Input : 

{
"cards":[
       { "id":"1",
         "principal": { "type": "pan", "value": "4000000000000002"},
         "expiry": {	"type": "plain", "value": "2023-06"}
       },
       { "id":"2",
         "principal":{ "type": "pan", "value": "8139986370259068"},
         "expiry": { "type": "plain", "value": "2020-12" }
       }
       ],
"service": "HUB_NRT",
"issuerCode": "66666",
"subIssuerCode": "66666",
"status": "ACTIVE",
"deletedTime":"2022-12-23T09:45:35",
“firstName”:“John”,
“lastName”:”Dow”,
"language": "fr",
"credentialsUpdateMode": "DELETE_AND_CREATE",
"credentials": {
                "type": "plain",
                "value": "{\"METHOD:EMAIL\":[{\"email\":\"{{email_address}}\"}]}"
               }
}

Output :

{
    "cardResponses": [
        {
            "id": "1",
            “cardId”:  "30a93d15-c8f0-4bee-848e-b029c3e6c8e1",
            "cardHolderId": "81453cf5-afce-4d38-8fec-4bcfc21a7cf3",
            "tokenPan": "mckODEzOTk4NjM3MDI1OTA2OA==",
            "language": "fr"
        },
        {
            "id": "2",
            “cardId”: "bdfe9373-5908-4856-86b1-edc1a4697cb0"
            "cardHolderId": "01821c69-ebac-44e2-b963-0abe6f6b1b5a",
            "tokenPan": "mckODEzOTk4NjM3MDI1OTA2OA==",
            "language": "fr"
        }
    ]
}

• Request to manage cards after adding new format of credentialList    

Input : 

{
    "service": "{{service}}",
    "issuerCode": "{{issuerCode}}",
    "subIssuerCode": "{{subIssuerCode}}",
    "cards": [
        {
            "id": "1",
            "principal": {
                "type": "pan",
                "value": "{{pan}}"
            },
            "expiry": {
                "type": "plain",
                "value": "2023-10"
            }
        }
    ],
    "credentialList": [
        {
            "type": "SMS",
            "value": "+37477445464"
        },
        {
            "type": "EMAIL",
            "value": "tigranyan.argishti@gmail.com"
        }
    ],
    "effectiveUpdateDate": "2024-01-16T13:23:55",
    "credentialsUpdateMode": "DELETE_AND_CREATE"
}

Output :

{
    "cardResponses": [
        {
            "id": "1",
            "cardId": "48c4f206-149a-4d3e-a04d-b0e3c729c92b",
            "cardHolderId": "38c83f83-9460-4a13-a7c8-41913d6a0462",
            "tokenPan": "mckNDk3NjcwMDAwMDAwMDAxNQ=="
        }
    ]
}

• Request to delete card credentials    

Input : 

{
    "service": "HUB_NRT",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "cards": [
        {
            "id": "GUID",
            "principal": {
                "type": "pan",
                "value": "4532953162392327"
            },
            "expiry": {
                "type": "plain",
                "value": "2024-03"
            },
            "cardHolderId": "ef9a45e1-2399-4af4-89e4-37011ab3a50b"
        }
    ],
    "credentials": {
        "type": "plain",
        "value": "{\"METHOD:SMS\":[{\"sms\":\"DELETE\"}]}"
    },
    "credentialsUpdateMode": "DELETE"
}

    1.2. searchCard

POST ~/referential/rest/{version}/public/searchCard/{requestId}

Search card by pan, token pan and expiry date.

Examples

• Sample 1 of successful search card    

Input : 

Content-Type: application/json
{
         "principal" : {
         "type": "pan",
         "value": "3569990010059540"
            },
    "service": "ACS_U5G",
    "issuerCode": "00006",
    "subIssuerCode":"00006",
    "expiry": {
         "type": "expiry",
         "value": "2017-11"
            }
}

Output :

{
    "id": "8f7b2bd8-9e9a-46a3-8006-a768e10dee9f",
    "createdTime": "2020-11-25T06:37:55",
    "updatedTime": "2019-03-05T04:18:26",
    "deletedTime": "2022-10-23T08:55:15",
    "token": "g00ccbf4c96f5b98",
    "cardHolderId": "046949fc-a1b8-49ca-b19b-245619262a1e",
“firstName”:“John”,
“lastName”:”Dow”,
    "language": "fr",
    "status": "ACTIVE",
    "credentials": {
        "type": "plain",
        "value": "{\"METHOD:DDN\":[{\"ddn\":\"01011970\",\"ddnPattern\":\"DDMMYYYY\"}],\"METHOD:PWD\":[{\"pwd\":\"!@#$,{;(^&*)}:\\\\.?/+-_=|'][~\\\"%!@#$,{;(^&*)}:\\\\.?/+-_=|'][~\\\"%\"}],\"METHOD:SMS\":[{\"sms\":\"+33600000000\"}],\"METHOD:EMAIL\":[{\"email\":\"testworldlinebox1@yopmail.com\"}]}"
    }
}

• Sample 2 of successful search card    

Input : 

Content-Type: application/json
{
         "principal" : {
         "type": "pan",
         "value": "4000000000000002"
            },
    "service": “HUB_NRT",
    "issuerCode": "66666",
    "subIssuerCode":"66666",
    "expiry": {
         "type": "plain",
         "value": "2023-06"
            }
}

Output :

{
    "id": "52b3f168-aef2-40e2-80ff-7974e325b55c", 
    "createdTime": "2022-12-01T11:43:59", 
    "deletedTime": "2022-12-23T09:45:35", 
    "token": "mckNDAwMDAwMDAwMDAwMDAwMg==", 
    "cardId": "52b3f168-aef2-40e2-80ff-7974e325b55c", 
   “cardHolderId”: “e57bcbf7-846e-4d5b-bb27-f9a2ec0d6a39”, 
   "firstName": "John", 
   "lastName": "Dow", 
   “language”: “fr”, 
   "status": "ACTIVE", 
   “expiryDate”: "2024-06", 
   "credentials": { "type": "plain", "value": "{\"METHOD:EMAIL\":[{\"email\":\"testnrt@gmail.com\"}]}" }, 
   "label": "cardLabel" 
}

• Sample 3 of successful search card    

Input : 

Content-Type: application/json
{
    "principal": {
        "type": "pan",
        "value": "{{pan}}"
    },
    "cardHolderId": "{{cardHolderId}}",
    "expiry": {
        "type": "expiry",
        "value": "2023-10"
    },
    "service": "{{service}}",
    "issuerCode": "{{issuerCode}}",
    "subIssuerCode": "{{subIssuerCode}}"
}

Output :

{
    "id": "bae13888-7deb-4c68-9761-96c265062320",
    "createdTime": "2023-03-10T13:28:48",
    "updatedTime": "2023-03-10T13:28:59",
    "token": "mckNDk3NjcwMDAwMDAwMDAxNQ==",
    "cardId": "bae13888-7deb-4c68-9761-96c265062320",
    "cardHolderId": "811aa876-4a88-4fd4-815e-0f63fce8bb7c",
    "language": "fr",
    "status": "ACTIVE",
    "expiryDate": "2023-10",
    "credentialList": [
        {
            "type": "IVR",
            "value": "+37477445464"
        },
        {
            "type": "EMAIL",
            "value": "tigranyan.argishti@gmail.com"
        }
    ]
}

• Sample of error card not found    

Output : 

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

    16.3. copyCard

POST ~/referential/rest/{version}/public/copyCard/{requestId}

This function will be used for copying credential data from one card to another.

Examples

Input : 

{
    "service":"{{service}}",
    "issuerCode": "{{issuerCode}}",
    "subIssuerCode": "{{subIssuerCode}}",
    "oldPan": {
        "type": "pan",
        "value": "{{pan}}"
    },
    "oldDeletedTime": "2028-08-01T00:00:00",
    "oldCardStatus":"ACTIVE",
    "newPan": {
        "type": "pan",
        "value": "{{pan_4164}}"
    },
    "newExpiryDate": {
        "type": "expiry",
        "value": "2022-10"
    },
    "newDeletedTime": "2025-08-01T00:00:00",
    "newCardStatus":"ACTIVE",
    "newCardId":""
}

• Output of successful copy card    

{
    "id": "0be3e040-acfa-4807-88b5-2214cd4b1d1b",
    "createdTime": "2023-03-10T13:34:30",
    "deletedTime": "2025-08-01T00:00:00",
    "token": "mckNDk3NjcwMDAwMDAwMDAyMw==",
    "cardId": "0be3e040-acfa-4807-88b5-2214cd4b1d1b",
    "cardHolderId": "811aa876-4a88-4fd4-815e-0f63fce8bb7c",
    "language": "fr",
    "status": "ACTIVE",
    "expiryDate": "2022-10",
    "credentialList": [
        {
            "type": "EMAIL",
            "value": "tigranyan.argishti@gmail.com"
        },
        {
            "type": "IVR",
            "value": "+37477445464"
        }
    ]
}

• Output of error copy card when old PAN is unknown    

{
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "requestId": "4f70f7c9-8a74-411b-aff6-b9744c916fc5",
    "service": "ACS_U9F",
    "principals": [],
    "errorCode": "400100005",
    "origin": "REFCLIENT",
    "message": "com.wl.gbl.ah.utils.services.exception.AuthenticationHUBExceptionV2: Bad parameter : Undefined Card ",
    "originVersion": "21R2-P-05-SNAPSHOT",
    "originHost": "tsahx001v",
    "contextTemporary": {}
}

    1.4. updateUserWithCredentials

POST ~/referential/rest/{version}/public/updateUserWithCredentials/{requestId}

Current method will be used to update credentials of all cards for specified user. In case of request for more than one card, any error on one card will dismiss the update / creation for other cards.

Examples

• Request to update user credentials

Input : 

{
    "service": "ACS_U9F",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "credentials": {
        "type": "plain",
        "value": "{\"METHOD:SMS\":[{\"sms\":\"+37441901157\"}]}"
    },
    "credentialsUpdateMode": "UPDATE",
    "cardHolderId": "cardholderid",
    "firstName": "new first name",
    "lastName": "new last name"
}

Output :

{
    "cardResponses": [
        {
            "id": "53d47f12-463e-45d8-95c5-87dd4fc5ce16",
            "cardId": "5fddf717-e51f-4507-a439-6dc54d889970",
            "cardHolderId": "cardholderid",
            "tokenPan": "g02d20a3b496d266"
        },
        {
            "id": "c0931ee5-b195-4660-92b5-6ea54a7e554d",
            "cardId": "a9137220-ff21-48de-8120-507bb2283008",
            "cardHolderId": "cardholderid",
            "tokenPan": "g02d20a3b496d266"
        },
        {
            "id": "7e934f88-15f1-4166-86a1-1e38775dce01",
            "cardId": "updatedCardIdv2021R3",
            "cardHolderId": "cardholderid",
            "tokenPan": "g02d20a3b496d266"
        },
        ...
    ]	
}

• Request to update user credentials after adding credentialList functionality

Input : 

{
    "service": "{{service}}",
    "issuerCode": "{{issuerCode}}",
    "subIssuerCode": "{{subIssuerCode}}",
    "cardHolderId": "{{cardHolderId}}",
    "principal": {
        "type": "pan",
        "value": "{{pan}}"
    },
    "expiry": {
        "type": "expiry",
        "value": "2022-10"
    },
    "firstName": "firstName",
    "lastName": "lastName",
    "language": "fr",
    "credentialsUpdateMode": "DELETE_AND_CREATE",
    "credentialList": [
        {
            "type": "SMS",
            "value": "+37477445464"
        },
        {
            "type": "EMAIL",
            "value": "tigranyan.argishti@gmail.com"
        },
        {
            "type": "IVR",
            "value": "+37494952595"
        }
    ],
    "label": "label"
}

Output :

{
    "cardResponses": [
        {
            "id": "f492fce5-2827-4902-9df9-b3bcd2fca227",
            "cardId": "f492fce5-2827-4902-9df9-b3bcd2fca227",
            "cardHolderId": "71b2bb27-3aa8-47ee-b594-d52f21f38ea7",
            "tokenPan": "mckNDk3NjcwMDAwMDAwMDAxNQ==",
            "language": "fr"
        }
    ]
}

• Request to delete user credentials

Input : 

{
    "service": "HUB_NRT",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "context": {
        "protocolVersion": "2.2"
    },
    "cards": [
        {
            "id": "GUID",
            "principal": {
                "type": "pan",
                "value": "4532953162392327"
            },
            "expiry": {
                "type": "plain",
                "value": "2024-03"
            },
            "cardHolderId": "ef9a45e1-2399-4af4-89e4-37011ab3a50b"
        }
    ],
    "credentials": {
        "type": "plain",
        "value": "{\"METHOD:TA\":[{\"TA\":\"DELETE\"}],\"METHOD:EMAIL\":[{\"email\":\"DELETE\"}]}"
    },
    "cardHolderId": "ef9a45e1-2399-4af4-89e4-37011ab3a50b",
    "firstName": "first name",
    "lastName": "last name",
    "credentialsUpdateMode": "DELETE"
}

    1.5. searchUserCredentials

POST ~/referential/rest/{version}/public/searchUserCredentials/{requestId}

Search user credentials by card holder ID.

Examples

• Sample of successful search user credentials

Input : 

Content-Type: application/json
{
     "principal": {
        "type": "pan",
        "value": "4978041601875887"
    },
    "service": "ASC_U9F",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "cardHolderId" : "302fe46b-c234-4386-b034-8227e073cfd9"
}

Output :

{
    "cardHolderId": "302fe46b-c234-4386-b034-8227e073cfd9",
    "language": "fr",
    "cardResponses": [
        {
            "status": "ACTIVE",
            "tokenPan": "mck1oba4c659oadp",
            "expiryDate": "2022-10",
            "credentials": {
                "type": "credentials",
                "value": "{\"METHOD:TA\":[{\"TA\":\"38a4a004-2e3b-11eb-adc1-0242ac120002\"}]}"
            }
        }
    ]
}

• Sample of successful search user credentials after adding CredentialList functionality

Input : 

Content-Type: application/json
{
    "principal": {
        "type": "pan",
        "value": "{{pan}}"
    },
    "cardHolderId": "{{cardHolderId}}",
    "expiry": {
        "type": "expiry",
        "value": "2023-10"
    },
    "service": "{{service}}",
    "issuerCode": "{{issuerCode}}",
    "subIssuerCode": "{{subIssuerCode}}"
}

Output :

{
    "cardHolderId": "71b2bb27-3aa8-47ee-b594-d52f21f38ea7",
    "firstName": "firstName",
    "lastName": "lastName",
    "language": "fr",
    "cardResponses": [
        {
            "status": "ACTIVE",
            "tokenPan": "mckNDk3NjcwMDAwMDAwMDAxNQ==",
            "expiryDate": "2025-03",
            "credentialList": [
                {
                    "type": "SMS",
                    "value": "H##e9fe0c080fb29a7452a34d1fe213f46aeb1a7200cdd1e5fe467c595b"
                },
                {
                    "type": "IVR",
                    "value": "H##9b7b59e57230472c2bb7ab8f5947be9568ccd6447673ff474f6373ee"
                },
                {
                    "type": "EMAIL",
                    "value": "H##1c2a13bed56df2c7f7c1bb97f848643503088e671ac31df63e8238d97376084d2fead3c6f478d16cc220b746"
                }
            ]
        }
    ]
}

• Sample of user credentials not found after adding CredentialList functionality

Output : 

{
    "cardHolderId": "74e9bf86-ca83-44cd-aa4e-58dd939e2936",
    "cardResponses": [
        {
            "status": "ACTIVE",
            "tokenPan": "mck26e5fc4c5hfkp",
            "expiryDate": "2022-11"
        }
    ]
}

    1.6. createVirtualCard

POST ~/referential/rest/{version}/public/createVirtualCard/{requestId}

Create Virtual Card, based on a real PAN.

Assumptions :

• vPan must be a valid PAN number (13-19c.) with correct luhn key,
• Expiry date could be handle for vPAN - A deleteTime is mandatory for each virtual card,
• A PAN could have multiple vPAN,
• vPAN must be linked to one and only one existing and active PAN.

As it was already mentioned, each virtual card is associated with a real card. But each real card should not have more than 100 active virtual cards connected to it. Aside of that, depending on the bank, the capability to retrieve the real PAN differs.

There are banks which are configured to have external card repository, which means that the real PAN remains unknown in the HUB database until the first transaction is done, For such Banks, a virtual PAN could be created for an unknown PAN in HUB’s database. Both cards, physical card (PAN) and virtual card (vPAN) will be created in one step base on the same request.

Example

Input : 

Content-Type: application/json
{
    "service": "ASC_U9F",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    "principal": {
        "type": "pan",
        "value": "4978041601875887"
    },
    “vPrincipal”: {
        "type": "pan",
        "value": "4716636697857207"
    }
    "vExpiryDate": {
        "type": "plain",
        "value": "2022-10"
    },
   "vDeletedTime": "2023-12-03T10:15:30"
}

Output : No Content

    1.7. updateVirtualCard

POST ~/referential/rest/{version}/public/updateVirtualCard/{requestId}

Update an existing Virtual Card.

Example

Input : 

Content-Type: application/json
{
    "service": "ASC_U9F",
    "issuerCode": "66666",
    "subIssuerCode": "66666",
    “vPrincipal”: {
        "type": "pan",
        "value": "4716636697857207"
    },
    "vExpiryDate": {
        "type": "plain",
        "value": "2022-10"
    },
   "vDeletedTime": "2023-12-03T10:15:30"
}

Output : No Content

2. Data Dictionary

    2.1. Credentials

Credentials field is corresponding to information of cardholder which is mandatory to initialize and launch the authentication.

The credentials value field is a String that can be parsed in JSON into a Map of credentials each containing a Map with its value. The value is always a String that needs to be casted to as JSON object, as a result, all the double quotes characters need to be escaped by a backslash. This process is only requested for data provided in plain text. For encrypted data, the encrypted result is in HEX format so compliant with JSON format.

• Example 1: Plain example

"credentials": {
	"type": "plain",
	"value": "{\"METHOD:PWD\": [{\"pwd\": \"M0nP@sswrOrD\"}], \"METHOD:SMS\": [{\"sms\": \"+33600000000\"}]}"
}

This will be parsed into:

{
	"METHOD:PWD": [{
		"pwd": "M0nP@sswrOrD"
	}],
	"METHOD:SMS": [{
		"sms": "+33600000000"
	}]
}

• Example 2: Encrypted example

"credentials": {
	"type": "encrypted",
	"value": "4a67ba0915b17c54f41d6bb79e35c0053f418728ccefa6e2c9e6f4b96a63e6c34452b8ced31f45b7bb6c9fb02e7972fd1731bb3e3350b30a4407b4b858f173

2a450434c2f01fc4",
"keyTag": "01"
}

The value in the 2nd example is the encrypted version of the value in the 1st example. When the type is encrypted, the encryption is applied to the entire value field.

• Example 3: Hashed example

In some cases, the password can be pushed hashed. In that case here is how it needs to be used :

"METHOD:PWD\":
[{"value":"f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9","algorithm":"SHA-256"}]

Kinds of credential currently available are in standard are:

• SMS 
  mobile phone used for authentication by OTP sent by SMS
  HUB phone number must be in international standard E.164 format.
  164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits.

"credentials": {
    "type": "plain",
    "value": "{\"METHOD:SMS\":[{\"sms\":\"+33644190115\"}]}"
  },

On old version of Card Repository:

"credentials": {
    "type": "plain",
    "value": "{\"METHOD:SMS\":[{\"phonenumber\":\"+33644190115\"}]}"
  },

• IVR 
  landline phone used for OTP sent by Interactive Voice Call
  HUB phone number must be in international standard E.164 format.

"credentials": {
    "type": "plain",
    "value": "{\"METHOD:IVR\":[{\"ivr\":\"+33244190115\"}]}"
  },

On old version of Card Repository:

"credentials": {
    "type": "plain",
    "value": "{\"METHOD:SMS\":[{\"phonenumber\":\"+33644190115\", \"ignoreForSms\":\"true\"}]}"
  },

• EMAIL 
  Email address used for authentication by OTP sent by mail.

"credentials": {
  "type": "plain",
  "value": "{\"METHOD:EMAIL\":[{\"email\":\"testnrt@test.com\"}]}"
  }

• SSN

  "credentials": {
    "type": "plain",
    "value": "{\"METHOD:SSN\":[{\"ssn\":\"93e2e023-0784-4d06-ac25-bf7c4bdf2603\"}]}"
  }

• TA

  "credentials": {
    "type": "plain",
    "value": "{\"METHOD:TA\":[{\"TA\":\"93e2e023-0784-4d06-ac25-bf7c4bdf2603\"}]}"
  }

• DDN 
  Authentication by Birthdate

"credentials": {
  "type": "plain",
  "value": "{\"METHOD:DDN\":[{\"ddn\":\"19810803\",\"ddnPattern\":\"AAAAMMJJ\"}]}"
}

• PWD in plain text 
  Authentication by password – password is provided in plain text but stored in database encrypted

  "credentials": {
    "type": "plain",
    "value": "{\"METHOD:PWD\":[{\"pwd\":\"123456\"}]}"
  },

• USERCODE in plain text

"credentials": {
	"type": "plain",
	"value": "{\"METHOD:USERCODE\":[{\"usercode\":\"9876543210\"}]}"
}

Current version 25R2-1.0 of September 4th 2025

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. 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.
 

  1.1. File transfer mode

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

  1.2. Security of exchanges through file transfers

    1.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.

    1.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.

  1.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.

  1.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

    1.4.1. Record « Header »

    1.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.

    1.4.3. Record « CardHolder »

    1.4.4. Structure « CardHolder »

    1.4.5. Structure « Card »

    1.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.

    1.4.7. Structure « CardData »

Note: CardData is not currently used.

    1.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

    1.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.

    1.4.10. Example file log report

    1.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.

2. Validation rules for xml format

  2.1. Header

  2.2. CardHolder

  2.3. Card

  2.4. AuthenticationData

3. Functional Validation rules

  3.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}

  3.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

   

Current version 25R2-1.0 of September 4th 2025

RBA Scoring WS Client  is the standard interfaces exposed by an external RBA platform and expected by ACS as client server.

Thanks this API, ACS can get a score and indicators from a scoring platform and update it for giving additional information regarding the final authentication done.

1. Functional Workflows

  1.1 Scoring request

If the bank has a scoring platform, for each incoming transaction (Areq), thanks to scoringRequest, a real time response provides a risk rating (score and indicators).

Based on this score and additional conditions, the Bank can decide either to approve the authentication without Strong Customer Authentication (frictionless flow), or ask for customer authentication (Challenge flow), or decline transaction if risk is too high.

  1.2 Notification request

Once the transaction has been completed, a notification request is sent, thanks to notificationRequest giving additional information regarding the final authentication done.

Current version 25R2-1.0 of September 4th 2025

APM WS Server is a standard interfaces exposed by ACS.
The bank is therefore client of ACS.

Thanks to this API the bank can manage  :

• the trusted beneficiaries ;
  It is possible add, remove or get the trusted beneficiaries for a given cardholder

• the merchants lists and categories;
  It is possible to set a category (Eligible Trusted beneficiaries, Secure Corporate, Level 1, etc.) for a given merchant.

• the operands value used in APM rules engine;
  For example, it is possible to set the purchase amount threshold authorized based on Bank's ETV value 

RBA Scoring API is the standard interfaces which is used to connect a Scoring platform to ACS.

Scoring platform provides a score, a recommendation and indicators, based on these information and ACS Rulesets, the APM rules engine takes an authentication decision (Frictionless, SCA or Decline)

Another standard WS APM interface, exposed by ACS, allows to manage the trusted beneficiaries, the merchants categories and the thresholds value used in APM rules engine;

VERSION 26R1 - last update Sept. 10 2025 

The ACS platform provides a set of APIs to manage and configure your ACS' Cardholder repository (cards, credentials, etc.), and to interface with your Bank’s information system or with your external authentication and scoring solutions. These APIs are standardized to enable rapid and easy integration.

These APIs can be grouped into four distinct domains:

• Risk-Based Authentication (RBA) allows interfacing with a scoring platform (external or Riskshield Inform) and also provides the ability to update data used by the APM rule engine (ETV threshold, merchant category, etc.).
• Card Referential manages the Cardholder repository by importing it via batch loads, in real time, or by real-time querying of the Bank’s information system.
• Authentication enables initiating and validating an authentication managed by an external module outside the ACS platform.
• Transactions allows to get a real-time export or retrieval of transaction information.
   

ACS API could be secure by using Oauth 2.0 protocol or mTLS.

List of changes

VERSION 26R1 - last update Sept. 18 2025

This specification describes the features proposed by the module WL Authentication Process Management (APM) to process a Risk Based Authentication solution for 3D-Secure platform. 

1 Overview

With the enforcement of PSD2, article 97 requires that “Payment Service Providers to authenticate a user when they:

• access an online payment account,
• initiate an electronic payment transaction,
• or carry out any action through a remote channel that may imply a risk of payment fraud”.

This new regulation will lead to an increase in Strong Customer Authentication. In order to provide a better user experience and to lower costs due to Strong Authentication, the Bank can choose a Risk Based Authentication (RBA). RBA is recommended by many regulations (PSD2) and schemes under the EMV 3DS 2.1 protocol.

WL APM is a functional extension of the ACS. New modules are added to be able to assess the risk of transactions. Thanks to the transaction risk analysis (TRA), the Bank can decide either to approve the authentication without SCA (frictionless flow), or ask for SCA (Challenge flow), or decline transaction if the risk is too high.

WL APM main goals are to:

- Check exemptions (RTS and others) and determine the right authentication workflow to process,

• Implement RBA for payment and non-payment flows,
• Manage authentication workflow for card based payments (3DS transactions) as well as PSD2 Access to Account use cases (PIS, AIS).
• Propose a bank extranet which functionalities are included in the ACS back-office. 

WL APM is agnostic of any scoring platform. Therefore, RBA scoring can be done by Worldline Solution (Inform Riskshield), DS, Issuer Bank or by an external scoring tool.

WL APM is a modular solution which can process RBA and SCA for 3DS Secure flows.

                                                           Figure 1 : Overview of WL APM functional architecture

2 Functional description

During the initialization of an authentication request, WL ACS is in charge of:

• Identifying the cardholder who has to be authenticated,
• Checking the status of the cardholder,
• Retrieving all the authentication methods available for the cardholder,
• Providing this information to the Service Provider.

WL ACS also includes an additional module, the APM- RBA rules engine, which covers the following complementary features:

• Check Standard Fraud prevention lists (e.g. black lists, white lists, ...),
• Take into account fraud score and recommendation from external platform (DS, merchants, scoring platform, ...)
• Apply Rules (From Bank, Scheme or regulatory framework) to make a decision,
• Provide a Decision to the Service Provider.

Then, the Service Provider is able to make a decision and decide which authentication process to trigger:

• Frictionless: acceptation of the authentication without any authentication action asked to the cardholder
• Strong Customer Authentication: challenge asked to the cardholder
• Decline: refusal of the authentication

                                                                        Figure 2: Overview of WL APM decision process

 2.1 Rules Engine

2.1.1 Workflow

The WL APM rules engine is a module which can apply specific rules, in a defined sequential order to establish a SCA decision.

The decision can take 3 results:

• Frictionless : no authentication requested for the transaction,
• SCA : Strong Customer authentication must be done, in this case strong authentication means available will be provided also to Service Provide
• Decline: the transaction is too risky and must be declined.

WL APM provides a predefined standard set of rules. Then, the Bank chooses which rules or set of rules has to be activated depending on its strategy.

The rules list and the scheduling are defined by the Bank. It can be different depending on the use case (3DS, e-banking, Access to Account…).

                                               Figure 3: Overview of WL APM RBA Rules engine

Categories of rules

The rules engine can manage rules in part or in whole. It allows setting up:

• The bank's own rules
• The rules of the schemes
• RTS exemptions (optional if managed on another bank system)
• The rules related to the score
• Bank specific rules
  • Blacklist of users, countries (user IP), phones, merchants
  • White list of users
  • Merchant pivot amount: list of merchants for whom strong authentication is mandatory above a defined threshold
• Scheme rules
  • ID&V
  • VPP
  • BIN Attack
• RTS Exemption Rules
  • Low value transactions (Amount < 30 € and cumulative amount of < 100 € or 5 consecutive frictionless transactions)
  • Analysis of the risks related to the transaction (amount between €30 and ETV and risk analysis)
  • Trusted beneficiaries
  • Secure Corporate
• Rules related to the score:
  • Consideration of the recommendation of the scoring platform (frictionless, SCA, decline)
    • Interpretation of the score provided (value of the score + recommendation):
      • Either by the scoring platform
      • or by the directory server
    • Fallback

WL APM RBA parameters

Bank can choose, for example:

• To activate or deactivate the WL APM RBA process
• To activate or deactivate the call to the external Scoring platform
• To take into account or ignore the scoring and recommendation from Directory Server
• To take into account or ignore the scoring and recommendation from external Scoring platform
• To define which scoring is most valuable between Scheme or external platform
• To bypass the score request for a Scheme
• To bypass the score request for virtual Cards
• Value of threshold amount or threshold score
• To activate or deactivate a rule
• To change rule order (switch ordinal of two rules).
• etc.

A new tool, called "Rules Creator", also allows for the creation and management of APM rules entirely independently via the Back-Office (cf. Back-Office User's guide).

In case of technical error or unavailability of the rules engine, it will answer back to the authentication workflow that a SCA has to be triggered.

Moreover, not to slow down the authentication process, a timer can be configured (e.g. DS asks to answer within 5 seconds on Areq/Ares message).

2.1.2 Definition of rules

2.1.2.1 Criterion

Transaction Data used as criterion in rules Engine are:

• Amount of the transaction (converted in Bank's currency),
• Score of the transaction
  • Provided by Scheme,
  • Provided by External Scoring Platform,
  • Provided by Issuer
• SCA recommendation
  • Provided by Scheme,
  • Provided by External Scoring Platform,
  • Provided by Issuer
  • Provided by Merchant
• Cumulative amount of consecutive frictionless transactions,
• Number of consecutive frictionless transactions,
• Threshold
  • ETV level amount (see § 6.1)
  • Frictionless amount threshold (30 EUR as defined by PSD2)
  • Minimum Score threshold
  • Maximum Score threshold
  • Specific Bank thresholds
• Merchant Identity (Name) 
• Merchant inclusion in Issuer’s List Merchant
• Merchant country code
• Acquirer country code
• MCC includes in travel industry list (cf. Appendices)
• Protocol version
• Scheme
• Brand
• Secure corporate payment flag
• Recurring and Instalment flag (1^st transaction or a recurring n transaction)
• 3RI flag
• 3RI use case based on threeRIInd value
• Message Category value (Payment / Non-Payment / 3RI)
• threeDSRequestorChallengeInd
• threeDSRequestorAuthenticationInd
• MasterCard merchant fraud rate
• Absence of score
• Prior Reference Transaction is retrieved
• Compare amount of prior and subsequent transaction
• Compare currency of prior and subsequent transaction
• MasterCard risk data – MasterCard “recommendation” and “reason code 1”
• CB recommendation – “cbAction” data
• VISA DAF fields ; authPayProcessReqInd, authPayCredStatus and dafAdvice
• VISA VPP indicator
• FIDO assertion or attestation control
• PAN is card virtual ; boolean
• Issuer Maintenance Mode activation on ACS platform ; boolean

Some criterion values depend on the transaction context. Others, like threshold are variable defined by the Bank in the rules engine module.

2.1.2.2 Rules

A rule is a list of operands which apply to criterion to make an action.

Available Operands are:

• Equals
• Lower [or equals]
• Greater [or equals]
• And
• Or
• Boolean
• In

Actions are:

• Fix decision value for a specific reason
• Continue to next rules

2.1.2.3 Rules set

A rules set is a list of rules defined in an established order which defines the priority of the rules and the strategy of the bank to take a SCA Decision.

                                                                                Figure 4 - Example of Rules Profile

Rules set can be defined on Service, Issuer or Sub-Issuer Level. However, only one rules profile can be defined for a given Bank. If a sub-Issuer doesn’t have profile defined then the profile of its Issuer will be applied.

Specific rules set could also be defined based on optional information: 3DS Protocol Version (2.2 or 2.3.1), Network (VISA, MasterCard, CB, …), location (Merchant Country in or outside EEA) and deviceChannel (Browser Base, App base, 3RI)

In case of lot of rules set definition with intersection, the rules to apply is retrieved base on the priority order below:

1. service: required
2. issuer: required
3. subIssuer: optional
4. location: (Merchant Country - EEA) optional
5. Network optional
6. Protocol Version optional
7. deviceChannel: optional

2.1.2.3 Rules configuration

The bank can modify the existing rules directly via the API and ACS back-office or via integration project depending on the complexity of the change expected.

 2.2 PSD2 RTS requirements

SCA exemptions are based on the level of risk, amount, recurrence and the payment channel used for the execution of the payment. These exemptions allow PSPs to achieve the right balance between convenience of the payment experience and fraud reduction

WL APM includes a Rules engine and Risk-Based Authentication compliant with PSD2 RTS and schemes requirements to check SCA exemptions.

By default, the WL APM module includes the following rules:

• Check acquirer location
• Check amount vs minus threshold (by default 30 euros)
• Check cumulative amount since last SCA (by default 100 euros)
• Check number of transaction since last SCA (by default 5 transactions)
• Check amount vs issuer ETV
• Check RBA risk value (low / medium / high)
• Check if recurrent transaction
• Check Acquirer Exemption
• Check 3RI Use Cases

The following rules are out of the scope of the 1^st version of WL APM:

• Check if beneficiary is the payee (out of 3DS scope)

                                      Figure 5 – Application of PSD2 RTS Rules – arts 16 and 18

WL APM manages exemptions which apply to 3DS flows. Here are the detailed rules:

3 White & Black lists

This function allows managing standard fraud prevention lists. You can access it via the navigation banner by selecting the heading <Fraud>.

Fraud is controlled in real time for each transaction thanks to the fraud parameters which have been entered in the ACS3 Back Office.

The available fraud functions on the platform are:

• Cards in white/black lists,
• Cards in exemption lists,
• Blacklisted authentication mean
• IP filters
• Blacklisted merchants (URL, Name, ...)
• Country blacklist (cardholder IP)
• Fraud lists search

 3.1 Cards in white/black or exemption lists

This function is used to:

•  Search for a whitelist or blacklist card
•  Add a card to the blacklist, whitelist or exemption list
• Delete a card from the blacklist or the whitelist.

Business rules :

1. When a card is blacklisted, the card is blocked for all authentication requests. A blacklisted card will neither be able to perform a challenge nor participate in frictionless authentication.
2. When a card is whitelisted, it benefits from an exemption, allowing it not to be affected by merchant-based, country-based and IP-based blacklists.
3. When a card is placed on the exception list, it is identified as such and can therefore have rules specific to the ACS authentication profile.

 3.2 Blacklisted means

This function is used to:

• Search for the presence of an authentication mean in the blacklist via the phone number or the e-mail address
• To add an authentication mean in black list
• Delete a blacklisted authentication mean.

Business rules :

1. When a mean (phone number or email address) is blacklisted, it is automatically retired from the list of available credentials. 
2. If the blacklisted credential is the only credential available, the associated authentication method is revoked for the current transaction.
3. An authentication mean can be blacklisted for a determined period or indefinitely.
    

 3.3 IP filters

This function allows you to:

• Look for the existence of a IP filter
• Add an IP filter to a blacklist
• Delete an IP filter from the black list.

Business rules :

1. If the Cardholder IP address of the transaction is in a blacklisted range, the authentication is declined.
2. The IP filter can be applied to the instance, or the issuer and its sub-issuers or to one sub-issuer.
3. The IP filter can be limited to an IP address, to an IP range or to an IP address mask.

 3.4 Blacklisted merchants

This merchant black list is based on the following information:

• The merchant URL, name, id or domain
• The cardholder IP country who makes his purchase on the merchant website (Geo-location)
• A threshold amount and its direction (>= / <=)

These 3 pieces of information are managed by the rules engine.

The first piece of information is transmitted in the PAREQ or AREQ messages sent by the merchant.

The user can carry out the following actions via the back-office:

• View the blacklisted merchants
• Add a merchant in the black list
• Delete a merchant from the black list

Business rules :

1. If the merchant data refers to one of the blacklisted merchant lists, the authentication is declined.
2. The Merchant blacklist can be applied to the instance, or the issuer and its sub-issuers or to one sub-issuer.
3. The Merchant blacklist  can be defined for a merchant URL, merchant name or a merchant domain.

 3.5 Country Blacklist

This function allows:

• Access to the blacklist of countries (IP cardholder)
• Add a country to the blacklist
• To modify the pivotal amount above which transactions are refused
• To delete a country from the black list.

Business rules :

1. When a country is blacklisted, all transactions from that country are rejected if the amount of the transaction is greater than the amount set for the country.
2. The country is detected from the IP address of the cardholder.
3. The country blacklist can be applied to the instance, or the issuer and its sub-issuers or to one sub-issuer.

4 Merchants List

On APM rules engine is possible to define a rule for a limited list of merchants. To do that, the rule must include an operator which checks Merchant inclusion in Issuer’s List Merchant for a specific category flag.

The check is done based on the merchant name, field “merchantName” in protocol 2. The name of the merchant defined in the ACS list must be strictly equals to the name provided in the 3DS.

The list could be defined on Instance, Issuer or Sub-Issuer Level.

The list of merchant is limited to 500 merchants.

Each merchant is included in specific categories. A merchant could be flagged in 1 to N categories.

The available categories are:

• Secure Corporate
• Trusted Beneficiaries ACS
• Trusted Beneficiaries 3DS Server
• Delegated Authentication
• TRA
• Risk
• Level 1 to 5

The APM rule condition will be for example:

merchantName ∈ {Merchants List flagged “Secure Corporate”}

Merchants List could be managed in ACS BO or via standard Public RBA API

5 Exonerating hint 

If an external scoring platform is configured for a Customer, then the logic comes as described below:

• During AReq processing, a Scoring request is sent to scoring platform
• After the ARes message (Frictionless) or RRes message (Challenge), a Notification request (Advice) is sent to scoring platform

A score (authScore) and a decision (authIndicator) are returned in score response message.
It is also possible for an external scoring platform to provide an RBA reason using generic field exoneratingHint. 
 

If the exonaratingHint contains an existing valid Reason (cf. reason types list)
then APM could returns this value to ACS platform which triggers the transStatus and transStatusReason values accordlingly.

APM must be configured with a single rule to apply the Scoring recommentation :

• decision = EXTRBADECISION
• reason = EXT_RBA

The APM configuration to handle the exoneratingHint field and the overriding logic is defined in the table below:

In summary, if APM is configured to use the Scoring platform decision as received, then the rbaReason returned to ACS must be the externalRBA Reason, i.e., if rbaReason = EXT_RBA

VERSION 26R1 - last update Sept. 18 2025

1. Purpose of this page

WL APM Rules Engine is a functional extension of the HUB.

New feature are added in RBA Module to be able to assess the risk of transactions. Thanks to the transaction risk analysis (TRA), the HUB will provide a decision to ACS and Banks can decide either to approve the authentication without SCA (frictionless flow), or ask for SCA (Challenge flow), or decline transaction if the risk is too high.

WL APM main goals are to:

• Check exemptions (PSD2 RTS and others) and determine the right authentication workflow to process,
• Implement RBA for payment flows,
• Propose a bank extranet which functionalities are included at the beginning in the ACS back-office.

WL APM is agnostic of any scoring platform.

The main goal of this document is to give the exhaustive list of :

• Operand usable to define specific conditions in rules,
• Reason linked to a decision for a specific use case

2. Operands List

  2.1 Protocol operands

The table below contains operands currently in use. The operand name must be one of the listed in the table, and must be used with corresponding operand type.

  2.2 Score operands

[1] If the “Reversed” flag is TRUE, the operator is reversed. E.g. the “STRICTLY_ABOVE” operator becomes LESS_THAN_OR_EQUAL_TO.

  2.3 Merchant operands

  2.4 Recurring / Instalment / Split operands

  2.5 MASTERCARD operands

 [1] If the “Reversed” flag is TRUE, the operator is reversed. E.g. the “STRICTLY_ABOVE” operator becomes LESS_THAN_OR_EQUAL_TO.

  2.6 VISA operands

  2.7 CB operands

3. Reason Types List

The table below contains reason types currently in use. The auth type of the reason type must match the auth type of the rule.

Notes, for Issuer with an external scoring platform configuration, it is possible to return the reason in scoring response message in field exoneratingHint.

If the APM is configured to apply the external Scoring platform’s decision, and a valid reason (included in the table below) is returned then the reason is applied.

4. Appendices

  4.1 EEA Countries List

Specific rules set could also be defined based on optional information: 3 DS Protocol Version (1.0.2 or 2.x), Network (VISA, MasterCard, CB, …), location (Acquirer Country in or outside EEA) and deviceChannel (Browser Base, App base, 3RI)

Notes, if Acquirer country code is not provided, the merchant country code is used as fallback.

By default, EEA countries list includes

AUSTRIA AT 040

BELGIUM BE 056

BULGARIA BG 100

CROATIA HR 191

CYPRUS CY 196

CZECH_REP CZ 203

DENMARK DK 208

ESTONIA EE 233

FINLAND FI 246

FRANCE FR 250

GERMANY DE 276

GIBRALTAR GI 292

GREECE GR 300

HUNGARY HU 348

ICELAND IS 352

IRELAND IE 372

ITALY IT 380

LATVIA LV 428

LICHTENSTEIN LI 438

LITHUANIA LT 440

LUXEMBOURG LU 442

MALTA MT 470

NETHERLANDS NL 528

NORWAY NO 578

POLAND PL 616

PORTUGAL PT 620

ROMANIA RO 642

SLOVAKIA SK 703

SLOVENIA SI 705

SPAIN ES 724

SWEDEN SE 752

Since 23R1, it’s possible to extend the EEA Countries List with additional countries via a parameter defined on Service, Issuer or Sub-Issuer Level

  4.2 MCC travel industry code

VERSION 26R1 - last update Sept. 18 2025

1 DAF Rules

 1.1 DAF Rules when processing VISA Payment

The Digital Authentication Framework (DAF framework defines) a unique type of payment credential referred to as an Authenticated Payment Credential which is defined as follows:

1. The Issuer has confirmed the authenticity of the Payment Credential through Issuer identification and verification (ID&V) or,
2. Visa has determined the Payment Credential to have a sufficient history of successful Transactions at a registered Merchant such that the Issuer has effectively validated its authenticity and the Payment Credential is uniquely associated with the registered Merchant or Merchant Token Requestor. Merchants who transact with Authenticated Payment Credentials and meet the DAF program criteria on qualified purchase transactions will receive fraud dispute protection in a frictionless manner on subsequent transactions.

When processing VISA payments over DAF, the following APM rules are used for processing the payment request:

On July 2022 VISA published a new version of specification v1.1. This specification includes new feature related to transaction declining based on whether a fraud is suspected or not. Fraud handling logic works as follows:

1. During a "Must Approve" use case, declines are permitted in the case of compromised credentials. Issuers can notify Visa of a compromised card by using: N+10 (stolen card) or N+11 (suspected fraud)
2. For Europe domestic authentication requests, European issuers may decline low risk transactions that are not authenticated under the Visa Delegated Authentication Program or other agreements with issuers: N + 90
3. APM add also the possibility to reject all DAF transactions for reason “Not supported”

DAF transaction related full list of reason types:

1. DAF_ENROLMENT
2. DAF_MUST_APPROVE
3. DAF_SUSPECTED_FRAUD
4. DAF_NON_VDAP
5. DAF_ISSUER_DECISION_LOW_RISK
6. DAF_ISSUER_DECISION_HIGH_RISK
7. DAF_NOT_SUPPORTED
8. DAF_STOLEN_CARD

 1.2 VISA FIDO - SCA pre-Enrolment

In "Supporting FIDO™Authentication -An Implementation Guide For Visa Secure", VISA announces the inclusion of FIDO authentication data in the DAF protocol and messages. 

The DAF FIDO mechanism follows 3 main steps :

• Pre-enrolment : common step for all solutions
• Enrolment : target solution depends on the FIDO server
• Subsequent transactions processing : target solution depends on the FIDO server

If merchant expects to enroll cardholder to FIDO, an agreement must be requested to ACS. This agreement is done during a SCA successful transaction. ACS is free to accept of refuse FIDO enrolment request.

ACS will :

• support for 3DS authentication method code = 80 in AReq message (agreement for FIDO enrolment)
• return transStatusReason = 91 and/or 92 in Rreq message if SCA is successful 

Notes, the pre-Enrolment process is the same for all DAF implementation ; 3DS OBO, 3DS pass-through and VTS.

 1.3 VISA VPP – Enrollment

When the merchant finalizes the FIDO enrolment, an advice is pushed to DS and ACS. Merchant sends a second AReq with the FIDO attestation data and the prior reference of pre-enrolment SCA transaction :

• VISA adds the VPP extension to the AReq towards ACS 
• ACS responds with an acknowledgment (TransStatus = I) triggered by a dedicated APM rule

A new reason (frictionless decision), has been created on APM to cover Enrolment VPP use cases :

• FIDO_ATTESTATION_OK
• FIDO_ATTESTATION_KO

No control is done on APM but an optional control could be implemented with a FIDO Server solution.
APM could be connected to a Worldline FIDO Server or any external FIDO Server platform.

The rule only identifies the use cases, triggers a frictionless and set a dedicated reason for logging and triggering on ACS the expected transSatus value.
 

 1.4 VISA VPP – Authentication

When the merchant sends the AReq with the FIDO data from the authentication (assertion) to the DS :

• The DS will enrich the AReq with the result of the control and send it to the ACS
• The ACS retrieves the VISA VPP extension 
• The APM enables the issuer to make the decision based on VPP verification values.
  • If VPP result is failure, transaction will be declined for suspected fraud reason
  • Else standard DAF rules will applied

A new operand (Boolean) has been created to check if VPP extension is available, contains an assertion and result of authentication is successful :

• VPP_ASSERTION_VERIFIED

with 2 new reasons (frictionless or decline decision) depending on VPP extension result :

• FIDO_ASSERTION_OK (Frictionless)
• FIDO_ASSERTION_KO (Decline)

 1.5 VISA VPP – Enrollment Pass-through FIDO Server

When the merchant finalizes the FIDO enrolment, an advice is pushed to DS and ACS. Merchant sends a second AReq with the FIDO attestation data and the prior reference of pre-enrolment SCA transaction.

The ACS will:

• Retrieve the FIDO attestation
• Control the validity of the attestation
• Store the FIDO credential’s Public Keyand its association with the user into the Worldline FIDO server secured environment
• Respond to the Visa directory server which sends the response to the merchant

A new operand (Boolean) has been created to check if FIDO data is available, contains an attestation, is linked to a valid prior transaction (SCA with pre-enrolment agreement) and result of authentication is successful :

• FIDO_ATTESTATION_VERIFIED

New reasons (frictionless decision), have been created on APM to cover Enrolment VPP use cases :

• FIDO_ATTESTATION_OK
• FIDO_ATTESTATION_KO

If attestation is not verified, ACS must always returns to Merchant an acknowledgement (transStatus = I) BUT attestation will be not stored as successful in WL FIDO Backend. It means that all subsequent transactions linked to this FIDO attestation will be rejected.

 1.6 VISA VPP – Authentication Pass-through FIDO Server

When the merchant’s 3DS Server sends an AReq with the FIDO data from the authentication, the ACS will:

• Verify the assertion based on the stored public key for this user and detect if the authentication was made with Secure Payment Confirmation (data related to transactions are displayed on DAF FIDO template upon cardholder authentication) or WebAuthn (no transactions details displayed). 
• Allow decisioning based on verification, APM rules and DAF mechanism
  • If assertion control fails, transaction will be declined for suspected fraud reason
  • Else standard DAF rules will applied
• Response by ARes to the Visa Directory Server / Merchant according to DAF existing rules

A new operand (Boolean) has been created to check if Areq contains an assertion and result of authentication is successful :

• FIDO_ASSERTION_VERIFIED

A new reason (decline decision), has been created on APM to cover assertion not verified by WL FIDO Back-end :

• FIDO_ASSERTION_KO

 1.7 VISA VPP – Enrollment Pass-through Issuer

When the merchant finalizes the FIDO enrolment, an advice is pushed to DS and ACS. Merchant sends a second AReq with the FIDO attestation data and the prior reference of pre-enrolment SCA transaction.

The ACS will:

• Transfer the FIDOattestation “as is” to the Issuer Platform through the Scoring Request API :
  • this API needs to be implemented by the issuer (if not already)
  • this API needs to be updated by the issuer already using it (new fields)
• Return the Ares with a frictionless decision

Warning ! Scoring platform must return in the exoneratingHint field, one of the FIDO DAF attestation reason

• FIDO_ATTESTATION_OK
• FIDO_ATTESTATION_KO

ACS must always returns to Merchant an acknowledgement (transStatus = I) BUT the response is triggered by the scoring decision and reason.

 1.8 VISA VPP – Authentication Pass-through Issuer

When the merchant sends the AReq with the FIDO data from the authentication (assertion), the ACS will:

• Transfer the FIDO assertion “as is” to the Issuer Platform through the Scoring interface
• Allow decisioning based on verification (with Scoring platform feedback), APM rules and DAF mechanism.

Warning ! Scoring platform must return in the exoneratingHint field, one of the FIDO DAF attestation reason or standard DAF reason :

• FIDO_ASSERTION_OK
• FIDO_ASSERTION_KO
  or
• DAF_SUSPECTED_FRAUD
• DAF_MUST_APPROVE
• DAF_ISSUER_DECISION_LOW_RISK
• DAF_ISSUER_DECISION_HIGH_RISK

ACS response is triggered by the scoring decision and reason.

2 VISA VTS

2 VTS transaction

The difference between VTS and 3DS transactions are :

• In 3DS the authentication decision is made by the issuer
• IN VTS, there is no possibility from the issuer to decline the authentication. VISA VSDS is responsible for authentication verification, linked to DAF. It is assumed that no invalid authentication can reach the ACS in VTS mode.

When the Visa’s VSDS performs self-verification and sends an AReq with the FIDO data from the authentication, the ACS will :

• Retrieve and verify the assertionbased on the stored public key for this user and detect if the authentication was made with WebAuthn or Secure Payment Confirmation
• Responds with an AReswith transStatus=I (07) as per DAF mechanism 

ACS differentiates VTS and 3DS transaction base on challenge Indicator value. VTS must have challenge indicator = 06.

New reasons, linked to a frictionless decision, have been created on APM to cover VTS use cases :

• FIDO_ASSERTION_VTS_OK
• FIDO_ASSERTION_VTS_KO

 2.1 VTS: Token Provisionning

VISA proposes a new Identification and Verification (ID&V) services based on an authentication done on 3DS.

So, they used the EMVCO 3DS2.x new features:

The EMV 3DS 2.1 and 2.2 specifications define a non-payment message category and authentication indicator specifically for token provisioning, and can be used for both App-based and Browser-based models

Currently APM handles a specific rule for ID&V Token 

If Message Category = 02 (or 86) (Non-Payments) and 3DS Requestor Authentication Indicator = 06 (Cardholder Verification as part of EMV token ID&V) then a SCA is required for reason “ID&V_SCA_REQ”

This rule could be combined with other operands like score level, purchase amount, etc.