Cadastrar um Cliente com Perfis de Verificação

Este guia percorre o cadastro de um cliente pessoa física em dois perfis de verificação ao mesmo tempo, e depois como adicionar um perfil a um cliente que foi criado com apenas um. Para a lista completa de requisitos por perfil, veja a visão geral.

Cadastrar um cliente novo

O exemplo cadastra uma pessoa física mexicana nos perfis A e C.

Crie o cliente com os perfis selecionados

Envie todos os campos que você já tem. Campos exigidos por qualquer um dos dois perfis contam uma única vez para ambos.

curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "Ana",
    "lastName": "García",
    "email": "ana.garcia@example.com",
    "phone": "+525551234567",
    "dateOfBirth": "1990-05-15",
    "address": {
      "line1": "Avenida Reforma 222",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "postalCode": "06600",
      "country": "MEX"
    },
    "enabledVerificationProfiles": ["a", "c"],
    "personalInformation": {
      "nationality": "MEX",
      "countryOfBirth": "MEX",
      "residencyCountry": "MEX",
      "taxIdentificationNumber": "GAAA900515AB1",
      "taxIdentificationNumberType": "rfc",
      "taxIdentificationNumberCountry": "MEX",
      "gender": "female",
      "occupationSocCode": "151252",
      "sourceOfFunds": "salary",
      "accountPurpose": "receive_salary",
      "expectedMonthlyPayments": "5000_9999",
      "employmentStatus": "employed",
      "actingAsIntermediary": false
    }
  }'

Leia o que cada perfil ainda precisa

A resposta lista ambos os perfis como incomplete. Só faltam documentos.

{
  "id": "customer_244a09f15e254288886e419071c92da6",
  "enabledVerificationProfiles": ["a", "c"],
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "required": ["identity_document", "liveness_report_document", "source_of_funds_document"]
      }
    },
    {
      "name": "kyc_profile_c",
      "status": "incomplete",
      "criteria": {
        "required": ["identity_document", "proof_of_address_document", "w8_ben_document", "source_of_funds_document", "liveness_report_document"]
      }
    }
  ]
}

Envie os documentos

Envie cada tipo de documento uma única vez. Um documento que aparece em required em ambos os perfis atende a ambos.

curl -X POST https://api.spherepay.co/v2/document \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  --form 'target="customer"' \
  --form 'targetId="customer_244a09f15e254288886e419071c92da6"' \
  --form 'documentType="id_card"' \
  --form 'country="MEX"' \
  --form 'side="front"' \
  --form 'file=@id-front.jpg'

Repita para o verso do documento de identidade e para proof_of_address_document, w8_ben_document, source_of_funds_document e liveness_report_document.

Aguarde a decisão de cada perfil

Assim que todos os perfis habilitados tiverem criteria.required vazio, o SpherePay envia o cliente para análise e ambos os perfis passam para pending. Nenhuma chamada de submit é necessária. Cada perfil é decidido de forma independente, então consulte GET /v2/customer/{id} periodicamente e aja por perfil. Ou assine os eventos de webhook de clientes: um evento é emitido por perfil por mudança de status, com o nome do perfil em data.verificationProfile.

{
  "verificationProfiles": [
    { "name": "kyc_profile_a", "status": "pending" },
    { "name": "kyc_profile_c", "status": "approved" }
  ]
}

O cliente pode operar com os produtos que o perfil C desbloqueia assim que kyc_profile_c estiver em approved, mesmo enquanto kyc_profile_a ainda está em pending.

O envio aguarda todos os perfis habilitados. Se você selecionar A e C mas fornecer apenas os requisitos de A, nenhum dos dois perfis sai de incomplete. Forneça os requisitos de todos os perfis selecionados, ou selecione menos perfis.

Adicionar um perfil depois

Quando um cliente criado com um perfil precisa de outro — por exemplo, o SpherePay habilita o perfil C para a sua aplicação e o cliente quer enviar USD para o exterior — envie o novo array completo.

Amplie a seleção

curl -X PATCH https://api.spherepay.co/v2/customer/customer_244a09f15e254288886e419071c92da6 \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabledVerificationProfiles": ["a", "c"] }'

Forneça apenas o que o novo perfil ainda precisa

O novo perfil aparece em verificationProfiles. Os campos já fornecidos para A são transferidos como complete; os documentos que você já enviou são reavaliados para C e listados em criteria.pending até que essa verificação termine. Apenas os requisitos específicos de C ficam em required: sex, country_of_birth, nationality, proof_of_address_document e w8_ben_document para um cliente que concluiu A.

curl -X PATCH https://api.spherepay.co/v2/customer/customer_244a09f15e254288886e419071c92da6 \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalInformation": {
      "gender": "female",
      "countryOfBirth": "MEX",
      "nationality": "MEX"
    }
  }'

Em seguida, envie proof_of_address_document e w8_ben_document como na seção anterior.

Aguarde o novo perfil

kyc_profile_c passa para pending por conta própria e é decidido de forma independente. O perfil A não é reavaliado.

Isso funciona quer o perfil A esteja em incomplete, pending ou approved. Os campos que A já avaliou permanecem bloqueados enquanto A estiver em pending ou approved; um PATCH que toque um deles retorna 400 customer/field-locked-by-verification-profile. Veja Quando os dados do cliente podem ser atualizados.

Guias relacionados

Selecionar perfis

O que enabledVerificationProfiles aceita e retorna.

Remover um perfil

Remova um perfil que o cliente não precisa mais.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Cadastrar um Cliente com Perfis de Verificação

Cadastrar um cliente novo

Adicionar um perfil depois

Guias relacionados

Selecionar perfis

Remover um perfil

​Cadastrar um cliente novo

​Adicionar um perfil depois

​Guias relacionados

Selecionar perfis

Remover um perfil

Cadastrar um cliente novo

Adicionar um perfil depois

Guias relacionados