Onboarding de receiver

Um receiver já pode receber (payin) assim que é criado, sem enviar nenhum documento. O KYC é o que libera o saque (payout): a equipe Astron Pay revisa os documentos e aprova manualmente. 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, com revisão manual da equipe Astron Pay — vale tanto para PF quanto para PJ, sem aprovação automática. Enquanto o KYC está em SUBMITTED, o receiver continua recebendo (payin) normalmente; o que fica bloqueado até a aprovação é o saque (payout). Em vez de interpretar o kycStatus diretamente, use o campo capabilities retornado no receiver:

{ "kycStatus": "PENDING", "capabilities": { "payin": true, "payout": false } }

capabilities.payin já vem true desde a criação do receiver. capabilities.payout só vira true quando o KYC é aprovado — esse é o sinal recomendado de que o saque está liberado, e também aparece no payload do webhook receiver.kyc_approved.

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_approved — payout liberado (capabilities.payout: true).
receiver.kyc_rejected — inclui rejectionReason; a conta é bloqueada por completo (nem payin nem payout). Resubmeter os documentos volta o kycStatus para SUBMITTED, mas não desbloqueia a conta sozinho — só uma nova aprovação da equipe restaura o acesso.

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.
`PAYOUT_REQUIRES_KYC` (403) ao criar payout	Normal, temporário: o KYC ainda não foi aprovado. Peça os documentos ao receiver, se ainda não enviou.
`RECEIVER_NOT_TRANSACTABLE` (403)	Conta suspensa ou bloqueada pela plataforma. Enviar documentos não resolve; abra um ticket com o suporte.

Introdução

Conceitos

Guias

Webhooks recebidos

Fee Tiers

Receivers

Quote

Payin

Payout

Orders

Merchant Wallet

Ledger

Webhook Config

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