Quickstart

Este guia mostra o fluxo mais comum: criar um receiver, submeter KYC, gerar cotação e criar uma ordem de payin.

Pré-requisitos

Merchant ativo (status ACTIVE) no dashboard.
Credenciais em mãos (x-api-key + x-api-secret).
URL de webhook configurada (ver Configurando webhooks).

1. Criar 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"
  }'

Resposta (201):

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

Guarde o id — você o usará em todas as operações a seguir. Repare que capabilities.payin já vem true: o receiver pode receber (payin) desde a criação, sem enviar nenhum documento. capabilities.payout só libera depois que o KYC for aprovado (passo 2) — use esse campo, em vez de interpretar o kycStatus, para saber o que está disponível.

2. Submeter KYC

Envie os documentos como multipart/form-data. Para um receiver PF com RG:

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"

Para CNH, substitua documentType=cnh e envie documentPhoto ou documentDigital no lugar de documentFront/documentBack.

O status passa a SUBMITTED, tanto para PF quanto para PJ — não há mais aprovação automática. O receiver já podia receber (payin) desde a criação, e continua podendo enquanto o KYC está em análise; o que fica bloqueado até a aprovação é o payout. A equipe Astron Pay analisa manualmente e, ao aprovar, o status vira APPROVED, capabilities.payout passa a true e o evento receiver.kyc_approved é enviado via webhook. Se a equipe rejeitar (receiver.kyc_rejected), a conta é bloqueada por completo — nem payin nem payout ficam disponíveis. Resubmeter os documentos corrigidos move o kycStatus de volta para SUBMITTED, mas não desbloqueia a conta sozinho: só a nova aprovação da equipe restaura o acesso (payin incluído).

3. Gerar cotação de payin

curl -X POST https://api.astronpay.co/api/v1/quote/payin \
  -H "x-api-key: $API_KEY" \
  -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverId": "rcv_01hxy...",
    "amountBrl": 1000,
    "targetToken": "USDC"
  }'

Resposta:

{
  "quoteId": "qt_01hxy...",
  "merchantId": "mer_01hxy...",
  "receiverId": "rcv_01hxy...",
  "amountBrl": 1000,
  "commercialRate": "5.01",
  "ratePlatform": "5.11",
  "amountToken": "195.69",
  "targetToken": "USDC",
  "expiresAt": "2026-04-17T18:30:30Z"
}

A cotação expira em 30 segundos. Crie a ordem antes disso.

4. Criar ordem de payin

curl -X POST https://api.astronpay.co/api/v1/payin \
  -H "x-api-key: $API_KEY" \
  -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverId": "rcv_01hxy...",
    "quoteId": "qt_01hxy...",
    "destinationWallet": "4k5dSo1EnderecoSolana..."
  }'

Resposta (201):

{
  "id": "ord_01hxy...",
  "type": "PAYIN",
  "status": "AWAITING_PAYMENT",
  "chain": "solana",
  "amountBrl": 1000,
  "targetToken": "USDC",
  "destinationWallet": "4k5dSo1EnderecoSolana...",
  "pixPaymentCode": "00020126...",
  "expiresAt": "2026-04-16T18:31:42.000Z",
  "createdAt": "2026-04-16T18:31:12.000Z"
}

Exiba o pixPaymentCode ao receiver para que ele efetue o pagamento via PIX copia-e-cola.

5. Receber o webhook

Quando o receiver pagar o PIX, você recebe:

{
  "event": "order.completed",
  "orderId": "ord_01hxy...",
  "externalId": "meu-pedido-123",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amountBrl": 1000,
  "amountToken": 199.5,
  "targetToken": "USDC",
  "destinationWallet": "4k5dqkqCg7GXhE8...Solana",
  "txHash": "5Ab...",
  "timestamp": "2026-04-16T18:31:12.000Z",
  "deliveryId": "uuid-da-entrega"
}

Verifique a assinatura do webhook antes de processar (ver Validação).

Introdução

Conceitos

Guias

Webhooks recebidos

Fee Tiers

Receivers

Quote

Payin

Payout

Orders

Merchant Wallet

Ledger

Webhook Config

Pré-requisitos

1. Criar receiver

2. Submeter KYC

3. Gerar cotação de payin

4. Criar ordem de payin

5. Receber o webhook

Próximos passos

​Pré-requisitos

​1. Criar receiver

​2. Submeter KYC

​3. Gerar cotação de payin

​4. Criar ordem de payin

​5. Receber o webhook

​Próximos passos

Pré-requisitos

1. Criar receiver

2. Submeter KYC

3. Gerar cotação de payin

4. Criar ordem de payin

5. Receber o webhook

Próximos passos