Skip to main content
Version: v6

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.

// Set the Account ID
Incognia.setAccountId(accountId)

warning
While data such as e-mail and phone numbers are examples of identifiers, their use in the SDK is forbidden. Consider using non-personal information, such as UUIDs, and Hashing to securely generate and set the User ID.

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.

// 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

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
Even though the addresses are an optional parameter, the risk assessment quality is greatly enhanced by its addition.

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.