Managing 3D Secure Credentials

This section provides details of how to:

• Create a 3D Secure Credential for a card
• Update the Credentials linked to a card
• List 3DS Credentials
• Delete a 3DS Credential
• Get 3DS Configuration

Creating a 3D Secure Credential

This API can be used to create a 3D Secure Authentication credential for a card.

Step 1: Retrieve card details

Before creating the credential for a card, identify the corresponding Public Token for the card to be used.
A card's public token is returned in the response to creating a card within the publicToken object.

Step 2: Create a 3D Secure credential

After identifying the public token for the card, you can create a 3D Secure credential for the card by executing a POST request to the Create 3DS Credential endpoint with the corresponding credential Type.

{{base-url}}/cards/{{publicToken}}/3ds-credentials

Credential Types

You can add multiple credentials to each card that you enrol in the 3D Secure service.

You can find an example of Create 3DS credentials request body using the OTPSMS credential type below.

{
"type":"OTPSMS",
"value": "8988"
}

If successful, a 201 response will be returned with the 3DS identifier.

{
    "identifier": 2008233
}

Creating a KBA 3DS Credential Type

When using the KBA credential type to create a 3DS credential for your card, the request body must include the value and cardholderAnswer fields. The value field contains the unique identifier of the KBA question you want to use. A default set of KBA questions are set up in Smart Client. These can be modified if required. You can view the default KBA questions in the 3D Secure Guide.

For example, in Smart Client the KBA ID 4 is set to What was the make of your first car? by default. In the below example, the value field is 4 (for KBA ID 4), and the cardholderAnswer is Vauxhall Corsa.

{
  "type": "KBA",
  "value": "4",
  "cardholderAnswer": "Vauxhall Corsa"
}

👍

API Explorer

See the Create 3DS Credentials endpoint.

Update a Credential

This API can be used to update a 3DS Authentication credential for a card.

Step 1: Retrieve card details

Before updating the credential for a card, identify the corresponding Public Token for the card to be used.
A card's public token is returned in the response to creating a card within the publicToken object.

Step 2: Update a 3D Secure credential

After identifying the public token for the card, you can update or delete the 3D Secure credential for the card by executing a PUT request to the Update 3DS Credential endpoint with the corresponding credential Type.

{{base-url}}/cards/{{publicToken}}/3dscredentials/{{3DSIdentifier}}

The body should include the new value of the 3DS credential. The below is an example of what the body should look like.

{
    "value": "07123456789"
}

If successful, a 204 response will be returned. You can use the List 3DS Credentials endpoint to confirm the update has been successful.

👍

API Explorer

See the Update 3DS Credentials endpoint.

List 3DS Credentials

The List 3DS Credentials endpoint allows you to retrieve the 3DS credentials associated with a card. You can retrieve the 3DS credentials by making a GET request to the endpoint. For example:

{{base-url}}/cards/{{publicToken}}/3dscredentials

A successful response will return a HTTP 200 response code and a payload that will return the details for the 3DS credentials for the card. For example:

[
    {
        "type": "OTPSMS",
        "value": "8988",
        "id": 2379470,
        "credentialType": 2
    },
    {
        "type": "OTPEMAIL",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 3
    },
    {
        "type": "BIOMETRIC",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 4
    },
    {
        "type": "OUTOFBAND",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 5
    },
    {
        "type": "ALL",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 6
    },
    {
        "type": "KBA",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 7
    },
    {
        "type": "BEHAVIOURALBIOMETRIC",
        "value": "Not Enrolled",
        "id": 0,
        "credentialType": 8
    }
]

A blank HTTP 200 response will be returned if there are no 3DS credentials associated with the card.

👍

API Explorer

See the List 3DS Credentials endpoint.

Delete a Credential

The Delete 3DS Credentials endpoint allows you to remove 3DS credentials associated with a card. You can delete the credentials by making a DELETE request, with the 3DS credential id being set in the endpoint. For example:

{{base-url}}/cards/{{publicToken}}/3ds-credentials/{{3DSCredential}}

👍

API Explorer

See the Delete 3DS Credentials endpoint.

Get 3DS Configuration

The Get 3DS Configuration endpoint enables customers to view a card's 3DS enrolment data from the database. This is to support customers using Apata for their 3DS provider. You can retrieve a card's 3DS configuration by making a GET request to the Get 3DS Configuration endpoint. For example:

{{base-url}}/cards/{{publicToken}}/3ds-configuration

If successful, a HTTP 200 response will be returned. For example:

{
    "provider": 4,
    "providerName": "Apata",
    "version": "Apata",
    "programManager": {
        "programManagerCode": "PMT",
        "shortName": "GPSDUMMY"
    },
    "mobile": "8988",
    "email": null,
    "isActive": true,
    "status": "00",
    "has3dSecureCredentialEntry": true,
    "apataConfig": {
        "cardProgramId": "sudbhcfndjfncvfhgn",
        "challengeProfileId": "rshgbvbhmbhverdctgvrwe",
        "financialInstitutionId": "egegdfbvcvskdfng",
        "numberOfQuestionsToAnswer": 0,
        "numberIncorrectPermissible": 0,
        "language": "en-EN"
    },
    "kba": [],
    "otpSms": {
        "otpSmsTemplateFullFormat": null,
        "otpSmsTemplateDefaultFormat": null
    },
    "biometric": {
        "autoEnrol3DSBiometrics": 0,
        "autoEnrol3DSOOB": 0,
        "biometricUrl": null,
        "hasBiometricCredentials": false,
        "hasOOBCredentials": false
    }
}

👍

API Explorer

See the Get 3DS Configuration endpoint.