KYC Verification

The KYC (Know Your Customer) verification process is required to verify your identity and enable full access to platform features. This guide covers the complete KYC flow, from updating your information to submitting verification documents.

KYC Flow Overview

The KYC verification process consists of three main steps that must be completed in order:

Update Client Information - Provide your personal details (name, birth date, tax document, phone)
Create/Update Address - Provide your complete address information
Start KYC Process - Initiate verification and upload identity documents
Process KYC - Submit documents for verification
Check Status - Monitor the verification status

Prerequisites

Before starting the KYC process, ensure you have:

Completed authentication and have a valid access token
All required personal information ready
Valid identity documents (front and back)
Complete address information

Step 1: Update Client Information

First, you need to update your client information with your personal details. This endpoint requires authentication.

Update client information

curl -X PATCH https://api.example.com/api/client \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "fullName": "John Doe",
    "birthDate": "01/01/1990",
    "taxDocument": "12345678900",
    "phone": "+5511999999999"
  }'

Required Fields:

fullName - Your full name
birthDate - Birth date in DD/MM/YYYY format
taxDocument - Tax identification number (CPF for Brazil)
phone - Phone number with country code

Response:

{
  "status": 202,
  "message": "Client updated successfully",
  "data": {
    "email": "user@example.com",
    "full_name": "John Doe",
    "birth_date": "1990-01-01T00:00:00.000Z",
    "tax_document": "12345678900",
    "phone": "+5511999999999"
  }
}

Note: Once KYC is completed, you cannot update your client information anymore.

Step 2: Create or Update Address

Next, you need to provide your complete address information. You can create a new address or update an existing one.

Create Address

Create address

curl -X POST https://api.example.com/api/address \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "zipCode": "01234567",
    "street": "Main Street",
    "number": "123",
    "complement": "Apt 45",
    "district": "Downtown",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }'

Update Address

Update address

curl -X PATCH https://api.example.com/api/address \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "zipCode": "01234567",
    "street": "Main Street",
    "number": "123",
    "complement": "Apt 45",
    "district": "Downtown",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }'

Required Fields:

zipCode - Postal/ZIP code
street - Street name
number - Street number
district - District/neighborhood
city - City name
state - State/Province code
country - Country code (ISO format)

Optional Fields:

complement - Additional address information (apartment, suite, etc.)

Response:

{
  "status": 201,
  "message": "Address created successfully",
  "data": {
    "id": "address-id",
    "zip_code": "01234567",
    "street": "Main Street",
    "number": "123",
    "complement": "Apt 45",
    "district": "Downtown",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }
}

Get Address

You can retrieve your current address information:

Get address

curl -X GET https://api.example.com/api/address \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Step 3: Start KYC Process

Once you have completed your client information and address, you can start the KYC verification process. This will generate upload URLs for your identity documents.

Start KYC process

curl -X POST https://api.example.com/api/kyc/start \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "documentCountry": "BR",
    "documentType": "CPF"
  }'

Required Fields:

documentCountry - Country code where the document was issued (ISO format)
documentType - Type of document (e.g., "CPF", "RG", "CNH", "PASSPORT")

Response:

{
  "status": 200,
  "message": "Client KYC started successfully",
  "data": {
    "session": {
      "id": "session-id",
      "status": "PENDING",
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    "backDocumentUpload": {
      "url": "https://s3.amazonaws.com/bucket/...",
      "fields": {
        "bucket": "bucket-name",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "credential",
        "X-Amz-Date": "20240101T000000Z",
        "key": "document-key",
        "Policy": "policy-string",
        "X-Amz-Signature": "signature"
      }
    },
    "frontDocumentUpload": {
      "url": "https://s3.amazonaws.com/bucket/...",
      "fields": {
        "bucket": "bucket-name",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "credential",
        "X-Amz-Date": "20240101T000000Z",
        "key": "document-key",
        "Policy": "policy-string",
        "X-Amz-Signature": "signature"
      }
    }
  }
}

Important: The upload URLs expire after 15 minutes. If you need to restart the process, you can call this endpoint again (only if status is FAILED or EXPIRED).

Step 4: Upload Documents

After receiving the upload URLs, you need to upload your identity documents using a multipart/form-data POST request to the provided URLs.

Upload Front Document

Upload front document

curl -X POST {frontDocumentUpload.url} \
  -F "bucket={frontDocumentUpload.fields.bucket}" \
  -F "X-Amz-Algorithm={frontDocumentUpload.fields.X-Amz-Algorithm}" \
  -F "X-Amz-Credential={frontDocumentUpload.fields.X-Amz-Credential}" \
  -F "X-Amz-Date={frontDocumentUpload.fields.X-Amz-Date}" \
  -F "key={frontDocumentUpload.fields.key}" \
  -F "Policy={frontDocumentUpload.fields.Policy}" \
  -F "X-Amz-Signature={frontDocumentUpload.fields.X-Amz-Signature}" \
  -F "file=@/path/to/front-document.jpg"

Upload Back Document

Upload back document

curl -X POST {backDocumentUpload.url} \
  -F "bucket={backDocumentUpload.fields.bucket}" \
  -F "X-Amz-Algorithm={backDocumentUpload.fields.X-Amz-Algorithm}" \
  -F "X-Amz-Credential={backDocumentUpload.fields.X-Amz-Credential}" \
  -F "X-Amz-Date={backDocumentUpload.fields.X-Amz-Date}" \
  -F "key={backDocumentUpload.fields.key}" \
  -F "Policy={backDocumentUpload.fields.Policy}" \
  -F "X-Amz-Signature={backDocumentUpload.fields.X-Amz-Signature}" \
  -F "file=@/path/to/back-document.jpg"

Document Requirements:

Supported formats: JPG
Maximum file size: 10MB
Documents must be clear and readable
Front document: Full front side of your ID
Back document: Full back side of your ID (if applicable)

Step 5: Process KYC

After uploading both documents, call the process endpoint to submit them for verification.

Process KYC

curl -X POST https://api.example.com/api/kyc/process \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Client KYC processed successfully"
}

After processing, your KYC status will change to VERIFYING while the documents are being reviewed.

Step 6: Check KYC Status

You can check the status of your KYC verification at any time.

Check KYC status

curl -X GET https://api.example.com/api/kyc/status \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Client KYC status retrieved successfully",
  "data": {
    "session": {
      "id": "session-id",
      "status": "VERIFYING",
      "individualId": "individual-id",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

KYC Status Values

The KYC process can have the following statuses:

PENDING - KYC session created, waiting for document upload
VERIFYING - Documents uploaded and being verified
COMPLETED - KYC verification successfully completed
FAILED - KYC verification failed (you can restart the process)
EXPIRED - KYC session expired (you can restart the process)

Important Notes

Information Lock: Once KYC is completed, you cannot update your client information (fullName, birthDate, taxDocument, phone).
Session Expiration: KYC sessions expire after 15 minutes if not processed. You can restart the process if status is FAILED or EXPIRED.
Document Validation: Ensure your documents are valid, clear, and match the information provided in your client profile.
Processing Time: Verification typically takes a few minutes to a few hours. Check the status periodically.
Required Information: Both client information and address must be complete before starting KYC.

Error Handling

Client Information Not Found

{
  "status": 404,
  "message": "Client not found"
}

Address Not Found

{
  "status": 404,
  "message": "Client address not found"
}

Invalid Document Type

{
  "status": 400,
  "message": "Invalid document type"
}

KYC Already Completed

{
  "status": 200,
  "message": "Client KYC already completed",
  "data": {
    "status": "COMPLETED"
  }
}

Cannot Update After KYC Approval

{
  "status": 400,
  "message": "It is not possible to update information after the KYC has been approved"
}

Complete Flow Example

Here's a complete example of the KYC flow:

# 1. Update client information
curl -X PATCH https://api.example.com/api/client \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "fullName": "John Doe",
    "birthDate": "01/01/1990",
    "taxDocument": "12345678900",
    "phone": "+5511999999999"
  }'

# 2. Create address
curl -X POST https://api.example.com/api/address \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "zipCode": "01234567",
    "street": "Main Street",
    "number": "123",
    "district": "Downtown",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }'

# 3. Start KYC
curl -X POST https://api.example.com/api/kyc/start \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "documentCountry": "BR",
    "documentType": "CPF"
  }'

# 4. Upload documents (using the URLs from step 3)
# ... upload front and back documents ...

# 5. Process KYC
curl -X POST https://api.example.com/api/kyc/process \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 6. Check status
curl -X GET https://api.example.com/api/kyc/status \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"