Synctera Device Fingerprint

Synctera has introduced a new device Fingerprint API schema across our platform. This schema allows FinTechs to include user identity and device metadata in every API request, ensuring enhanced security and compliance.

Importance of Including Device Data

In a regulated industry, it is essential to track user and device information to ensure only authorized devices interact with the platform and initiate requests on behalf of end-users. By including device data in API calls, you can:

Strengthen fraud prevention & detection controls
Ensure compliance with bank requirements
Maintain the integrity of our collective platform operations
Protect your end-users

Using the Device Fingerprint API

FinTechs are strongly recommended to include the Customer-Device-Info header in every API request. This header provides critical information about the end-user's device.

The header should consist of:

customer_id: The unique identifier of the end-user making the authorized request.
ip_address: The internet-facing IP address assigned by the end-user’s ISP.
device_type: The name or operating system of the authorized device.
user_agent: The user agent of the end-user’s browser on the authorized device.

An example would look like this:

"Customer-Device-Info": {
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "ip_address": "123.45.67.89",
  "device_type": "iOS",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"
}

Here’s an example of how to include it in a request:

curl -X POST https://api-sandbox.synctera.com/v0/accounts \
  -H 'Customer-Device-Info: {"customer_id":"123e4567-e89b-12d3-a456-426614174000","ip_address":"123.45.67.89","device_type":"iOS","user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"}'

Below is the OpenAPI specification representing the Customer-Device-Info header:

customer_device:
  type: object
  required:
    - customer_id
    - ip_address
  properties:
    is_system_call:
      type: boolean
      description: Indicates if the request is made by a system call.
      example: false
    customer_id:
      type: string
      format: uuid
      description: |
        The unique identifier of the end-user making the authorized request.

        Validation:
          - If `is_system_call` is true, `customer_id` must be null.
          - If `is_system_call` is false, `customer_id` must not be null.
      example: "123e4567-e89b-12d3-a456-426614174000"
    ip_address:
      type: string
      description: The internet-facing IP address assigned by your end-user’s ISP. Supports either IPv4 or IPv6 formats.
      example: "203.0.113.195"
    device_type:
      type: string
      description: The name or operating system of the authorized device.
      example: "iOS"
    user_agent:
      type: string
      description: The user agent of the end-user’s browser on the authorized device.
      example: "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1"

System calls for device fingerprinting

When making requests for internal operations (not on behalf of an end-user), ensure the Customer-Device-Info header includes the is_system_call field set to true. In these cases, omit the customer_id field entirely. Please note that including both customer_id and is_system_call in the same request will result in the request being rejected. This distinction helps maintain clarity between system-initiated actions and those performed on behalf of individual end-users.

An example header for a system call would look like this:

"Customer-Device-Info": {
  "is_system_call": true,
  "ip_address": "123.45.67.89"
}

Troubleshooting

If you encounter issues with the Customer-Device-Info header implementation, here are some suggestions:

Ensure Proper Header Formatting:
- Double-check that the Customer-Device-Info header conforms to the specified JSON schema. This header requires fields such as customer_id (or is_system_call), ip_address, device_type, and user_agent.
- Example Header: json { "customer_id": "123e4567-e89b-12d3-a456-426614174000", "ip_address": "123.45.67.89", "device_type": "iOS", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1" }
Base64 Encoding for Non-ASCII Headers:
- If the header content includes non-ASCII characters or if you encounter issues due to special characters, consider base64 encoding the header value. After encoding, ensure that it is properly decoded and handled within the application.
Validation Checks:
- Implement validation checks to ensure the required fields are present and correctly formatted. Reject requests with a 400 status code if the header is malformed.
Documentation and Updates:
- Ensure that your implementation aligns with the latest documentation.

If you continue to encounter errors, please reach out to Customer Success.