Integration Flow
Integration Flow with Identiq
The following flow demonstrates a basic example of Authentication, Query, and Data APIs integration:
Step 1 - Authentication API
The first API call is the authentication call. Make sure you use the proper CLIENT_ID and CLIENT_SECRET.
Please be aware of the fact that Query API and Data API have two sets of keys ( CLIENT_ID and CLIENT_SECRET)
POST https://int-your-edge-url.identiq.cloud/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
Step 2 - Query API
The next call is for Query API. Call query API to receive the verification scores from Identiq before you make a decision within the flow. Use the access_token from the previous call.
Example request:
POST https://int-your-edge-url.identiq.cloud/v2.1/verifications
PAYLOAD
{
"queryParameters": {
"scores": [
"signup"
]
},
"entity": {
"account": {
"email": {
"address": "[email protected]"
},
"address": {
"phone": {
"number": "+1-701-592-0496",
"country": "US"
},
"firstName": "Stephaine",
"lastName": "Deckow",
"postCode": "06402",
"country": "US"
},
"ip": "163.205.127.88",
"device": "7643008f-302e-4653-85fc-8aa4f3fd8cbe"
}
}
}
Example response received:
{
"requestId": "28e48105-53a8-445d-bc73-9e258ebca184",
"scores": {
"guestPayment": {
"score": 0.9,
"status": 0
}
},
"fields": {
"transaction": {
"paymentMethod": {
"fieldScores": {
"score": 0.7,
"riskScore":0.1
},
"valid": true
},
"billingAddress": {
"phone": {
"fieldScores": {
"score": 0.7,
"riskScore":0.0
},
"valid": true
},
"firstName": {
"fieldScores": {
"score": 0.8,
"riskScore":0.0
},
"valid": true
},
"lastName": {
"fieldScores": {
"score": 0.8,
"riskScore":0.0
},
"valid": true
},
"postCode": {
"fieldScores": {
"score": 0.0,
"riskScore":0.0
},
"valid": true
},
"email": {
"fieldScores": {
"score": 0.7,
"riskScore":0.0
},
"valid": true
}
},
"ip": {
"fieldScores": {
"score": 0.7,
"riskScore":0.0
},
"valid": true
},
"device": {
"fieldScores": {
"score": 0.7,
"riskScore":0.0
},
"valid": true
}
}
}
}
Read more
Full API Reference Documentation for the Query API can be found here: Create and get a verification result
Step 3 - Data API
Call the Data API, after the success of a new account registration, account update, transaction completion, and transaction status updates.
The data API structure is similar to the Query API with additional properties indicating an event status and timestamp fields.
The example below illustrates a completed transaction event:
POST https://int-your-edge-url.identiq.cloud/v1/entity/events
PAYLOAD
[
{
"transaction": {
"transactionId": "72c1fd9d-de6c-4593"
"accountId": "71c3dd9d-de6c-4693-a11f-b3r18b417f6a",
"amount": 20.5,
"currencyCode": "USD",
"paymentMethod": {
"cardBin": "666666",
"cardLast4": "1234"
},
"billingAddress": {
"email": {
"address": "[email protected]",
"verified": false
},
"phone": {
"number": "+1 444-0100-123",
"country": "US"
},
"postCode": "98712",
"firstName": "Jane",
"lastName": "Doe"
},
"device": "cccc33322-h83k-7847-a964-3786948bc42b",
"ip": "98.20.185.15",
"status": "ok",
"timestamp": "2022-09-10T15:46:51Z"
}
}
]
Change of status notification
Below is an example of a fraudulent chargeback notification (status chargeback_fraud) - An update of the fraud event identified, should be sent via the Data API to Identiq, optimally as soon as it arrives.
POST https://int-your-edge-url.identiq.cloud/v1/entity/events
PAYLOAD
[
{
"transaction": {
"transactionId": "72c1fd9d-de6c-4593"
"accountId": "71c3dd9d-de6c-4693-a11f-b3r18b417f6a",
"amount": 20.5,
"currencyCode": "USD",
"paymentMethod": {
"cardBin": "666666",
"cardLast4": "1234"
},
"billingAddress": {
"email": {
"address": "[email protected]",
"verified": false
},
"phone": {
"number": "+1 444-0100-123",
"country": "US"
},
"postCode": "98712",
"firstName": "Jane",
"lastName": "Doe"
},
"device": "cccc33322-h83k-7847-a964-3786948bc42b",
"ip": "98.20.185.15",
"status": "chargeback_fraud",
"timestamp": "2022-09-10T15:46:51Z",
"originalTimestamp": "2022-08-10T15:46:51Z"
}
}
]
Response example:
{
"affectedRows": 1,
"invalidIds": []
}
Read more
Full API Reference Documentation for the Data API can be found here: Update Events
Updated 9 months ago