Payment Person / KYC

A API de Payment Person permite registrar e validar pessoas físicas ou empresas antes de participarem de transações. Esta é uma etapa obrigatória para conformidade KYC (Know Your Customer) em muitos corredores de pagamento.

Fluxo de Trabalho

Consulte o schema de pessoa — Chame GET /schema/person?countryCode={code} para obter os campos obrigatórios específicos do país (veja Schemas)
Valide a pessoa — Chame POST /person/validate para verificar se os dados atendem aos requisitos de KYC sem criar um registro
Crie a pessoa — Chame POST /person para registrar a pessoa no sistema

Endpoints

POST https://{FQDN}/person
POST https://{FQDN}/person/validate

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Ambos os endpoints aceitam o mesmo corpo de requisição. A única diferença é:

Endpoint	Comportamento
`POST /person`	Cria um registro de payment person
`POST /person/validate`	Valida os dados sem criar um registro

Requisição

Campo	Tipo	Obrigatório	Descrição
`type`	string	Não	Tipo de pessoa: `"INDIVIDUAL"` ou `"BUSINESS"`
`identificationType`	string	Não	Tipo de identificação (ex.: `"NATIONAL_ID"`, `"PASSPORT"`, `"DRIVER_LICENSE"`, `"TAX_ID"`)
`identification`	string	Não	Número de identificação
`gender`	string	Não	Gênero: `"M"` ou `"F"`
`firstName`	string	Não	Nome (obrigatório para pessoas físicas)
`lastName`	string	Não	Sobrenome (obrigatório para pessoas físicas)
`companyName`	string	Não	Razão social da empresa (obrigatório para empresas)
`address`	object	Não	Dados de endereço

Nota: Embora a maioria dos campos esteja marcada como opcional no schema da API, requisitos específicos por país podem torná-los obrigatórios. Sempre consulte GET /schema/person primeiro para determinar quais campos são obrigatórios para um determinado país.

Objeto `address`

Campo	Tipo	Obrigatório	Descrição
`addressLine1`	string	Sim	Linha 1 do endereço
`addressLine2`	string	Não	Linha 2 do endereço
`city`	string	Sim	Nome da cidade
`state`	string	Sim	Estado ou província
`postalCode`	string	Sim	Código postal/CEP
`countryCode`	string	Sim	Código do país (ISO Alpha-2)
`phoneNumber`	string	Sim	Número de telefone
`emailAddress`	string	Sim	Endereço de e-mail

Exemplo — Criar uma Pessoa Física

curl -X POST https://{FQDN}/person \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "INDIVIDUAL",
    "identificationType": "NATIONAL_ID",
    "identification": "050482156",
    "gender": "M",
    "firstName": "John",
    "lastName": "Smith",
    "address": {
      "addressLine1": "4429 Candlewood St",
      "addressLine2": "",
      "city": "Los Angeles",
      "state": "CA",
      "postalCode": "90712",
      "countryCode": "US",
      "phoneNumber": "5551234567",
      "emailAddress": "[email protected]"
    }
  }'

Exemplo — Validar uma Empresa

curl -X POST https://{FQDN}/person/validate \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BUSINESS",
    "identificationType": "TAX_ID",
    "identification": "12-3456789",
    "companyName": "Acme Corp",
    "address": {
      "addressLine1": "100 Market St",
      "addressLine2": "Suite 300",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US",
      "phoneNumber": "4155551234",
      "emailAddress": "[email protected]"
    }
  }'

Resposta — Sucesso (200)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Smith",
  "status": "APPROVED"
}

Resposta — Falha de Validação (200)

{
  "type": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Smith",
  "status": "REJECTED",
  "message": "Identification number does not match country requirements"
}

Próximos Passos

Schemas — Consulte os requisitos de campos específicos por país para pessoas, contas e payouts
Check Account — Valide um método de pagamento antes de transacionar
Push Transaction — Envie payouts a destinatários