Skip to main content
POST
/
v1
/
kyc
/
document
/
{cpf_or_cnpj}
Get KYC By Document
curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v1/kyc/document/{cpf_or_cnpj} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document": "<string>"
}
'
{
  "id": 348,
  "origin_request": "PAYOUT",
  "description": " Compliance approved KYC without document upload",
  "info_add": null,
  "created_at": "2022-06-14 17:15:41",
  "updated_at": "2023-10-03 16:01:28",
  "merchant": "Merchant Name",
  "submerchant": null,
  "status": {
    "id": 3,
    "name": "Approved"
  },
  "reason": {
    "id": 17,
    "name": "Payout: Limit BRL 100K Usual"
  },
  "persons": [
    {
      "id": 390,
      "name": "Person name",
      "legal_name": null,
      "document": "83562580061",
      "type_person": "Beneficiary"
    }
  ],
  "document_required": [
    {
      "status": true,
      "label": "Document proving the origin and destination of the operation"
    },
    {
      "status": true,
      "label": "Proof of residence"
    },
    {
      "status": true,
      "label": "Personal document"
    },
    {
      "status": true,
      "label": "Beneficiary Full Name"
    },
    {
      "status": true,
      "label": "Email"
    },
    {
      "status": true,
      "label": "Phone"
    },
    {
      "status": true,
      "label": "Nationality"
    },
    {
      "status": true,
      "label": "Profession (Occupation)"
    }
  ],
  "documents": [
    {
      "id": 652,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 1,
      "document_name": "invoice",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Document proving the origin and destination of the operation",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 653,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 2,
      "document_name": "address",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Proof of residence",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 654,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 3,
      "document_name": "personal-document",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Personal document",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 655,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 5,
      "document_name": "full-name-beneficiary",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Beneficiary Full Name",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 656,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 7,
      "document_name": "email",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Email",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 657,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 8,
      "document_name": "phone",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Phone",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 658,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 11,
      "document_name": "nationality",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Nationality",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 659,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 9,
      "document_name": "profession",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Profession (Occupation)",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    }
  ]
}

​
Get KYC By Document

This data can be used in the “kyc-proof-url” of a KYC. If no document is found for this cpf/cnpj, the request will return an empty array. If a KYC with the provided document exists, only the most recent KYC record for that document will be returned. When you provide a cpf or cnpj, you will be informed.

​
Path Parameters

​
cpf_or_cnpj
string
required
CPF or CNPJ document number

​
Body

​
document
string
required
Provide either a CPF or CNPJ number (digits only, no special characters)

​
Response

​
id
integer
Unique identifier for the KYC record.
​
origin_request
string
Identifier or reference of the original request that triggered this KYC process.Example: PAYIN or PAYOUT
​
description
string
Textual description or details about the KYC request.
​
info_add
string
Additional information.
​
created_at
string
Date and time when the KYC record was created.Format: YYYY-MM-DD HH:mm:ss
​
updated_at
string
Date and time of the last update made to this KYC record.Format: YYYY-MM-DD HH:mm:ss
​
merchant
string
Name of the main merchant associated with the KYC process.
​
submerchant
string
Name of the submerchant involved in the KYC process.
​
status
object
Object representing the current status of the KYC.
​
reason
object
Object representing the reason for the KYC request.
​
persons
array
List of people or entities involved in the KYC process.
​
document_required
array
List of required document types for this person.
​
documents
array
List of uploaded documents related to the KYC.

​
Request Example

curl --request POST \
  --url 'https://api.sandbox.wepayout.com.br/v1/kyc/document/12345678900' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": "12345678901"
  }'

{
  "id": 348,
  "origin_request": "PAYOUT",
  "description": " Compliance approved KYC without document upload",
  "info_add": null,
  "created_at": "2022-06-14 17:15:41",
  "updated_at": "2023-10-03 16:01:28",
  "merchant": "Merchant Name",
  "submerchant": null,
  "status": {
    "id": 3,
    "name": "Approved"
  },
  "reason": {
    "id": 17,
    "name": "Payout: Limit BRL 100K Usual"
  },
  "persons": [
    {
      "id": 390,
      "name": "Person name",
      "legal_name": null,
      "document": "83562580061",
      "type_person": "Beneficiary"
    }
  ],
  "document_required": [
    {
      "status": true,
      "label": "Document proving the origin and destination of the operation"
    },
    {
      "status": true,
      "label": "Proof of residence"
    },
    {
      "status": true,
      "label": "Personal document"
    },
    {
      "status": true,
      "label": "Beneficiary Full Name"
    },
    {
      "status": true,
      "label": "Email"
    },
    {
      "status": true,
      "label": "Phone"
    },
    {
      "status": true,
      "label": "Nationality"
    },
    {
      "status": true,
      "label": "Profession (Occupation)"
    }
  ],
  "documents": [
    {
      "id": 652,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 1,
      "document_name": "invoice",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Document proving the origin and destination of the operation",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 653,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 2,
      "document_name": "address",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Proof of residence",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 654,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 3,
      "document_name": "personal-document",
      "collection_name": null,
      "collection_id": null,
      "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
      "rejection_reason": null,
      "label": "Personal document",
      "type_field": "file",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 655,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 5,
      "document_name": "full-name-beneficiary",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Beneficiary Full Name",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 656,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 7,
      "document_name": "email",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Email",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 657,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 8,
      "document_name": "phone",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Phone",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 658,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 11,
      "document_name": "nationality",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Nationality",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    },
    {
      "id": 659,
      "status_id": 3,
      "status_name": "Approved",
      "document_id": 9,
      "document_name": "profession",
      "collection_name": null,
      "collection_id": null,
      "value_field": null,
      "rejection_reason": null,
      "label": "Profession (Occupation)",
      "type_field": "text",
      "required_field": true,
      "expires_at": null,
      "automaticatic_validation": 0
    }
  ]
}

​
Use Cases

Retrieve KYC information using a CPF or CNPJ document:
async function searchByDocument(document) {
  try {
    const kyc = await getKYCByDocument(document);
    
    if (Array.isArray(kyc) && kyc.length === 0) {
      console.log('No KYC found for this document');
      return null;
    }
    
    const person = kyc.persons[0];
    console.log(`Found KYC for ${person.name}`);
    console.log(`Document: ${person.document}`);
    console.log(`Status: ${kyc.status.name}`);
    console.log(`Reason: ${kyc.reason.name}`);
    
    return kyc;
  } catch (error) {
    console.error('Error searching KYC:', error);
  }
}
Check the status and documents for a specific document number:
async function checkDocumentStatus(document) {
  try {
    const kyc = await getKYCByDocument(document);
    
    if (Array.isArray(kyc) && kyc.length === 0) {
      return { found: false };
    }
    
    const approvedDocs = kyc.documents.filter(doc => doc.status_id === 3);
    
    return {
      found: true,
      status: kyc.status.name,
      totalDocuments: kyc.documents.length,
      approvedDocuments: approvedDocs.length,
      persons: kyc.persons.map(p => p.name)
    };
  } catch (error) {
    console.error('Error checking document status:', error);
  }
}
Check if a document has an approved KYC before processing a transaction:
async function validateDocumentForTransaction(document) {
  const kyc = await getKYCByDocument(document);
  
  if (Array.isArray(kyc) && kyc.length === 0) {
    return {
      valid: false,
      reason: 'No KYC record found'
    };
  }
  
  const isApproved = kyc.status.id === 3;
  
  return {
    valid: isApproved,
    kycId: kyc.id,
    status: kyc.status.name,
    reason: isApproved ? 'KYC approved' : `KYC status: ${kyc.status.name}`
  };
}

// Usage
const validation = await validateDocumentForTransaction('12345678900');
if (validation.valid) {
  console.log('Document validated, proceed with transaction');
} else {
  console.log(`Cannot proceed: ${validation.reason}`);
}
Since this endpoint returns only the most recent KYC, use it to check current status:
async function getMostRecentKYC(document) {
  const kyc = await getKYCByDocument(document);
  
  if (Array.isArray(kyc) && kyc.length === 0) {
    return null;
  }
  
  const person = kyc.persons[0];
  
  return {
    id: kyc.id,
    person: person.name,
    document: person.document,
    personType: person.type_person,
    status: kyc.status.name,
    reason: kyc.reason.name,
    lastUpdate: kyc.updated_at,
    createdAt: kyc.created_at
  };
}

​
Best Practices

Document Format: Send only digits in the document field, without special characters like dots, hyphens, or slashes.
Most Recent Record: This endpoint returns only the most recent KYC record for the provided document. If you need historical records, use the List KYC endpoint.
Empty Array: An empty array response indicates no KYC record exists for the provided document, which is different from a 404 error.

List KYC

List all KYC verifications

Get KYC By ID

Get KYC by ID

Create Charge

Create a new charge

Create Payment

Create a payout payment