Docs
Developer Hub

Custom Encryption

Suggest Edits

Encryption Configuration API Documentation

The Encryption Configuration API enables merchants to establish custom encrypted communications. It provides an endpoint that allows merchants to create and update their encryption configurations. By utilizing this API, merchants can generate an encryptionConfigurationId and an encryptedCommunicationSettings object, which contains merchant keys for encryption/decryption and other encryption settings. The generated public key plays a crucial role in securely receiving the private key. The private key is encrypted with the key provided in the response. This encrypted private key serves as the foundation for encrypting all communications, following the specifications outlined in the SDK or API configuration.

Create Encryption Configuration Endpoint

This endpoint allows merchants to create a configuration and get our public key for merchant encryption private keys.

Endpoint URL

POST https://api.getmati.com/v2/encryption-configuration

Method availability

This method is available only to merchants who have the 'can-use-encryption-configuration-service' tag set.

Request Parameters

This endpoint has no input parameters.

Request Explanation

For one merchant, this request can be executed no more than once every 10 minutes. The merchant should create it once and use the received configurationId for all verifications. The merchant cannot call this method for every verification. The merchant can use the configurationId for as long as they want. The merchant can update their encryption keys using the patch method for a single configurationId (also no more than once every 10 minutes).

Example Request

curl --location --request POST 'https://api.getmati.com/v2/encryption-configuration' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data ''

Example Response

{
    "configurationId": "645aa85ad6f165001a0ab1fb",
    "isWebhookEncrypted": true,
    "encryptedCommunicationSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public key}}",
        "publicKeyFormat": "pkcs1-public-pem",
        "encryptionScheme": "pkcs1"
    },
    "createdAt": "2023-05-09T20:08:58.680Z",
    "updatedAt": "2023-05-09T20:08:58.680Z"
}

Response explanation

This response contains the following fields:

  • configurationId: Unique identifier for the created configuration.
  • isWebhookEncrypted: Indicates if webhooks are encrypted.
  • encryptedCommunicationSettings: Contains merchant keys for encryption/decryption and other encryption settings.
    • algorithmType: Type of encryption algorithm used. Supported values are "RSA" and "AES".
    • publicKey: Public key for the RSA algorithm.
    • publicKeyFormat: Format of the public key. Supported values are "pkcs1-public-pem" and "pkcs8-public-pem".
    • encryptionScheme: Encryption scheme used. Supported value is "pkcs1".
  • createdAt: Date and time of the configuration creation.
  • updatedAt: Date and time of the last configuration update.

Update Encryption Configuration Endpoint

This endpoint allows merchants to update their encryption configurations.

Endpoint URL

PATCH [https://api.getmati.com/v2/encryption-configuration/{{encryption_configuration_id}](https://api.getmati.com/v2/encryption-configuration/%7B%7Bencryption_configuration_id%7D)

Method availability

Merchant may not encrypt their privateKey if it has the tag 'can-send-unencrypted-private-keys' set

Documentation

Encryption Configuration API Documentation

The Encryption Configuration API provides merchants with an API endpoint to create and update their encryption configurations. This endpoint generates an encryptionConfigurationId and an encryptedCommunicationSettings object that contains merchant keys for encryption/decryption and other encryption settings. The public key generated in this request is used to safely receive the private key, which will be encrypting with the key provided in the response. This encrypted private key will be used to encrypt all communications, as specified in the SDK or API configuration.

Create Encryption Configuration Endpoint

This endpoint allows merchants to create a configuration and get the public key for their encryption private keys.

Endpoint URL

POST <https://api.getmati.com/v2/encryption-configuration>

Method availability

This method is available only to merchants who have the 'can-use-encryption-configuration-service' tag set.

Request Parameters

This endpoint has no input parameters.

Request Explanation

For one merchant, this request can be executed no more than once every 10 minutes. The merchant should create it once and use the received configurationId for all verifications. The merchant cannot call this method for every verification. The merchant can use the configurationId for as long as they want. The merchant can update their encryption keys using the patch method for a single configurationId (also no more than once every 10 minutes).

Example Request

curl --location --request POST 'https://api.getmati.com/v2/encryption-configuration' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data ''

Example Response

{
    "configurationId": "645aa85ad6f165001a0ab1fb",
    "isWebhookEncrypted": true,
    "encryptedCommunicationSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public key}}",
        "publicKeyFormat": "pkcs1-public-pem",
        "encryptionScheme": "pkcs1"
    },
    "createdAt": "2023-05-09T20:08:58.680Z",
    "updatedAt": "2023-05-09T20:08:58.680Z"
}

Response explanation

This response contains the following fields:

  • configurationId: Unique identifier for the created configuration.
  • isWebhookEncrypted: Indicates if webhooks are encrypted.
  • encryptedCommunicationSettings: Contains merchant keys for encryption/decryption and other encryption settings.
    • algorithmType: Type of encryption algorithm used. Supported values are "RSA" and "AES".
    • publicKey: Public key for the RSA algorithm.
    • publicKeyFormat: Format of the public key. Supported values are "pkcs1-public-pem" and "pkcs8-public-pem".
    • encryptionScheme: Encryption scheme used. Supported value is "pkcs1".
  • createdAt: Date and time of the configuration creation.
  • updatedAt: Date and time of the last configuration update.

Update Encryption Configuration Endpoint

This endpoint allows merchants to update their encryption configurations.

Endpoint URL

PATCH <https://api.getmati.com/v2/encryption-configuration/{{encryption_configuration_id}>}

Method availability

Merchant may not encrypt their privateKey if it has the tag 'can-send-unencrypted-private-keys' set.

Request Parameters

This endpoint requires the following input parameters:

  • configurationId (string, required): Unique identifier for the configuration being updated.
  • encryptionSettings (object, optional): Contains merchant keys for encryption/decryption and other encryption settings. This parameter has the following internal properties:
    • algorithmType (string, required): Type of encryption algorithm to use. Supported values are "RSA" and "AES".
    • if algorithmType = "RSA":
      • publicKey (string, required): Public key for the RSA algorithm.
      • privateKey (string, required): Private key for the RSA algorithm. Must be encrypted with our Public Key.
      • publicKeyFormat (string, required): Format of the public key. Supported values are "pkcs1-public-pem" and "pkcs8-public-pem".
      • privateKeyForm (string, required): Format of the private key. Supported values are "pkcs1-private-pem" and "pkcs8-private-pem".
      • encryptionScheme (string, required): Encryption scheme to use. Supported value is "pkcs1".
    • if algorithmType = "AES":
      • algorithm (string, required): Type of AES encryption algorithm to use. Supported value is "aes-256-ctr".
      • privateKey (string, required): Private key for the AES algorithm. Must be encrypted with our Public Key.
  • isVerificationRetrievingEncrypted (boolean, optional): Set to true to retrieve the verification API in encrypted form. Must pass the encryptionSettings parameter to set this to true.
  • isWebhookEncrypted (boolean, optional): Set to true to make webhooks encrypted. Must pass the encryptionSettings parameter to set this to true.

Example Request (RSA keys)

curl --location --globoff --request PATCH 'https://api.getmati.com/v2/encryption-configuration/{{encryption_configuration_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
    "isWebhookEncrypted": true,
    "encryptionSettings": {
    "algorithmType": "RSA",
    "publicKey": "{{public_key}}",
    "privateKey": "{{private_key}}",
    "publicKeyFormat": "pkcs8-public-pem",
    "privateKeyFormat": "pkcs8-private-pem",
    "encryptionScheme": "pkcs1"
  }
}'

Example Request (AES key)

curl --location --request PATCH 'https://api.getmati.com/v2/encryption-configuration/{encriptionConfigurationId}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "isWebhookEncrypted": true;
 "isVerificationRetrievingEncrypted": true;
 "encryptionSettings": {
   "algorithmType": "AES",
	 "algorithm": "aes-256-ctr",
	 "privateKey": "{{private_key}}"}'

Example Response

{
    "configurationId": "{{configurationId}}",
    "isWebhookEncrypted": true,
    "isVerificationRetrievingEncrypted": true,
    "encryptedCommunicationSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public_key}}",
        "publicKeyFormat": "pkcs1-public-pem",
        "encryptionScheme": "pkcs1"
    },
    "createdAt": "2023-04-27T21:36:24.369Z",
    "updatedAt": "2023-04-27T22:23:24.496Z"
}

Encrypted Webhooks

When a verification is specified with encryptionConfigurationId and isWebhookEncrypted = true, each message related to that verification will be returned in encrypted form, except for eventName, flowId, and timestamp fields.

However, there are some webhook types that are not currently supported for encryption, including:

  • custom_fields_input_copy_changed
  • premium_aml_watchlists_monitoring
  • verification_signed
  • financial_institution_scrape_data_received
  • financial_bank_statement_parsed_data_received
  • financial_bank_statements_parsing_validation_status_received

These unsupported webhook types will be sent unencrypted.

Example Unencrypted Webhook

The following is an example of an unencrypted webhook:

{
  "resource": "http://localhost:4002/v2/verifications/645047579fdba5001a9b4179",
  "step": {
    "status": 200,
    "id": "ip-validation",
    "error": {
      "type": "StepError",
      "code": "ip.notFound",
      "message": "No ip data found"
    }
  },
  "eventName": "step_completed",
  "flowId": "64502a250f3874526b95ab93",
  "timestamp": "2023-05-01T23:10:06.338Z"
}

Example Encrypted Webhook

The following is an example of an encrypted webhook:

{
  "resource": "{{encrypted_value}}",
  "step": {
    "status": "{{encrypted_value}}",
    "id": "{{encrypted_value}}",
    "error": {
      "type": "{{encrypted_value}}",
      "code": "{{encrypted_value}}",
      "message": "{{encrypted_value}}"
    }
  },
  "eventName": "step_completed",
  "flowId": "64502a250f3874526b95ab93",
  "timestamp": "2023-05-01T23:10:06.338Z"
}

Race Condition

In case a webhook is sent while the merchant is updating the encryption keys or the merchant is unable to decrypt the webhook for some other reason (e.g. key is expired), we suggest the following:

  1. Update the public/private keys in encryptionConfiguration
  2. Get the full verification body using the API (GET VERIFICATION API).

Response to Retrieve Webhook Resource Data

If for a given verification an encryptionConfigurationId was specified with isVerificationRetrievingEncrypted = true, we will return the response to GET VERIFICATION API in encrypted form.

Example Encrypted Response

{
  "_id": "{{encrypted_value}}",
  "computed": {
    "age": {
      "data": "{{encrypted_value}}"
    },
    "isDocumentExpired": {
      "data": {
        "national-id": "{{encrypted_value}}",
        "passport": "{{encrypted_value}}"
      }
    }
  },
  "createdAt": "{{encrypted_value}}",
  "customFieldsDataCopy": {
    "fields": []
  },
  "documentsFieldsConfigs": [],
  "verificationStatus": "{{encrypted_value}}",
  "verificationStatusDetails": {
    "value": "{{encrypted_value}}"
  }
}

Phone Risk

The Phone Risk API allows merchants to check the risk associated with a given phone number.

Request

Endpoint: POST /safety/v1/checks/encrypted/phone/risk

Header:

  • Authorization: Bearer token that authenticates the request.

Body:

{
    "encryptionConfigurationId": "{{encryption_configuration_id}}",
    "recipient": "{{encrypted_phone}}",
    "callbackUrl": "{{encrypted_callback}}",
    "metadata": {
        "user_defined": "value"
    }
}

Fields:

  • encryptionConfigurationId (required): The ID of the encryption configuration to use for

Documentation

Encryption Configuration API Documentation

Overview

Our verification retrieval API service provides you with access to your customer’s data securely. With the introduction of Encrypted Webhooks and Data Retrieval, you now have the option to receive encrypted webhooks and encrypted data, adding an extra layer of protection to your customer's sensitive information.

How it works

The Encryption Configuration API provides you with an API endpoint to create and update your encryption configurations. This endpoint generates an encryptionConfigurationId and an encryptedCommunicationSettings object that contains keys for encryption/decryption and other encryption settings.

The publicKey generated in this request is used to safely receive the private key through our /PATCH endpoint, which will be encrypted with the key provided in the response. This encrypted private key will be used to encrypt all communications, as specified in the SDK or API configuration.

Create Encryption Configuration Endpoint

This endpoint allows you to create a configuration and get the public key for their encryption private keys.

Endpoint URL

POST https://api.getmati.com/v2/encryption-configuration

Method availability

This method is available only to customers that have special access to it. Please contact [email protected] if you would like to use this feature.

Request Parameters

This endpoint has no input parameters.

Rate Limiting

This action can only be performed once every 10 minutes. It is recommended to create the request and use the generated configurationId for all subsequent verifications. Calling this method for every verification is not allowed for the merchant; instead, you should use the configurationId for as long as necessary. If necessary, you can update their encryption keys for a single configurationId using the /PATCH method discussed next, but this should also be done no more than once every 10 minutes.

Example Request

curl --location --request POST 'https://api.getmati.com/v2/encryption-configuration' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data ''

Example Response

{
    "configurationId": "645aa85ad6f165001a0ab1fb",
    "isWebhookEncrypted": true,
    "encryptedCommunicationSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public key}}",
        "publicKeyFormat": "pkcs1-public-pem",
        "encryptionScheme": "pkcs1"
    },
    "createdAt": "2023-05-09T20:08:58.680Z",
    "updatedAt": "2023-05-09T20:08:58.680Z"
}

Response explanation

This response contains the following fields:

  • configurationId: Unique identifier for the created configuration. It will be used in other operations to specify which encryption settings are to be used for a given verification or API request.
  • isWebhookEncrypted: Indicates if webhooks are going to be sent in an encrypted way. It can be set to false through the /PATCH endpoint
  • encryptedCommunicationSettings: Contains keys for encryption/decryption and other encryption settings.
    • algorithmType: Type of encryption algorithm used. Supported values are "RSA" and "AES".
    • publicKey: Public key for the RSA algorithm. It can be used to encrypt the privateKey when sending it through the /PATCH endpoint.
    • publicKeyFormat: Format of the public key. Supported values are "pkcs1-public-pem" and "pkcs8-public-pem".
    • encryptionScheme: Encryption scheme used. Supported value is "pkcs1".
  • createdAt: Date and time of the configuration creation.
  • updatedAt: Date and time of the last configuration update.

Update Encryption Configuration Endpoint

This endpoint allows merchants to update their encryption configurations.

Endpoint URL

PATCH https://api.getmati.com/v2/encryption-configuration/{{encryption_configuration_id}}

Method availability

This method is available only to customers that have special access to it. Please contact [email protected] if you would like to use this feature.

Request Parameters

This endpoint requires the following input parameters:

  • configurationId (string, required): Unique identifier for the configuration being updated. It is obtained from the first endpoint in this document.
  • encryptionSettings(object, required): Contains your own keys for encryption/decryption and other encryption settings.
    • This parameter has the following internal properties:
    • algorithmType (string, required): Type of encryption algorithm to use. Supported values are "RSA" and "AES".
      • if algorithmType = "RSA":
        • publicKey (string, required): Public key for the RSA algorithm.
        • privateKey (string, required): Private key for the RSA algorithm. Must be encrypted with our publicKey obtained in the encryption-configuration endpoint.
        • publicKeyFormat (string, required): Format of the public key. Supported values are "pkcs1-public-pem" and "pkcs8-public-pem".
        • privateKeyForm (string, required): Format of the private key. Supported values are "pkcs1-private-pem" and "pkcs8-private-pem".
        • encryptionScheme (string, required): Encryption scheme to use. Supported value is "pkcs1".
      • if algorithmType = "AES":
        • algorithm(string, required): Type of AES encryption algorithm to use. Supported value is "aes-256-ctr".
        • privateKey (string, required): Private key for the AES algorithm. Must be encrypted with our Public Key.
  • isVerificationRetrievingEncrypted(boolean, optional): Set to true to retrieve the verification API in encrypted form. Must pass the encryptionSettings parameter to set this to true.
  • isWebhookEncrypted (boolean, optional): Set to true to make webhooks encrypted. Must pass the encryptionSettings parameter to set this to true.

Example Request (RSA keys)

curl --location --globoff --request PATCH 'https://api.getmati.com/v2/encryption-configuration/{{encryption_configuration_id}}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
    "isWebhookEncrypted": true,
    "encryptionSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public_key}}",
        "privateKey": "{{private_key}}",
        "publicKeyFormat": "pkcs8-public-pem",
        "privateKeyFormat": "pkcs8-private-pem",
        "encryptionScheme": "pkcs1"
    }
}'

Example Request (AES key)

curl --location --request PATCH 'https://api.getmati.com/v2/encryption-configuration/{encriptionConfigurationId}' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "isWebhookEncrypted": true,
    "isVerificationRetrievingEncrypted": true,
    "encryptionSettings": {
        "algorithmType": "AES",
        "algorithm": "aes-256-ctr",
        "privateKey": "{{private_key}}"
    }
}'

Example Response

{
    "configurationId": "{{configurationId}}",
    "isWebhookEncrypted": true,
    "isVerificationRetrievingEncrypted": true,
    "encryptedCommunicationSettings": {
        "algorithmType": "RSA",
        "publicKey": "{{public_key}}",
        "publicKeyFormat": "pkcs1-public-pem",
        "encryptionScheme": "pkcs1"
    },
    "createdAt": "2023-04-27T21:36:24.369Z",
    "updatedAt": "2023-04-27T22:23:24.496Z"
}

Encrypted Webhooks

When a verification is specified with encryptionConfigurationId and isWebhookEncrypted = true, each message related to that verification will be returned in encrypted form, except for eventName, flowId, and timestamp fields.

However, there are some webhook types that are not currently supported for encryption, including:

  • custom_fields_input_copy_changed
  • premium_aml_watchlists_monitoring
  • verification_signed
  • financial_institution_scrape_data_received
  • financial_bank_statement_parsed_data_received
  • financial_bank_statements_parsing_validation_status_received

These unsupported webhook types will be sent unencrypted.

Example Unencrypted Webhook

The following is an example of an unencrypted webhook:

{
    "eventName": "step_completed",
    "step": {
        "status": 200,
        "id": "ip-validation",
        "error": null,
        "data": {
            "country": "Mexico",
            "countryCode": "MX",
            "region": "Chihuahua",
            "regionCode": "CHH",
            "city": "Chihuahua City",
            "zip": "31207",
            "latitude": 28.7757,
            "longitude": -106.1146,
            "safe": true
        }
    },
    "resource": "https://api.getmati.com/v2/verifications/5fd7b347d4dbd8001b19cbcb",
    "timestamp": "2020-12-14T18:47:35.460Z"
}

Example Encrypted Webhook

The following is an example of an encrypted webhook:

{
  "resource": "{{encrypted_value}}",
  "step": {
    "status": "{{encrypted_value}}",
    "id": "{{encrypted_value}}",
    "error": {
      "type": "{{encrypted_value}}",
      "code": "{{encrypted_value}}",
      "message": "{{encrypted_value}}"
    }
  },
  "eventName": "step_completed",
  "flowId": "64502a250f3874526b95ab93",
  "timestamp": "2023-05-01T23:10:06.338Z"
}

Race Condition

In case a webhook is sent while the merchant is updating the encryption keys or the merchant is unable to decrypt the webhook for some other reason (e.g. key is expired), we suggest the following:

  1. Update the public/private keys in encryptionConfiguration
  2. Get the full verification body using the API (GET VERIFICATION API).

Response to Retrieve Webhook Resource Data

If for a given verification an encryptionConfigurationId was specified with isVerificationRetrievingEncrypted = true, we will return the response to GET VERIFICATION API in encrypted form.

Example request

curl --location 'https://api.getmati.com/v2/verifications/{{identity}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}'

Example Encrypted Response

{
  "_id": "{{encrypted_value}}",
  "computed": {
    "age": {
      "data": "{{encrypted_value}}"
    },
    "isDocumentExpired": {
      "data": {
        "national-id": "{{encrypted_value}}",
        "passport": "{{encrypted_value}}"
      }
    }
  },
  "createdAt": "{{encrypted_value}}",
  "customFieldsDataCopy": {
    "fields": []
  },
  "documentsFieldsConfigs": [],
  "verificationStatus": "{{encrypted_value}}",
  "verificationStatusDetails": {
    "value": "{{encrypted_value}}"
  }
}

Supported standalone APIs

Phone Risk

  • POST /safety/v1/checks/encrypted/phone/risk: This API allows merchants to check the risk associated with a given phone number. The request requires an encryptionConfigurationId, a recipient (encrypted phone number), a callbackUrl (encrypted URL), and optional metadata.

Email Risk

  • POST /safety/v1/checks/encrypted/email/risk: This API allows merchants to check the risk associated with a given email address. The request requires an encryptionConfigurationId, a recipient (encrypted email address), a callbackUrl (encrypted URL), and optional metadata.

Phone Risk

The Phone Risk API allows merchants to check the risk associated with a given phone number.

Request

Endpoint: POST /safety/v1/checks/encrypted/phone/risk

Header:

  • Authorization: Bearer token that authenticates the request.

Body:

{
    "encryptionConfigurationId": "{{encryption_configuration_id}}",
    "recipient": "{{encrypted_phone}}",
    "callbackUrl": "{{encrypted_callback}}",
    "metadata": {
        "user_defined": "value"
    }
}

Fields:

  • encryptionConfigurationId (required): The ID of the encryption configuration to use for

Email Risk

The Email Risk API allows merchants to check the risk associated with a given email address.

Request

Endpoint: POST /safety/v1/checks/encrypted/email/risk

Header:

  • Authorization: Bearer token that authenticates the request.

Body:

{
    "encryptionConfigurationId": "{{encryption_configuration_id}}",
    "recipient": "{{encrypted_email}}",
    "callbackUrl": "{{encrypted_callback}}"
}

Example webhook response

{
  "metadata": {
    "user_defined": "id00000"
  },
  "error": null,
  "data": {
    "email": "{{encrypted_value}}",
    "riskScore": "{{encrypted_value}}",
    "message": "{{encrypted_value}}",
    "success": "{{encrypted_value}}",
    "valid": "{{encrypted_value}}",
    "disposable": "{{encrypted_value}}",
    "smtp_score": "{{encrypted_value}}",
    "overall_score": "{{encrypted_value}}",
    "first_name": "{{encrypted_value}}",
    "generic": "{{encrypted_value}}",
    "common": "{{encrypted_value}}",
    "dns_valid": "{{encrypted_value}}",
    "honeypot": "{{encrypted_value}}",
    "deliverability": "{{encrypted_value}}",
    "frequent_complainer": "{{encrypted_value}}",
    "spam_trap_score": "{{encrypted_value}}",
    "catch_all": "{{encrypted_value}}",
    "timed_out": "{{encrypted_value}}",
    "suspect": "{{encrypted_value}}",
    "recent_abuse": "{{encrypted_value}}",
    "suggested_domain": "{{encrypted_value}}",
    "leaked": "{{encrypted_value}}",
    "domain_age": {
      "human": "{{encrypted_value}}",
      "timestamp": "{{encrypted_value}}",
      "iso": "{{encrypted_value}}"
    },
    "first_seen": {
      "human": "{{encrypted_value}}",
      "timestamp": "{{encrypted_value}}",
      "iso": "{{encrypted_value}}"
    },
    "sanitized_email": "{{encrypted_value}}",
    "domain_velocity": "{{encrypted_value}}",
    "user_activity": "{{encrypted_value}}",
    "associated_names": {
      "status": "{{encrypted_value}}",
      "names": []
    },
    "associated_phone_numbers": {
      "status": "{{encrypted_value}}",
      "phone_numbers": []
    },
    "request_id": "{{encrypted_value}}"
  }
}

Updated 12 months ago