API Categories

Identiq Authentication API: Obtain API key and secret for secure access to our services.

Card Authorization APIs:

Pre-Auth Request API (pre-auth-req): Retrieves an optimized authorization payload in real-time for PSPs and acquirers to send to card networks.
Post-Auth Response API (post-auth-res): Collects the full authorization request and response details after completion for analysis and reporting.

3DS Authentication APIs:

Pre-3DS Request API (Coming soon): Retrieves an optimized 3DS authentication request (AREQ) payload in real-time
Post-3DS Response API (post-3ds-res): Collects the full 3DS request and response details after completion for reporting and analysis.

📘
API Endpoint
Each endpoint must include the target acquirer bank or 3DS provider ID, as PSPs may work with multiple partners. Make sure you call the correct endpoint.

Example Flow

Authenticate: Call the Identiq authentication-api to receive your API key and secret.
Prepare Metadata object: Prepare a set of metadata required for Identiq API calls such as the merchant details
Post-3DS Response: After each 3DS transaction, call post-3ds-res with the full request and response details. This is an optional step that is only required for transactions who passed thought 3DS authentication
Pre-Authorization Request: Before processing a card authorization, call pre-auth-req to receive the optimized payload.
Post-Authorization Update: After each authorization transaction, call post-auth-res with the complete request and response data.

Quick Integration Guide

1 - Obtain API Key

Identiq is using the OAuth 2 authorization framework. Call the authentication API with your credentials to receive an API key and secret for future requests.

When you call the authentication API, you will receive both an access token and a refresh token. The refresh token is a long-lived credential, which includes a TTL (time-to-live) value indicating its expiration. It’s important to refresh the token before it expires to maintain continuous access, allowing you to request a new access token without needing to re-authenticate with your credentials.

Make sure you use the proper CLIENT_ID and CLIENT_SECRET.

Expected Input: API user credentials.
Output: API key and secret for secure access.

Example request and response:


{
    
     "audience": "https://identiq.com/v1/api",
     "client_id": "CLIENT_ID",
     "client_secret": "CLIENT_SECRET",
     "grant_type": "client_credentials"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik0wVXhSakV3UmtNMk9UTTBSa1pCT1VFMlJUSkNOREJEUkRKRFFUbEZOVEJET0RZM016azVSZyJ9.eyJodHRwczovL2lkZW50aXEuY29tL3RlbmFudCI6IkxBWk5lcU14VFJubGs1blRheTlaIiwiaXNzIjoiaHR0cHM6Ly9pZGVudGlxLXByb3RvY29sLmF1dGgwLmNvbS8iLAbBmSc2JltKukrmRtrdjo1lH7O6GZb04IlOOKUzFzFnK1Gp9g1s55c4asqY_uTukLXLGExO56V-gDT_uPVf4UBMvu-9EAfXU1Z4iA6GnIrQud9GcORfi3x4R2gqGgQWRf1AAc87FoTDRZdi-RMyug",
  "token_type": "Bearer",
  "expires_in": 63211,
  "scope": "create:verification read:verification"
}

In the response, you will receive the access token which needs to be cached for the next few hours (expires_in provides the number of seconds until the token is expired).

📘
Read more
Full API Reference Documentation for the Authentication API can be found here: Token

2 - Prepare Metadata

Prepare the set of metadata required for Identiq requests, as this object is used throughout Pre-Auth and Post-Auth requests. The metadata includes:

{
 		"identiqSessionId": "5da42ghghg",
    "partnerPaymentId": "uV7qelQg",
    "merchantName": "Commerce Records",
    "merchantId": "15483",
    "merchantCountry": "US",
    "mcc": "8944",
    "recurringType":"initial"
}

NOTE: an identiqSessionId is required to identify all calls the belong to the same payment sequence. If no session id is provided, it will be generated on the first call in the sequence. Future calls belonging to the same sequence must include the same session_id to allow events to be linked to each other. See details below.

Field	Description
partnerPaymentId	The transaction identifier used by the partner to track the payment. If multiple events are associated with this transaction (such as 3DS authentication, authorization, etc.), this ID should remain consistent across all events.
identiqSessionId	A unique identifier generated by Identiq for each transaction flow. The session ID should be included in all subsequent calls after it is first generated. see 'Identiq Session ID Handling' below for more information.
merchantId	The identifier for the merchant as recognized by the partner, ideally consistent across different acquirers.
merchantName	The name of the merchant.
merchantCountry	The country where the merchant is registered.
MCC	The merchant category code (MCC) associated with the merchant within the specific acquirer.
partnerResponseCode	Used only in Post-Auth and Post-3DS requests. This represents the internal transaction status as translated by the partner based on schema and acquirer reason codes
recurringType	Specifies whether the transaction is non-recurring, recurring initial, or recurring subsequent

Identiq Session ID Handling

A session ID is a unique identifier generated by Identiq for each transaction flow.
It ensures consistency across all Identiq API calls related to a specific payment attempt.
The session ID should be included in all subsequent calls after it is first generated.

When is the Session ID Created?

The session ID is first generated on the first API call to Identiq in a given transaction flow.
The first Pre-3DS or Pre-Auth call will generate the session ID.

How to Use the Session ID?

The session ID should be included in all subsequent API calls related to the transaction.

API Call	Session ID Generation
Pre-3DS Request	(coming soon)
Pre-Auth Request	First call generates session ID
Post-3DS Update	Requires session ID
Post-Auth Update	Requires session ID

3 - Update 3DS outcome

After completing 3D Secure authentication, update Identiq with the authentication outcome.
The session ID must be included to link the update to the correct transaction flow.
Each endpoint must include the target 3DS provider ID, as PSPs may work with multiple partners. Use the access_token from the previous call.

Expected Input: Full 3DS request and response data, including authentication status and relevant metadata.

👍
Pass the Authentication Payloads As-Is
Ensure that the payment payload is sent to Identiq exactly as it will be submitted to, or had been received from the 3DS vendor without any modifications.

Example request and response:


{
  "metadata": {
 		"identiqSessionId": "",
    "partnerPaymentId": "session_1234",
    "merchantName": "best commerce",
    "merchantId": "123",
    "mcc": "50",
    "recurringType":"initial",
    "partnerResponseCode": "0"
  },
  "request": {
    "acctID": "ActiveServer 3DS Test Account 000000001",
    "acctInfo": {
      "chAccAgeInd": "03",
      "chAccChange": "20160712",
      "chAccChangeInd": "04",
      "chAccDate": "20140328",
      "chAccPwChange": "20170328",
      "chAccPwChangeInd": "02",
      "nbPurchaseAccount": "11",
      "paymentAccAge": "20160917",
      "paymentAccInd": "04",
      "provisionAttemptsDay": "3",
      "shipAddressUsage": "20160714",
      "shipAddressUsageInd": "04",
      "shipNameIndicator": "02",
      "suspiciousAccActivity": "01",
      "txnActivityDay": "1",
      "txnActivityYear": "21"
    },
    "acctNumber": "7654310438720050",
    "acctType": "03",
    "authenticationInd": "01",
    "authenticationInfo": {
      "threeDSReqAuthData": "validlogin at UL TS BV",
      "threeDSReqAuthMethod": "02",
      "threeDSReqAuthTimestamp": "201711071307"
    },
    "browserInfo": "eyJicm93c2VyQWNjZXB0SGVhZGVyIjoidGV4dC9odG1sLGFwcGxpY2F0aW9uL3hodG1sK3htbCxhcHBsaWNhdGlvbi94bWw7cT0wLjksKi8qO3E9MC44IiwiYnJvd3NlcklQIjoiMTkyLjE2OC4xLjExIiwiYnJvd3NlckphdmFFbmFibGVkIjpmYWxzZSwiYnJvd3Nlckxhbmd1YWdlIjoiZW4iLCJicm93c2VyQ29sb3JEZXB0aCI6IjQ4IiwiYnJvd3NlclNjcmVlbkhlaWdodCI6IjQwMCIsImJyb3dzZXJTY3JlZW5XaWR0aCI6IjYwMCIsImJyb3dzZXJUWiI6IjAiLCJicm93c2VyVXNlckFnZW50IjoiTW96aWxsYS81LjAgKFdpbmRvd3MgTlQgNi4xOyBXaW42NDsgeDY0OyBydjo0Ny4wKSBHZWNrby8yMDEwMDEwMSBGaXJlZm94LzQ3LjAifQ",
    "browserInfoCollected": {
      "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "browserColorDepth": 48,
      "browserIP": "192.168.1.11",
      "browserJavaEnabled": false,
      "browserJavascriptEnabled": true,
      "browserLanguage": "en",
      "browserScreenHeight": 400,
      "browserScreenWidth": 600,
      "browserTZ": 0,
      "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
    },
    "cardExpiryDate": "1910",
    "cardHolderInfo": {
      "addrMatch": "Y",
      "billAddrCity": "Bill City Name",
      "billAddrCountry": "840",
      "billAddrLine1": "Bill Address Line 1",
      "billAddrLine2": "Bill Address Line 2",
      "billAddrLine3": "Bill Address Line 3",
      "billAddrPostCode": "Bill Post Code",
      "billAddrState": "CO",
      "cardholderName": "Cardholder Name",
      "email": "[email protected]",
      "homePhone": {
        "cc": "123",
        "subscriber": "123456789"
      },
      "mobilePhone": {
        "cc": "123",
        "subscriber": "123456789"
      },
      "shipAddrCity": "Ship City Name",
      "shipAddrCountry": "840",
      "shipAddrLine1": "Ship Address Line 1",
      "shipAddrLine2": "Ship Address Line 2",
      "shipAddrLine3": "Ship Address Line 3",
      "shipAddrPostCode": "Ship Post Code",
      "shipAddrState": "CO",
      "workPhone": {
        "cc": "123",
        "subscriber": "123456789"
      }
    },
    "challengeInd": "02",
    "forceMessageVersion": true,
    "merchantId": "1234567890123456789012345678901234",
    "merchantName": "Test Merchant",
    "merchantOverride": {
      "acquirerBIN": "123456",
      "mcc": "1234",
      "threeDSRequestorID": "GP_123456789",
      "threeDSRequestorName": "Test Merchant"
    },
    "merchantRiskIndicator": {
      "deliveryEmailAddress": "[email protected]",
      "deliveryTimeframe": "01",
      "giftCardAmount": "337",
      "giftCardCount": "02",
      "giftCardCurr": "840",
      "preOrderDate": "20170519",
      "preOrderPurchaseInd": "02",
      "reorderItemsInd": "01",
      "shipIndicator": "02"
    },
    "messageCategory": "01",
    "messageExtension": [
      {
        "criticalityIndicator": false,
        "data": {
          "A000000004-merchantData": {
            "scaExemptions": "05",
            "merchantFraudRate": "1",
            "acquirerCountryCode": "050",
            "secureCorporatePayment": "Y"
          }
        },
        "id": "A000000004-merchantData",
        "name": "Merchant Data"
      }
    ],
    "messageVersion": "2.2.0",
    "priorAuthenticationInfo": {
      "threeDSReqPriorAuthData": "validlogin at UL TS BV",
      "threeDSReqPriorAuthMethod": "02",
      "threeDSReqPriorAuthTimestamp": "201711071307",
      "threeDSReqPriorRef": "375d8b16-9e97-48ca-a3c2-cddb8268939c"
    },
    "purchaseAmount": "12345",
    "purchaseCurrency": "978",
    "purchaseDate": "20180122153045",
    "purchaseInstalData": "024",
    "recurringExpiry": "20180131",
    "recurringFrequency": "2",
    "threeDSRequestorDecMaxTime": "00010",
    "threeDSRequestorDecReqInd": "Y",
    "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
    "transType": "03",
    "whiteListStatus": "Y"
  },
  "response": {
    "acsChallengeMandated": "Y",
    "acsDecConInd": "N",
    "acsReferenceNumber": "3DS_GP_ACS_201_13579",
    "acsTransID": "375d90ad-3873-498b-9133-380cbbc8d99d",
    "amexDsTransID": "020100006afa60729412446b96732f98b3ee98a2",
    "authenticationType": "02",
    "authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
    "cardholderInfo": "Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.",
    "challengeUrl": "https://api.demo.activeserver.cloud/api/v2/brw/challenge/init?txid=6afa6072-9412-446b-9673-2f98b3ee98a2",
    "dsReferenceNumber": "3DS_GP_DS_201_13579",
    "dsTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
    "eci": "02",
    "messageVersion": "2.1.0",
    "resolvedCardScheme": "VISA",
    "resultMonUrl": "https://api.demo.activeserver.cloud/api/v2/brw/result/mon?t=6afa6072-9412-446b-9673-2f98b3ee98a2",
    "threeDSServerTransID": "6afa6072-9412-446b-9673-2f98b3ee98a2",
    "transStatus": "Y",
    "transStatusReason": "11",
    "whiteListStatus": "Y",
    "whiteListStatusSource": "03"
  }
}

{ 
  "success": true,
    "metadata": {
    "identiq_session_id": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
  },
}

📘
Read more
Full API Reference Documentation for the post 3DS response API can be found here: Post 3ds

4 - Optimize Card Authorization

4.a Pre-Auth Optimization Request

Obtain an optimized authorization payload in real-time before sending the transaction to the acquirer.

📘
Session ID
If this is the first request in the transaction flow, Identiq will generate a session ID and return it.
The session ID should be included in all subsequent calls related to this transaction.

Expected Input: The authorization payload that needs to be optimized before being sent to the acquirer/network for approval, along with the metadata object.
Output: An optimized payload to be sent to the acquirer/network, along with additional metadata indicating the optimization flow applied.

👍
Pass the Payment Payload As-Is
Ensure that the payment payload is sent exactly as it will be submitted to the acquirer or network—without any modifications. Identiq will optimize the payload and return it in the same format, ready for submission. This ensures seamless integration, prevents mismatches, and maintains compliance with acquirer requirements.

Examples request and response:

{
  "metadata": {
    "identiqSessionId": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
    "partnerPaymentId": "uV7qelQg",
    "merchantName": "Commerce Records",
    "merchantId": "15483",
    "merchantCountry": "US",
    "mcc": "8944",
    "recurringType":"initial"
  },
  "request": {
    "transaction_type": "sale3d",
    "transaction_id": "55487lQg",
    "amount": "5500",
    "currency": "USD",
    "card_holder": "Linden Billy",
    "card_number": "425603XXXXXX1234",
    "expiration_month": "1",
    "expiration_year": "30"
  }
}
'

{
  "metadata": {
    "optimizationGroup": "test",
    "hasChanged": true,
    "outcome": "Request processed successfully",
    "identiqSessionId": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
    "changedKeys": ["card_holder"]
  },
  "request": {
    "transaction_type": "sale3d",
    "transaction_id": "55487lQg",
    "amount": "5500",
    "currency": "USD",
    "card_holder": "BILLY LINDEN",
    "card_number": "425603XXXXXX1234",
    "expiration_month": "1",
    "expiration_year": "30"
  }
}

Response will include two main objects:

Request object - The 'request' object will include the optimized payload.
Response Metadata - Identiq includes specific metadata fields in responses to Pre-Auth and Pre-3DS requests:

Field	Description
optimizationGroup	Indicates test/control/out-of-scope allocation
hasChanged	Indicates whether the requested payload was optimized and altered (true/false)
changedKeys	Lists all fields that were modified during the optimization process.
outcome	Status of the optimization request (e.g., "Request processed successfully")
identiqSessionId	The unique identifier for the transaction generated by Identiq when flow initiated

📘
Read More
Full API Reference Documentation for the pre authorization API per acquirer, can be found here: Pre-Auth

4.b Post Card Authorization Update

Once a payment has been authorized, send a final update to Identiq.
The session ID must be included to ensure the transaction data remains linked.

Similar to the 3DS post-processing API, this captures the entire request and response details after the card authorization process. It is used solely for reporting and analysis.

Expected Input: Full authorization request and response data, including final status.

Example request and response:

{
  "metadata": {
    "identiqSessionId": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
    "partnerPaymentId": "session_1234",
    "merchantName": "best commerce",
    "merchantId": "123",
    "mcc": "50",
    "recurringType":"initial",
    "partnerResponseCode": "0"
  },
  "auth": {
    "request": {
      "payment_transaction": {
        "transaction_type": "sale3d",
        "transaction_id": "ABqbP8aZ",
        "amount": "100",
        "currency": "EUR",
        "card_holder": "Travis Trump",
        "card_number": "453304XXXXXX3333",
        "expiration_month": "11",
        "expiration_year": "2025",
        "customer_email": "[email protected]",
        "customer_phone": "+1987987987987",
        "billing_address": {
          "first_name": "Travis",
          "last_name": "Trump",
          "address1": "5rue augustes bl",
          "zip_code": "10178",
          "city": "Los Angeles",
          "neighborhood": "Hollywood",
          "state": "CA",
          "country": "US"
        },
        "moto": "false",
        "mpi_params": {
          "eci": "05",
          "cavv": "AAgCBIcWMAAAABMil4JSdQAAAAA=",
          "protocol_version": "2",
          "protocol_sub_version": "2",
          "directory_server_id": "2b3b30b9-2168-4d76-8c71-919b9b585c7b",
          "acs_transaction_id": "7f219820-56fe-013d-2288-0a58a9feac02",
          "threeds_challenge_indicator": "preference"
        },
      }
    },
    "response": {
      "payment_response": {
        "transaction_type": "authorize",
        "status": "approved",
        "mode": "live",
        "transaction_id": "ABqbP8aZ",
        "unique_id": "44177a21403427eb96664a6d7e5d5d48",
        "consumer_id": "123456",
        "token": "ee946db8-d7db-4bb7-b608-b65b153e127d",
        "avs_response_code": "5I",
        "avs_response_text": "Response provided by issuer processor; Address information not verified",
        "cvv_result_code": "M",
        "authorization_code": "345678",
        "retrieval_reference_number": "016813015184",
        "payment_account_reference": "50019P9LBXOLHN9G7QMU5VN520YSY",
        "response_code": "00",
        "timestamp": "2024-09-16T08:40:59Z",
        "amount": "100",
        "currency": "EUR",
        "scheme_response_code": "00",
        "sca_exemption_result": "13"
      }
    }
  }
}

{
  "success": true
}

📘
Read more
Full API Reference Documentation for the post authorization response API per acquirer can be found here: post auth

Key Notes

Targeted Endpoints: Specify the target acquirer bank or 3DS provider in each API call to support routing and reporting.
Response Handling: In post-* APIs, submit both the original request and the final response for

Integration Flow

API Categories

📘
API Endpoint

Example Flow

Quick Integration Guide

1 - Obtain API Key

📘
Read more

2 - Prepare Metadata

Identiq Session ID Handling

When is the Session ID Created?

How to Use the Session ID?

3 - Update 3DS outcome

👍
Pass the Authentication Payloads As-Is

📘
Read more

4 - Optimize Card Authorization

4.a Pre-Auth Optimization Request

📘
Session ID

👍
Pass the Payment Payload As-Is

📘
Read More

4.b Post Card Authorization Update

📘
Read more

Key Notes

API Categories

📘API Endpoint

Example Flow

Quick Integration Guide

1 - Obtain API Key

📘Read more

2 - Prepare Metadata

Identiq Session ID Handling

When is the Session ID Created?

How to Use the Session ID?

3 - Update 3DS outcome

👍Pass the Authentication Payloads As-Is

📘Read more

4 - Optimize Card Authorization

4.a Pre-Auth Optimization Request

📘Session ID

👍Pass the Payment Payload As-Is

📘Read More

4.b Post Card Authorization Update

📘Read more

Key Notes

📘
API Endpoint

📘
Read more

👍
Pass the Authentication Payloads As-Is

📘
Read more

📘
Session ID

👍
Pass the Payment Payload As-Is

📘
Read More

📘
Read more