先决条件
- Stage 访问令牌。请参阅 获取访问令牌。
- 实体类型:
INDIVIDUAL适用于自然人,COMPANY适用于法人实体。 - 身份证明文件。对于个人:税务识别号(
CPF、CUIT、RFC、CURP)或身份证明文件(DNI、PASSPORT、CC)。对于公司:税务识别号(CNPJ、CUIT、RFC、RUC、NIT)。它将成为主要文件。 - 稳定的
externalId:您自己的参考编号,每个商家独一无二。 - 如果 Localpayment 为您的商户配置了自定义字段,请参阅 自定义字段 部分。
需要申报哪些文件
一份文件对应一个 id,其中可包含您需要的任意数量的文件,例如身份证件的正面、背面和自拍照。创建实体时,请在document 中发送身份证明文件:它将成为主要文件。其他所有文件请使用 添加文件 进行申报。type + id 的组合在您的商户中必须是唯一的。
| 类型 | 主要文件 | 其他文件 |
|---|---|---|
INDIVIDUAL | 税务识别号或身份证明文件(CPF、DNI、PASSPORT)。证明材料:FRONT、BACK、SELFIE。 | PROOF_OF_ADDRESS,以及任何其他证明(PROOF_OF_FUNDS、PAYSLIP、OTHER)。 |
COMPANY | 税务识别号(CNPJ、CUIT、RFC、RUC、NIT)。证明材料:DOCUMENT。 | ARTICLES_OF_INCORPORATION、PROOF_OF_ADDRESS。所有者注册为 INDIVIDUAL 实体,并通过 管理最终受益所有人 进行关联。 |
最低数据
| 类型 | API 要求 | 强烈推荐 |
|---|---|---|
INDIVIDUAL | externalId, type, name, lastname, document | birthdate, nationality, residenceCountry, email, phone, address |
COMPANY | externalId, type, name, document | incorporationCountry, incorporationDate, legalRepresentativeName, website, email, phone, address |
INCOMPLETE_KYC_DATA。
创建个人
Request
curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities \
-H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Correlation-ID: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10" \
-d '{
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"type": "INDIVIDUAL",
"name": "Jane",
"lastname": "Doe",
"birthdate": "1990-01-15",
"nationality": "BRA",
"birthCountry": "BRA",
"residenceCountry": "BRA",
"isPep": false,
"email": "jane.doe@example.com",
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "999990001"
},
"address": {
"street": "Rua Exemplo",
"number": "123",
"city": "São Paulo",
"state": "SP",
"zipCode": "01310-100",
"country": "BRA"
},
"document": {
"type": "CPF",
"id": "00000000000",
"issuingCountry": "BRA"
}
}'
Response
{
"internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"type": "INDIVIDUAL",
"status": "PENDING_KYC",
"name": "Jane",
"lastname": "Doe",
"birthdate": "1990-01-15",
"gender": null,
"nationality": "BRA",
"birthCountry": "BRA",
"residenceCountry": "BRA",
"occupation": null,
"isPep": false,
"incorporationDate": null,
"incorporationCountry": null,
"website": null,
"legalRepresentativeName": null,
"email": "jane.doe@example.com",
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "999990001"
},
"address": {
"street": "Rua Exemplo",
"city": "São Paulo",
"state": "SP",
"zipCode": "01310-100",
"number": "123",
"comment": null,
"country": "BRA",
"line2": null,
"line3": null
},
"attributes": null,
"documentationStatus": "NO_FILES",
"document": {
"documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
"entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
"type": "CPF",
"id": "00000000000",
"issuingCountry": "BRA",
"issueDate": null,
"expirationDate": null,
"isPrimary": true,
"status": "PENDING",
"metadata": null,
"proofs": [],
"createdAt": "2024-01-15T17:03:10Z",
"updatedAt": "2024-01-15T17:03:10Z"
},
"documents": [],
"version": 0,
"createdAt": "2024-01-15T17:03:10Z",
"updatedAt": "2024-01-15T17:03:10Z",
"customFieldSchemaVersion": null
}
ETag: "0"。
请保留 internalId(实体)和 document.documentId(主要文件)。后续步骤需要用到这两个值。
创建公司
以税务识别号为主要文件、包含附加行的地址以及自定义字段的公司:{
"externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "COMPANY",
"name": "Example Company S.A.",
"incorporationCountry": "BRA",
"incorporationDate": "2020-01-15",
"website": "https://www.example.com",
"email": "test@example.com",
"phone": {
"countryCode": "55",
"areaCode": "11",
"number": "999990000"
},
"legalRepresentativeName": "Jane Doe",
"isPep": false,
"address": {
"street": "Rua Exemplo",
"number": "100",
"city": "São Paulo",
"state": "SP",
"zipCode": "01310-100",
"country": "BRA",
"line2": "Sala 100",
"line3": "Torre A"
},
"document": {
"type": "CNPJ",
"id": "00000000000100",
"issuingCountry": "BRA"
},
"attributes": {
"reasonForAccountOpening": "receive_payments_for_goods_and_services",
"sourceOfFundsAndIncome": "sales_of_goods_and_services",
"numberOfEmployees": "11-50",
"estimatedAnnualRevenueUsd": "1m_to_10m",
"estimatedMonthlyVolumeUsd": "50000",
"businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
"countryTaxResidence": "BRA",
"socialMedia": "https://www.linkedin.com/company/example",
"emailPixKey": "test@example.com"
}
}
处理集成中的错误
import os
import uuid
import requests
BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]
payload = {
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"type": "INDIVIDUAL",
"name": "Jane",
"lastname": "Doe",
"document": {"type": "CPF", "id": "00000000000", "issuingCountry": "BRA"},
}
response = requests.post(
f"{BASE_URL}/v1/entities",
json=payload,
headers={
"Authorization": f"Bearer {access_token}",
"X-Correlation-ID": str(uuid.uuid4()),
},
timeout=30,
)
if response.status_code == 201:
entity = response.json()
entity_id = entity["internalId"]
primary_document_id = entity["document"]["documentId"]
else:
problem = response.json() # application/problem+json
code = problem.get("code")
if code == "DUPLICATE_ENTITY":
# Already registered: look it up with GET /v1/entities?externalId=...
pass
elif code in ("VALIDATION_ERROR", "CUSTOM_FIELDS_INVALID"):
for detail in problem.get("details", []):
print(f"{detail['field']}: {detail['issue']}")
else:
# Quote the correlation id when you contact support
print(f"{response.status_code} {code} correlationId={problem.get('correlationId')}")
常见错误
| 错误 | 原因 | 解决方法 |
|---|---|---|
| 400 VALIDATION_ERROR | 未知属性、两位字母的国家代码、文档列表而不是文档,或者没有文档。 | 检查 details 中每个条目所指的字段。将多余数据移至 attributes。 |
| 400 CUSTOM_FIELDS_INVALID | attributes 不符合自定义字段 schema。 | 阅读 schema 并修复 details 中所指的字段。 |
| 409 DUPLICATE_ENTITY | externalId,或者文档类型 + id,已经在您的商户中使用。 | 重用现有实体。使用 列出实体 查找它。 |
| 422 INCOMPLETE_KYC_DATA | 缺少最低限度的 KYC 数据。 | 添加 name 和 lastname(个人)或 name(公司)。 |
{
"type": "about:blank",
"title": "Validation error",
"status": 400,
"detail": "Validation error",
"instance": "/api/entity/v1/entities",
"code": "CUSTOM_FIELDS_INVALID",
"correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
"details": [
{
"field": "numberOfEmployees",
"issue": "NOT_IN_OPTIONS"
},
{
"field": "legacyNote",
"issue": "UNKNOWN_FIELD"
}
]
}
税务识别号(
CPF、CNPJ、CUIT、RFC)是一份文件,而不是实体的字段。请在 document 中发送。国家代码必须符合 ISO 3166-1 alpha-3 标准(使用 BRA,而不是 BR)。下一步
上传文件和证明
请附上支持每个已声明文档的文件。
创建实体引用
所有请求字段、响应字段和错误代码。

