Payment integration
Overview
Incognia partners with Konduto to provide enriched fraud prevention models and rules for mobile payments.
Incognia's risk assessment relies on device identifiers, user-provided information like billing and/or shipping addresses, and location behavior collected by the Incognia SDK, which needs to be integrated with your mobile app to support the protection of your in-app payments.
Furthermore, the integration relies on updating your backend to send additional data to Konduto's Orders API.
Requirements
- An Incognia account. Contact us to get one.
- An app with the Incognia SDK initialized. Follow the SDK getting started guide for this.
- Contact your Konduto's Account Manager to activate the integration with Incognia.
Step-by-step
Setting the User ID on the app
In order to verify a payment attempt, Incognia needs to link a device and a unique account identifier. The Account ID is used for this purpose.
This association must happen in two moments:
1. Whenever the application initializes
This covers the scenario where the application is updated with the Incognia SDK and the user is already logged in. The Application.onCreate()
on Android and the [AppDelegate application:didFinishLaunchingWithOptions:]
on iOS are good places to do this.
If the Account ID is not available in those locations, it is important to forward the value to the Incognia SDK as soon as it is available. The important action here is to call setAccountId
whenever the application initializes so it is guaranteed that we always know that a specific user is associated with a specific device.
2. Whenever the user logs in and out
It is necessary to call the setAccountId
method when the user successfully logs in and clearAccountId
when the user logs out. This is usually done in the callback of these two actions.
- Kotlin
- Java
- Swift
- Objective-C
// Set the Account ID
Incognia.setAccountId(accountId)
// Set the Account ID
Incognia.setAccountId(accountId);
// Set the Account ID
ICGIncognia.setAccountId(accountId)
// Set the Account ID
[ICGIncognia setAccountId:accountId];
warning
Forwarding the device's Installation ID to your server
The Incognia SDK collects location and device data to build a behavioral profile for mobile users. This data is tagged with an identifier called Installation ID, which is automatically generated by the SDK.
To verify a payment attempt, Incognia needs to receive an Installation ID to identify the device from which the payment originates. Since Konduto will request the Incognia API to assess the risk of this payment, it needs to receive this information from your server along with the order info.
The installation ID can be forwarded to your server in two ways.
Option 1: Sending the Installation ID as a header
Before sending a payment request from your mobile application to your server, call Incognia.getInstallationId
and set its value as a header of the request. We encourage you to choose a clear name for this header, like Incognia-Installation-ID
, so you can easily identify it on the server-side.
This option has a clear benefit if your application will use more than one Incognia solution because you won't need to change each request's properties, like signup, login, payment, password change, etc.
- Kotlin
- Java
- Swift
- Objective-C
// This method may return null if the SDK has not yet been initialized or if an error occurs on initialization.
val installationId = Incognia.getInstallationId()
// HttpURLConnection
httpUrlConnection.setRequestProperty("Incognia-Installation-ID", installationId)
// Send the request with the installationId to your backend server
// This method may return null if the SDK has not yet been initialized or if an error occurs on initialization.
String installationId = Incognia.getInstallationId();
// HttpURLConnection
httpUrlConnection.setRequestProperty("Incognia-Installation-ID", installationId);
// Send the request with the installationId to your backend server
// This method may return nil if the SDK has not yet been initialized or if an error occurs on initialization.
let installationId = ICGIncognia.installationId()
// NSURLRequest
request.setValue(installationId, forHTTPHeaderField: "Incognia-Installation-ID")
// Send the request with the installationId to your backend server
// This method may return nil if the SDK has not yet been initialized or if an error occurs on initialization.
NSString *installationId = [ICGIncognia installationId];
// NSURLRequest
[request setValue:installationId forHTTPHeaderField:@"Incognia-Installation-ID"];
// Send the request with the installationId to your backend server
Option 2: Sending the Installation ID in the body of the request
Before sending the payment request from your mobile application to your server, call Incognia.getInstallationId
and send it as additional information about this payment. We suggest that you choose a clear name for this property like Incognia-Installation-ID
, so you can easily identify it on the server-side.
Handling the user's payment request
To evaluate a payment using Incognia, your server needs to request Konduto Order API informing that an order was placed alongside additional information, such as Incognia's Installation ID, the customer
, and the relevant addresses of the transaction (i.e., billing or shipping addresses).
important
Below is an example of a body request to Konduto Order API including Incognia's Installation ID:
{
"id":"ORD1837213",
"customer": {
"id":"28372"
// ... other fields
},
"external_device": {
"fingerprint": "incognia-installation-id"
},
"billing":{ },
"shipping":{ }
// ... other fields
}
Using the Incognia risk assessment
When your server makes a request to the Konduto Order API, it will receive a response like the following:
{
"status": "ok",
"order": {
"id": "ORD1837213",
"score": 0.07,
"ip": "189.68.156.100",
"recommendation": "review",
"status": "declined",
// ... other fields
}
For more details about the response, check Konduto's documentation: Understanding Konduto response. Incognia will be internally used by Konduto to enrich their fraud prevention models and rules, influencing their recommendation
and score
fields related to the analyzed order.
Wrapping Up
After these steps, your application is ready to increase conversions and reduce fraud for in-app mobile payments.