Guides
Sign UpLog InLearning CenterPlatform StatusPostman Collection

Synctera Device Fingerprint

Suggest Edits

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. While not mandatory for a successful API call, Partner Banks might enforce the device fingerprinting schema on FinTechs. FinTech use of the schema will be monitored by Synctera and Partner Banks.

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.

If the FinTech uses a third party device risk vendor, such as Socure, the header can also include:

  • vendor: The name of that vendor.
  • session_token: The token created by the most recent device risk session with the above vendor, if applicable. Most useful to submit if using Socure for device risk.
  • device_id: The ID generated by the FinTech's device risk vendor to identify the end-user's device used to initiate the relevant API request.
  • metadata: Optional field to store additional information about the device, such as the complete JSON response from the third party vendor. This field is flexible and can be tailored based on the vendor's output format.

Note: These fields are recommended but not strictly enforced, except for customer_id, which is required for end-user initiated requests.

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
  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"
    vendor:
      type: string
      description: If applicable, the third party vendor used to manage end-user device risk and source of device_id.
      example: "Socure"
    session_token:
      type: string
      description: The risk vendor session token for the device risk assessment.
      example: "abc123xyz456"
    device_id:
      type: string
      description: If created by the vendor, send the ID associated with the end user’s last session.
      example: "device-12345"
    metadata:
      description: >
         Optional field to store additional information about the device.
         It supports collecting the complete JSON response from the third party vendor and flexible based on vendor’s output format.
      type: string
      example: "{\"risk_score\": 85, \"location\": \"CA, USA\", \"session_ids\": [\"session-123\", \"session-456\"]}"

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:

  1. Ensure Proper Header Formatting:
    • Double-check that the Customer-Device-Info header conforms to the specified JSON schema. This header can include 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" }
  2. 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.
  3. 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.
  4. Documentation and Updates:
    • Ensure that your implementation aligns with the latest documentation.

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

Updated 8 days ago