Guides
Home

Integration Flow

The following flow demonstrates a basic example of Identiq API Authentication, Credit Card authorization and 3-D Secure analysis integration.

Suggest Edits

API Categories

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

Credit 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 (pre-3ds-req): Provides an optimized 3DS payload for authentication requests in real-time.
  • Post-3DS Response API (post-3ds-res): Collects the full 3DS request and response details after completion for reporting and analysis.
    Each endpoint must include the target acquirer bank or 3DS provider ID, as PSPs may work with multiple partners

Integration Phases

Phase 1 - Authenticate to Obtain API Key

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

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: PSP or acquirer credentials.
  • Output: API key and secret for secure access.
POST https://api.identiq.cloud/v1/oauth/token


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

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

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

📘

Read more

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

Phase 2 - Post 3DS Authentication Update

After the 3DS authentication process is completed, update our system with both the original request and the response details. Each endpoint must include the target acquirer bank or 3DS provider ID, as PSPs may work with multiple partners. Use the access_token from the previous call.

  • Endpoint: /api/v1/psp/post3ds/[vendor]
  • Expected Input: Full 3DS request and response data, including transaction status and relevant metadata.

Example request:

POST https://api.identiq.cloud/api/v1/psp/post3ds/gpayments

{
  "metadata": {
    "identiq_session_id": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
    "session_id": "session_1234",
    "event_Timestamp": "2024-10-06T14:23:45Z",
    "merchant_Name": "best commerce",
    "merchant_id": "123",
    "mcc": "50"
  },
  "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"
  }
}

📘

Read more

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

Phase 3 - Post Credit Card Authorization Update

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

Endpoint: /api/v1/psp/postauth/[acquirer]

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

Example: 

POST https://api.identiq.cloud/api/v1/psp/postauth/ecp

{
  "metadata": {
    "identiq_session_id": "a4aa4ef7-5b33-4ab6-98df-8e354267f8eb",
    "session_id": "session_1234",
    "event_Timestamp": "2024-10-06T14:23:45Z",
    "merchant_Name": "best commerce",
    "merchant_id": "123",
    "mcc": "50",
    "pspResponse_code": ""
  },
  "auth": {
    "request": {
      "payment_transaction": {
        "transaction_type": "sale3d",
        "transaction_id": "ABqbP8aZ",
        "usage": "40208 concert tickets",
        "remote_ip": "245.253.2.12<",
        "amount": "4898",
        "currency": "EUR",
        "card_holder": "Travis Trump",
        "card_number": "453304XXXXXX3333",
        "expiration_month": "11",
        "expiration_year": "2025",
        "cvv": "123",
        "customer_email": "[email protected]",
        "customer_phone": "+1987987987987",
        "business_attributes": {
          "event_start_date": "17-10-2024",
          "event_end_date": "27-10-2024",
          "event_organizer_id": "20192375",
          "event_id": "1912"
        },
        "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"
        },
        "sca_params": {
          "exemption": "trusted_merchant",
          "visa_merchant_id": "00000000"
        },
        "crypto": "false"
      }
    },
    "response": {
      "payment_response": {
        "transaction_type": "authorize",
        "status": "approved",
        "mode": "live",
        "transaction_id": "119643250547501c79d8295",
        "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",
        "descriptor": "Descriptor one",
        "amount": "100",
        "currency": "USD",
        "sent_to_acquirer": true,
        "scheme_transaction_identifier": "019091214161031",
        "scheme_transaction_link_id": "TLINKIDENTIFIER4521412",
        "scheme_settlement_date": "0917",
        "scheme_response_code": "00",
        "reason_for_not_honoring_exemption": "8A01",
        "sca_exemption_result": "13",
        "code": "340",
        "technical_message": "expiration_year is invalid",
        "message": "expiration_year is invalid",
        "account_owner": {
          "first_name": "Travis",
          "middle_name": "Joe",
          "last_name": "Pastrana"
        }
      }
    }
  }
}

📘

Read more

Full API Reference Documentation for the post authorization response API can be found here: post auth

Phase 4: Real-Time 3DS Optimization (Pre-3DS Request)

Use this API to obtain an optimized 3DS payload in real-time before initiating a 3DS authentication request with the network.

Examples will be added soon.

Phase 5: Real-Time Credit Card Authorization Optimization (Pre-Auth Request)

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

Examples will be added soon.

Example Flow

  • Authenticate: Call authentication-api to receive your API key and secret.
  • Post-3DS Response: After each 3DS transaction, call post-3ds-res with the full request and response details.
  • Post-Authorization Response: After each authorization transaction, call post-auth-res with the complete request and response data.
  • Pre-3DS Request: Before initiating a 3DS authentication, call pre-3ds-req to receive the optimized payload
  • Pre-Authorization Request: Before processing a card authorization, call pre-auth-req to receive the optimized payload.

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

Updated 2 months ago