Skip to main content
Version: v6

Payments

Verify payments by analyzing the behavioral pattern of each user and matching it to in-app payments history. Payments initiated at unfamiliar locations will increase the Incognia risk score and can be used to trigger step-up authentication.

We secure digital payments by matching the historical location fingerprint and the payments history of the initiating user, to their real-time location. Payments initiated at unfamiliar locations will result in a higher risk score. In-store payments are secured when we match the user's real-time location with the indicated store.

Assess new payment

POST
https://api.incognia.com/api/v2/authentication/transactions

This method registers a new payment for the given installation with the available information, returning a risk assessment and the evidence behind it.

Headers

Content-TypestringRequiredapplication/JSON
AuthorizationstringRequiredBearer token generated in Authenticating section.

Body Parameters

external_idstringOptionalClient provided payment identifier which can be used for providing later feedbacks.
installation_idstringRequiredInstallation ID of the device from which the signup originates.
typestringRequiredType of the assessment. The payment type is supported.
account_idstringRequiredID of the user account performing the payment.
addressesarrayOptionalList of addresses related to the payment may be given. Address types supported are shipping, billing and home. At least one of address_coordinates or structured_address are required when declaring an address. Incognia recommends declaring both fields, which should refer to the same location.
payment_valueobjectOptional Value and currency of the transaction.
payment_methodsarrayOptionalMethods used for paying (such as credit and debit card), along with extra information about each method, such as BIN and expiry dates for cards for example.
{
"installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
"account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
"type": "payment",
"external_id": "3720e8ad9047dd39466b3c8974e592c2fa383d4ac3ab8ff1"
}

Sample cURL:

curl -XPOST -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d @body.json "https://api.incognia.com/api/v2/authentication/transactions"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response fieldTypeDescription
idstringUnique identifier for the payment event.
risk_assessmentenumThe risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasonsarrayThe reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidenceobjectThe supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_idstringUnique identifier for the user's device.

Register a new payment without evaluating it

To register a payment without evaluating its risk assessment, add the ?eval=false query parameter. The full URL becomes:

https://api.incognia.com/api/v2/authentication/transactions?eval=false

Turning off the risk assessment evaluation allows you to register a new payment, but the response will be an empty JSON (i.e., {}). For instance, if you're using the risk assessment only for some payment transactions you still should register all the other ones: this will avoid any bias on the risk assessment computation.

Coming soon: get the latest payment assessment

GET
https://api.incognia.com/api/v2/authentication/transactions/{id}

This method allows you to query the latest assessment for a given payment event, identified by its id.

Warning: This endpoint is coming soon. Please consult Incognia's team before using it.

Path Parameters

idstringRequiredPayment ID of the event whose assessment is being queried.

Headers

AuthorizationstringRequiredBearer token generated in Authenticating section.

Sample cURL:

curl -H "Authorization: Bearer <token>" "https://api.incognia.com/api/v2/authentication/transactions/<id>"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response fieldTypeDescription
idstringUnique identifier for the payment event.
risk_assessmentenumThe risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasonsarrayThe reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidenceobjectThe supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_idstringUnique identifier for the user's device.