KYC Endpoint

Validate your customer's KYC information in real time by using the KYC Endpoint

KYC Request

POST https://api-stg.directa24.com/v1/kyc

This endpoint allows you to validate yout customer KYC information.

Headers

Name	Type	Description
Content-Type*	string	application/json
X-Date*	string	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*	string	Merchant X-Login Deposits API Key
Authorization*	string	Authorization control hash

Request Body

Name	Type	Description
country*	String	Country of the user
document	String	Document of identity of the user
document_type	String	Type of the document specified
first_name	String	First name of the user
last_name	String	Last name of the user
phone	String	Phone number of the user
email	String	Email address of the user
bank_account	object	Bank account of the user
user_ip	String	IP address of the user

200: OK Success

{
    "description": "Valid account"
}

400: Bad Request Validation error

{
    "code": 300,
    "description": "Invalid document number",
    "type": "INVALID_DOCUMENT"
}

401: Unauthorized Invalid Credentials

{
    "code": 100,
    "description": "Invalid Credentials",
    "type": "INVALID_CREDENTIALS"
}

Note: To use this API (both on Staging or Production environments), please contact us via [email protected] or your responsible account manager, with some information about your merchant, so we can enable this feature for your account, as this comes disabled from default Until there's a confirmation from our integration team, you won't be able to use this API and you'll receive an error.

Description

Incorporate this API's functionalities on the user's registration or purchase process to verify their identities and prevent frauds before it get's to affect your operations.

Forget to incorporate dozens of different fraud providers, with this API you have an all-in-one validation tool that scans all (or at least one of) the following details:

• The Document of Identity

• The Email Address

• The Phone Number (please note that at the moment, this is only available in Brazil)

• The Bank Account

Depending upon the information you specify on the requests it's the details we will share back to you.

In order to start using this API, you need to:

1. Send the request with POST method.

2. Use the headers described here.
3. Specify the details required to perform the KYC in the body as JSON

This API must be activated on your account. Check with your Account Manager regarding the activation

Example Request

Please note that this example request is specific to Brazil. Example requests may vary by country.

cURL

curl --location --request POST 'https://api-stg.directa24.com/v1/kyc' \
--header 'X-Login: deposits_api_key' \
--header 'X-Date: 2022-01-01T19:00:06Z' \
--header 'Authorization: D24 520ec3e5e2d8f8c2fc66948bc87984a2ff8dec0fe25d13781272f0ae94665c3c' \
--header 'Content-Type: application/json' \
--data-raw '{
    "country": "BR",
    "document": "84932568207",
    "document_type": "CPF",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "[phone]",
    "email": "[email protected]",
    "user_ip": "",
    "bank_account": {
        "bank_code": "000",
        "account": "000000",
        "branch": "0000",
        "account_type": "S"
    }
}'

Request fields description

Field	Format	Description	Validations
country	string (length: 2)	Country code of the deposit in ISO 3166-1 alpha-2 code format	Country codes
document	string (max length: 30)	Document of identity of the user	Valid document for the country of the user See validations here
document_type	string (max length: 10)	Type of the document specified	Valid document type for the country of the user See validations here
first_name	string (max length: 255)	First name of the user	String of up to 255 characters
last_name	string (max length: 255)	Last name of the user	String of up to 255 characters
phone	string (max length: 255)	Phone number of the user	Phone number validations
email	string (max length: 255)	Email address of the user	Email validation regex
bank_account	object	Bank account of the user
user_ip	String (max length: 255)	IP Address of the user	Valid IPv4 or IPv6

Example Responses

Success Example

🇧🇷 Brazil

{
    "user": {
        "birthday": "1955-05-28",
        "age": "68",
        "name": "John Smith",
        "gender": "M",
        "name_similarity": 1,
        "legal_situation": "REGULAR",
        "pep": false,
        "street": "Avenida Paulista",
        "number": "1",
        "zip": "0333333",
        "city": "Sao Paulo",
        "code_state": "SP",
        "neighborhood": "Liberdade",
        "full_address": "Avenida Paulista 1 Sao Paulo SP",
        "email_address": "[email protected]",
        "deceased": false,
        "bolsa_familia": false,
        "emergency_aid": false,
        "ofac": false,
        "assumed_income": "ATE 1,5 MIL REAIS",
        "sportsman": false,
        "related_sportsman": false,
        "risk": {
            "ppn": false,
            "ppe": false,
            "cvm": false,
            "arrest_warrant": false,
            "tcu_inidoneo": false,
            "tcu_disabled": false,
            "lava_jato": false,
            "civil_servant": false,
            "interpol": false
        },
        "fraud_statistics": {
            "info_act_date": "2024-07-12T18:26:19.606748057Z[UTC]",
            "spi": {
                "watermark": "1970-01-01T00:00:00",
                "settlements": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                }
            },
            "fraud_markers": {
                "watermark": "1970-01-01T00:00:00",
                "application_frauds": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "mule_accounts": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "scammer_accounts": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "other_frauds": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "unknown_frauds": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "total_fraud_transaction_amount": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                },
                "distinct_fraud_reporters": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                }
            },
            "infraction_reports": {
                "watermark": "1970-01-01T00:00:00",
                "open_reports": 0,
                "open_reports_distinct_reporters": 0,
                "rejected_reports": {
                    "d90": 0,
                    "m12": 0,
                    "m60": 0
                }
            },
            "entries": {
                "watermark": "1970-01-01",
                "registered_accounts": 0
            }
        }
    },
    "phone": {
        "type": "MOBILE",
        "country": "BR",
        "carrier": "Claro S.A.",
        "blocked": "Not blocked",
        "state": "Sao Paulo",
        "errors": [
            {
                "message": "error message"
            }
        ]
    },
    "email": {
        "exists": true,
        "domain_exists": true,
        "domain_creation_age": "1995-01-18T00:00:00Z",
        "first_seen_date": "1998-02-23T00:00:00Z",
        "risk_band": "HIGH",
        "full_name": "",
        "domain_name": "gmail",
        "domain_risk_level": "1",
        "errors": [
            {
                "message": "error message"
            }
        ]
    },
    "bank_account_status": {
        "status": "VALID_STRUCTURE",
        "description": "Account number structure is valid"
    },
    "errors": [
        {
            "field": "fieldName",
            "message": "error message"
        }
    ]
}

🇵🇪 Peru

{
    "user": {
        "name": "CORNEJO VALENCIA ZACK BRIAN",
        "document": "10715352171",
        "gender": "M"
    },
    "errors": []
}

🇨🇱 Chile

{
    "user": {
        "birthday": "1977-02-02",
        "name": "CRISTIAN LEONARDO YEVENES LLANOS",
        "document": "131341148",
        "gender": "M"
    },
    "errors": []
}

Error Responses Example

// The document informed didn't pass our validations
{
    "code": 300,
    "description": "Invalid document number",
    "type": "INVALID_DOCUMENT"
}

// The API Key used is incorrect
{
    "code": 100,
    "description": "Invalid Credentials",
    "type": "INVALID_CREDENTIALS"
}

Error Responses Fields

Field	Format	Description
code	Integer	Error code. Click here to check all the possible error codes
type	String	Type of the error. Click here to check all the possible error types for refund
description	String	Human readable description of the error