Lifecycle management

Clients are required to integrate with the following endpoints for 3DS lifecycle management.

Testing - mock authentication

Used to perform authentication testing.

API schema available here.

{
"clientId": 12345,
"rid": 10000,
"acsTranId": "559b5bc7-b1ca-1234-bc9d-6f55cad7a790",
"token": 11223344,
"messageCategory": "01",
"merchantName": "Unknown",
"txnAmount": 123.45,
"txnCurrency": "840",
"authType": 1,
"otp": "email",
"languagePreference": "12345",
"additionalData": "{}",
"merchantRedirectUrl": "http://example.com"
}

{
"rid": 10000,
"token": 11223344,
"responseCode": "00",
"description": "success",
"authenticationPerformed": "12345"
}

Check card enrollment

Used to retrieve card enrollment details and descriptions.

API schema available here.

{
"api_call_unique_identifier": "438574123456657485",
"client_id": 12345,
"user_id": "string",
"remarks": "string",
"token": 712341238
}

{
"header": {
"error_id": 0,
"error_desc": "success"
},
"body": {
"uniqueID": "497f6eca-1234-5678-bfeb-53cbbbba6f08",
"type": "DEFAULT",
"externalId": "string",
"scheme": "VISA",
"language": "en",
"challengeMethods": [],
"phoneNumbers": [],
"emails": [],
"enabled": true,
"biometricConsent": "GRANTED",
"description": "string",
"cardProgramId": "ec737f30-0c61-1234-5678-83d7c7b38b49",
"testable": true,
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
}

Create challenge profile

Used to create a challenge profile.

API schema available here.

{
  "api_call_unique_identifier": "438574845123456485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "name": "My Challenge Profile",
  "description": "string",
  "type": "V1",
  "alias": "string",
  "getproperties": {
    "choiceChallengeInterfaceId": "cf3604c5-29dc-4cb3-a4c0-123456d3a6f0",
    "allowFallback": false,
    "allowChoice": false,
    "allowChoiceOnFallback": false,
    "options": "object"
  }
}

{
  "api_call_unique_identifier": "438574841234567485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "name": "My Challenge Profile",
  "description": "string",
  "type": "V1",
  "alias": "string",
  "getproperties": {
    "choiceChallengeInterfaceId": "cf3604c5-29dc-4cb3-a4c0-123456d3a6f0",
    "allowFallback": false,
    "allowChoice": false,
    "allowChoiceOnFallback": false,
    "options": "object"
  }
}

Delete challenge profile

Used to delete an existing challenge profile.

API schema available here.

{
  "api_call_unique_identifier": "438574841234567485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "challengeProfileId": "497f6eca-6276-4993-bfeb-53ghehga6f08"
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {}
}

Disable card enrollment

Used to disable card enrollment, but not delete card enrollment.

API schema available here.

{
  "api_call_unique_identifier": "438574841234567485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "token": 123423128
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {}
}

Enable card enrollment

Used to enable or re-enable card enrolment.

API schema available here.

{
  "api_call_unique_identifier": "438512345670657485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "token": 123456728
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {}
}

Get challenge profile

Used to retrieve the challenge profile details.

API schema available here.

{
  "api_call_unique_identifier": "438574123456787485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "id": "09edhj7f-fe04-44ee-b187-agh567641a3e"
}

{
  "organisationId": "string",
  "financialInstitutionId": "string",
  "id": "string",
  "alias": "string",
  "name": "string",
  "type": "string",
  "version": 0,
  "description": "string",
  "properties": {
    "choiceChallengeInterfaceId": "cf3604c5-29dc-4cb3-a4c0-403ghj7896f0",
    "allowFallback": false,
    "allowChoice": false,
    "allowChoiceOnFallback": false,
    "options": "object"
  },
  "created": "string",
  "updated": "string"
}

List 3DS challenge methods

Used to list the challenge methods configured.

API schema available here.

{
  "api_call_unique_identifier": "438571234567857485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "count": 2,
  "prodId": 123,
  "nextToken": "eyJpZCI6GHYUInHkOTYyLTZmMzMtNDA0My1iHJYUGHYmOWIxNDYxNDdlMCJ9"
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {
    "challengeMethods": [
      {
        "id": "60d7bf59-718e-1234-ac5b-1a507e61cc30",
        "alias": "SMSOTP",
        "name": "My Challenge method",
        "description": "string",
        "challengeInterfaceId": "ed897acb-71b0-4b21-902e-123456787b5e",
        "retries": 5,
        "attempts": 1,
        "authMethodSettings": {
          "defaultValue": "60d7bf59-718e-1234-ac5b-1a507e61bb30",
          "matchers": [
            {
              "scheme": "MASTERCARD",
              "protocolVersion": "1.0.2",
              "value": "01"
            }
          ]
        },
        "created": "2022-04-27T07:02:07.000Z",
        "updated": "2022-04-27T07:02:07.000Z",
        "type": "SMS_OTP",
        "properties": {
          "choiceChallengeInterfaceId": "cf1234c5-29dc-4cb3-a4c0-123456d3a6f0",
          "allowFallback": false,
          "allowChoice": false,
          "allowChoiceOnFallback": false,
          "options": "object"
        }
      }
    ],
    "nexttoken": "eyJpZCI6hjumZjlmZDI5LTkwNjEtNDczMS1fguHJG4IxYTdiNhjuYHJ8OSJ9"
  }
}

Remove card from 3DS

Used to remove/delete a card that is enrolled in 3DS. Once this has been performed, a card would need to be re-enrolled in 3DS.

API schema available here.

{
  "api_call_unique_identifier": "438512345678657485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "token": 123456789
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {}
}

Update card data in 3DS

Used to update the card/cardholder data/metadata such as the below:

email
phone number
challenge methods
biometric consent
whether the card can be used for test transactions
challenge profile

API schema available here.

{
  "api_call_unique_identifier": "438574123456789485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "token": 123456789,
  "cardProgramId": "ec737f30-0c61-4383-9732-83d7c7b38b49",
  "language": "en",
  "email": "[email protected]",
  "phoneNumber": "00712336252",
  "challengeMethods": [
    {
      "ids": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "enabled": true,
  "biometricsConsent": "GRANTED",
  "testable": false,
  "3ds_challenge_profile": "950c886e-8eba-4465-8443-d22f1234gfY8"
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {
    "externalId": "string",
    "scheme": "VISA",
    "language": "en",
    "challengeMethods": [
      {
        "ids": "497f6eca-6276-1234-bfeb-53cbbbba6f08"
      }
    ],
    "phoneNumbers": [
      "string"
    ],
    "emails": [
      "string"
    ],
    "biometricConsent": "GRANTED",
    "cardProgramId": "ec737f30-0c61-4383-9732-8312345Gfb49",
    "challengeProfileId": "950c886e-8eba-4465-8443-d223456GyGf8"
  }
}

Update challenge profile

Used to update the challenge profile.

API schema available here.

{
  "api_call_unique_identifier": "438574123456787485",
  "client_id": 12345,
  "user_id": "string",
  "remarks": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbghyUGhy",
  "name": "My Challenge Profile",
  "description": "string",
  "properties": {
    "challenge_interface_id": "cf3604c5-29dc-4cb3-a4c0-123456h3a6f0",
    "allow_fallback": false,
    "allow_choice": false,
    "allow_choice_on_fallback": false,
    "options": [
      {
        "alias": "string",
        "choice_index": 0,
        "fallback_index": 0,
        "fallback_on_error": false,
        "challenge_method_ids": "497f6eca-6276-4993-bfeb-53ghgyuh&f08"
      }
    ]
  }
}

{
  "header": {
    "error_id": 0,
    "error_desc": "success"
  },
  "body": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "My Challenge Profile",
    "description": "string",
    "type": "V1",
    "alias": "string",
    "properties": {
      "choiceChallengeInterfaceId": "cf3604c5-29dc-4cb3-a4c0-403981d3a6f0",
      "allowFallback": false,
      "allowChoice": false,
      "allowChoiceOnFallback": false,
      "options": "object"
    },
    "created": "string",
    "updated": "string"
  }
}

Automated card management

The below APIs are not specific to 3DS, however, they act as automatic triggers if the card object is enrolled with Paymentology 3DS.

API	Purpose related to 3DS
Edit card holder details V2	When this API is used by for a card enrolled in Paymentology 3DS to update the email and/or phone number, this will also be updated in the ACS system.
Set card status V2	When this API is used to change a card status the following applies for a card enrolled in 3DS:
	1. 1199 (Void card - report DE39=05) - card is deleted/removed from 3DS via Remove card from 3DS API.
	2. if a card was previously disabled for 3DS and the card status is now updated to 1000 (fully operational DE39 = 00) - card is enabled for 3DS via Enable card enrollment.
	3. If any other card status - card is disabled from enrollment via Disable card enrollment.