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"
}

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

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. A equipe Astron Pay analisa e aprova (APPROVED) — o evento receiver.kyc_approved é enviado via webhook.

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

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