> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astronpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding de receiver

> Passo-a-passo para criar receivers e enviar KYC.

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

## 1. Criar o receiver

```bash theme={null}
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"
  }'
```

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

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 |

```bash theme={null}
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                        |

```bash theme={null}
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           |

```bash theme={null}
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"
```

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

## 3. Acompanhar status

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

```bash theme={null}
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.                                      |