Skip to main content
Version: v6

Protecting in-app payments

In this how-to, you will learn how to integrate the Incognia Transaction API to recognize trusted customers, increase conversions and reduce fraud for in-app mobile payments. You will be able to automatically assess the risk of payment events and review or decline suspicious ones.

Requirements#

Step-by-step#

Setting the Account ID on the app#

In order to verify a payment attempt, Incognia needs to have an association between a device and a unique account identifier. The Account ID is used for this purpose.

To make this association, call the Incognia.setAccountId method whenever a user is authenticated and a user identifier is available on your application and a Incognia.clearAccountId when the user logs out.

// Set the Account IDIncognia.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 Account ID.

Forwarding the device's Installation ID to your server#

To verify a login attempt, Incognia needs to receive an Installation ID to identify the device from which the login originates. Since your server will request the Incognia API to assess the risk of this login, it needs to receive this information from your mobile application.

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()
// HttpURLConnectionhttpUrlConnection.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#

When your server receives a payment request, you can use Incognia intelligence to assess the risk of this new transaction inside this request/response cycle.

To evaluate a payment, your server needs to request our Transaction API informing that a payment was made, alongside its Installation ID, the Account ID, and the relevant addresses of the transaction, such as the home, billing, or shipping addresses.

important
Even though the addresses are an optional parameter, the risk assessment quality is greatly enhanced by its addition.

A sample implementation of a controller/handler#

Let's consider a toy example as back-end with the controller below:

// OrderController.java@Controller("/orders")public class OrderController {  @Post  public HttpResponse<?> postOrder(@Valid @Body OrderRequest request) {    boolean success = processPayment(        request.getUser(),        request.getProducts(),        request.getBillingAddress(),        request.getShippingAddress());    if (!success) {      return HttpResponse.unauthorized("payment denied");    }    return HttpResponse.ok();  }}
important
You are required to authenticate when using the Incognia API. For authentication details, see Authenticating in Incognia APIs

Considering that the authentication logic is implemented, you can add risk assessment requests to your login handler:

// OrderController.java@Controller("/orders")public class OrderController {  // read how to use Incognia's Java Wrapper: https://github.com/inloco/incognia-api-java  private final IncogniaAPI incogniaAPI;
  @Post  public HttpResponse<?> postOrder(@Valid @Body OrderRequest request) {    var assessment = api.registerPayment(        request.getIncogniaInstallationId(),        request.getUser().getId(),        Map.of(            AddressType.SHIPPING, request.getShippingAddress(),            AddressType.BILLING, request.getBillingAddress()));    if (riskAssessment.equals(Assessment.HIGH_RISK)) {      return HttpResponse.unauthorized("this payment is considered unsafe");    }    boolean success = processPayment(        request.getUser(),        request.getProducts(),        request.getBillingAddress(),        request.getShippingAddress());    if (!success) {      return HttpResponse.unauthorized("payment denied");    }    return HttpResponse.ok();  }}

Using the Incognia risk assessment#

When your server makes a request to the Transaction API endpoint, it will receive a response like the following:

{  "evidence": {    "account_integrity": {...},    "addresses": [...],    "device_behavior_reputation": "allowed",    "device_fraud_reputation": "allowed",    "device_integrity": {        "emulator": false,        "from_official_store": true,        "gps_spoofing": false,        "probable_root": false    },    "device_model": "SM-G9600",    "distance_to_trusted_location": 4.213,    "known_account": true,    "last_location_ts": "2019-08-24T14:15:22Z",    "location_events_quantity": 10,    "location_services": {        "location_permission_enabled": true,        "location_sensors_enabled": true    },    "sensor_match_type": "gps",    "first_device_login": false,    "first_device_login_at": "2021-07-01T10:45:53.299Z"  },  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "risk_assessment": "low_risk"}

The response contains the id of the created entity (in this case, a payment), the risk_assessment provided by Incognia based on device behavior, and evidence that supports this assessment. You can learn more about all the returned data in this article: Understanding risk assessments.

The returned assessment can be used with other risk-related data, such as in a risk engine, to decide if this payment should be accepted. Incognia's risk assessments include:

  • high_risk: this payment may be fraudulent and we advise that preventive actions are taken in these scenarios, such as a manual review or a decline;
  • low_risk: this payment seems to be safe to accept;
  • unknown_risk: we are unable to provide a precise assessment at the time of the request. Location data for this installation and device might not be available at the moment.

Wrapping Up#

After these steps, your application is ready to increase conversions and reduce fraud for in-app mobile payments.