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
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.
- Request
- Response
Headers
| Content-Type | string | Required | application/JSON |
| Authorization | string | Required | Bearer token generated in Authenticating section. |
Body Parameters
| external_id | string | Optional | Client provided payment identifier which can be used for providing later feedbacks. |
| installation_id | string | Required | Installation ID of the device from which the signup originates. |
| type | string | Required | Type of the assessment. The payment type is supported. |
| account_id | string | Required | ID of the user account performing the payment. |
| addresses | array | Optional | List 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_value | object | Optional | Value and currency of the transaction. |
| payment_methods | array | Optional | Methods 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. |
200: OK
The payment was assessed successfully
{
"id": "dfe1f2ff-8f0d-4ce8-aed1-af8435143044",
"device_id": "HcXQff4DRBtyIaTaYBat_SxP6fOzp_48V_oEaGm84g3LC7c4mg4JOcE0rYUT7He5QY6uZZcLfNRcphQVmfC6CA",
"risk_assessment": "low_risk",
"reasons": [
{
"code": "machine_learning_model",
"source": "local"
}
],
"evidence": {
// For a complete explanation of this part of the response,
// please refer to the evidence page in the docs.
"device_model": "Moto Z2 Play",
"known_account": true,
"location_services": {
"location_permission_enabled": true,
"location_sensors_enabled": true
},
"device_integrity": {
"probable_root": false,
"emulator": false,
"gps_spoofing": false,
"from_official_store": true
},
"device_fraud_reputation": "unknown",
"device_behavior_reputation": "allowed",
"accessed_accounts": 1,
"app_reinstallations": 2,
"distance_to_trusted_location": 21.06295635345013,
"last_location_ts": "2022-11-01T22:45:53.299Z",
"sensor_match_type": "gps",
"addresses": [
{
"type": "shipping",
"location_events_near_address": 43,
"address_quality": "good",
"geocode_quality": "good",
"address_match": "street",
"chargeback_rate_near_150_meters": 0.01,
"chargeback_rate_near_1500_meters": 0.03,
"chargeback_rate_near_5000_meters": 0.05
}
],
"location_events_quantity": 62,
"device_transaction_sum": [
{
"amount": 1024.00,
"currency": "BRL"
},
{
"amount": 256.00,
"currency": "USD"
}
],
"first_device_login": false,
"first_device_login_at": "2022-01-07T10:45:53.299Z"
}
}
400: Bad Request
The request was malformed (missing required fields, invalid fields). The response body will contain error details.
{
"errors": [
"missing installation_id"
]
}
403: Forbidden
The provided token does not have the required permissions.
Empty.
500: Internal Server Error
Some internal error happened. Try again or, if the problem persists, contact us.
Empty.
- Sample payment request with external_id
- Sample payment request with all body parameters
{
"installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
"account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
"type": "payment",
"external_id": "3720e8ad9047dd39466b3c8974e592c2fa383d4ac3ab8ff1"
}
{
"installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
"account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
"type": "payment",
"addresses": [
{
"type": "shipping",
"structured_address": {
"locale": "pt-BR",
"country_name": "Brasil",
"country_code": "BR",
"state": "SP",
"city": "São Paulo",
"borough": "",
"neighborhood": "Bela Vista",
"street": "Av. Paulista",
"number": "1578",
"complements" : "Andar 2",
"postal_code": "01310-200"
},
"address_coordinates": {
"lat": -23.561414,
"lng": -46.6558819
}
}
],
"payment_value": {
"amount": 5.0,
// Currency must conform to ISO 4217
"currency": "BRL"
},
"payment_methods": [
{
"type": "credit_card",
"credit_card_info": {
"bin": "123456",
"last_four_digits": "1234",
"expiry_year": "2027",
"expiry_month": "10"
}
},
{
"type": "debit_card",
"debit_card_info": {
"bin": "123456",
"last_four_digits": "1234",
"expiry_year": "2027",
"expiry_month": "10"
}
}
]
}
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 field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the payment event. |
| risk_assessment | enum | The risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments. |
| reasons | array | The reasons for the risk assessment. For more information refer to Understanding risk assessments. |
| evidence | object | The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments. |
| device_id | string | Unique 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
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.
- Request
- Response
Path Parameters
| id | string | Required | Payment ID of the event whose assessment is being queried. |
Headers
| Authorization | string | Required | Bearer token generated in Authenticating section. |
200: OK
The submission is successful.
{
"id": "dfe1f2ff-8f0d-4ce8-aed1-af8435143044",
"device_id": "HcXQff4DRBtyIaTaYBat_SxP6fOzp_48V_oEaGm84g3LC7c4mg4JOcE0rYUT7He5QY6uZZcLfNRcphQVmfC6CA",
"risk_assessment": "low_risk",
"reasons": [
{
"code": "machine_learning_model",
"source": "local"
}
],
"evidence": {
// For a complete explanation of this part of the response,
// please refer to the evidence page in the docs.
"device_model": "Moto Z2 Play",
"known_account": true,
"location_services": {
"location_permission_enabled": true,
"location_sensors_enabled": true
},
"device_integrity": {
"probable_root": false,
"emulator": false,
"gps_spoofing": false,
"from_official_store": true
},
"device_fraud_reputation": "unknown",
"device_behavior_reputation": "allowed",
"accessed_accounts": 1,
"app_reinstallations": 2,
"distance_to_trusted_location": 21.06295635345013,
"last_location_ts": "2022-11-01T22:45:53.299Z",
"sensor_match_type": "gps",
"addresses": [
{
"type": "shipping",
"location_events_near_address": 43,
"address_quality": "good",
"geocode_quality": "good",
"address_match": "street",
"chargeback_rate_near_150_meters": 0.01,
"chargeback_rate_near_1500_meters": 0.03,
"chargeback_rate_near_5000_meters": 0.05
}
],
"location_events_quantity": 62,
"device_transaction_sum": [
{
"amount": 1024.00,
"currency": "BRL"
},
{
"amount": 256.00,
"currency": "USD"
}
],
"first_device_login": false,
"first_device_login_at": "2022-01-07T10:45:53.299Z"
}
}
403: Forbidden
The provided token does not have the required permissions.
Empty.
404: Not Found
We were unable to find the given Sign Up event assessment in our database. Please check the given id.
Unable to find the given sign up id.
500: Internal Server Error
Some internal error happened. Try again or, if the problem persists, contact us.
Empty.
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 field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the payment event. |
| risk_assessment | enum | The risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments. |
| reasons | array | The reasons for the risk assessment. For more information refer to Understanding risk assessments. |
| evidence | object | The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments. |
| device_id | string | Unique identifier for the user's device. |