Onboarding de receiver

Todo receiver precisa ter KYC aprovado antes de transacionar. Este guia cobre o fluxo completo.

1. Criar o receiver

curl -X POST https://api.astronpay.co/api/v1/receivers \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PF",
    "name": "João Silva",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "document": "12345678901"
  }'

Para pessoa jurídica, use "type": "PJ" e forneça o CNPJ (14 dígitos, somente números) no campo document.

Guarde o id retornado — você o usará em todas as operações a seguir.

2. Submeter documentos de KYC

O endpoint POST /receivers/{id}/kyc/submit aceita multipart/form-data. Os campos obrigatórios dependem do tipo do receiver e do documentType escolhido.

Pessoa física (PF) com RG

Campo	Conteúdo
`documentType`	`"rg"`
`documentFront`	Frente do RG (JPG/PNG/PDF)
`documentBack`	Verso do RG
`selfie`	Selfie segurando o documento

curl -X POST https://api.astronpay.co/api/v1/receivers/$RECEIVER_ID/kyc/submit \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -F "documentType=rg" \
  -F "documentFront=@rg-frente.jpg" \
  -F "documentBack=@rg-verso.jpg" \
  -F "selfie=@selfie.jpg"

Pessoa física (PF) com CNH

Campo	Conteúdo
`documentType`	`"cnh"`
`documentPhoto`	Foto da CNH (ou `documentDigital` para CNH digital)
`selfie`	Selfie segurando o documento

curl -X POST https://api.astronpay.co/api/v1/receivers/$RECEIVER_ID/kyc/submit \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -F "documentType=cnh" \
  -F "documentPhoto=@cnh.jpg" \
  -F "selfie=@selfie.jpg"

Pessoa jurídica (PJ)

Para PJ, além do documento de identidade do sócio (RG ou CNH), são obrigatórios:

Campo	Conteúdo
`documentType`	`"rg"` ou `"cnh"`
`documentFront` / `documentBack`	Documento de identidade do representante (se RG)
`documentPhoto`	Foto da CNH (se CNH)
`selfie`	Selfie do representante
`cnpjCard`	Cartão CNPJ emitido pela Receita Federal
`socialContract`	Contrato social ou estatuto da empresa

curl -X POST https://api.astronpay.co/api/v1/receivers/$RECEIVER_ID/kyc/submit \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET" \
  -F "documentType=rg" \
  -F "documentFront=@rg-frente.jpg" \
  -F "documentBack=@rg-verso.jpg" \
  -F "selfie=@selfie.jpg" \
  -F "cnpjCard=@cnpj.pdf" \
  -F "socialContract=@contrato.pdf"

Arquivos: máximo de 10 MB cada. Formatos aceitos: PNG, JPG, PDF.

3. Acompanhar status

O status passa por PENDING → SUBMITTED → APPROVED | REJECTED.

curl https://api.astronpay.co/api/v1/receivers/$RECEIVER_ID \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"

Ou aguarde o webhook:

receiver.kyc_submitted — documentos recebidos.
receiver.kyc_approved — receiver pronto para transacionar.
receiver.kyc_rejected — inclui rejectionReason; corrija os documentos e resubmeta.

4. Limites

Após aprovação, o receiver recebe limites padrão (BRL diário, contagem diária, janela noturna). Consulte em GET /receivers/{id}/limits. O merchant pode solicitar ajustes via suporte.

Erros comuns

Situação	Correção
Documento inválido (CPF/CNPJ)	Use só dígitos, sem pontuação.
Receiver duplicado (409)	Já existe um receiver com esse documento. Busque via `GET /receivers?search=...`.
Campo de documento faltando	Confirme quais campos são obrigatórios para o `documentType` e tipo do receiver.
Documento ilegível (rejeição)	Refaça a foto em boa iluminação e resubmeta.

Introdução

Conceitos

Guias

Webhooks recebidos

Onboarding de receiver

1. Criar o receiver

2. Submeter documentos de KYC

Pessoa física (PF) com RG

Pessoa física (PF) com CNH

Pessoa jurídica (PJ)

3. Acompanhar status

4. Limites

Erros comuns

​1. Criar o receiver

​2. Submeter documentos de KYC

​Pessoa física (PF) com RG

​Pessoa física (PF) com CNH

​Pessoa jurídica (PJ)

​3. Acompanhar status

​4. Limites

​Erros comuns

1. Criar o receiver

2. Submeter documentos de KYC

Pessoa física (PF) com RG

Pessoa física (PF) com CNH

Pessoa jurídica (PJ)

3. Acompanhar status

4. Limites

Erros comuns