🔗 Cobranças / Links de Pagamento (Receive Requests)

Gera links universais de recebimento — o pagador abre o link e paga via Pix ou envia cripto direto pra carteira do usuário, sem precisar ter conta na plataforma.

1. Criar uma Cobrança

curl -X POST https://api.dexkey.finance/v1/receive-requests \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "fiatAmount": "10000",
    "displayCurrency": "BRL",
    "token": "USDT",
    "blockchain": "polygon",
    "senderType": "EXTERNAL_WALLET",
    "description": "Venda de iPhone 15 Pro"
  }'

fiatAmount: valor em fiat, menor unidade (ex: "10000" = R$ 100,00). Use "0" para valor aberto (pagador decide). Mutuamente exclusivo com amount (valor direto na menor unidade do token).
token: BTC, ETH, USDT, USDC ou BRT.
senderType: tipo de remetente esperado (ex: EXTERNAL_WALLET para carteira externa sem conta na plataforma).

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "requesterId": "660e8400-e29b-41d4-a716-446655440001",
  "receiverId": "660e8400-e29b-41d4-a716-446655440001",
  "chaveDeX": "+5511999999999",
  "amount": "20004001",
  "amountFormatted": "20.004001",
  "fiatAmount": "10000",
  "exchangeRateAtCreation": "4.999000000000000000",
  "displayCurrency": "BRL",
  "token": "USDT",
  "blockchain": "polygon",
  "senderType": "EXTERNAL_WALLET",
  "status": "PENDING",
  "deepLinkUrl": "https://app.etherdex.com/receive/550e8400-e29b-41d4-a716-446655440000",
  "blockchainUri": "ethereum:0x...@137/transfer?address=0x...&uint256=20004001",
  "description": "Venda de iPhone 15 Pro",
  "expiresAt": null,
  "createdAt": "2026-01-20T10:00:00.000Z"
}

amount/amountFormatted: valor no token calculado automaticamente a partir do fiatAmount e da cotação no momento da criação (exchangeRateAtCreation).
deepLinkUrl: link universal — abre a tela de pagamento (Pix ou carteira cripto conforme o caso).
blockchainUri: URI padrão (ERC-681/BIP-21/TRC-URI) para carteiras externas escanearem/abrirem direto.

2. Listar Suas Cobranças

curl "https://api.dexkey.finance/v1/receive-requests?page=1&limit=20" \
  -H "Authorization: Bearer $JWT"

{
  "data": [ /* array de objetos no mesmo formato da seção 1 */ ],
  "total": 12
}

3. Consultar uma Cobrança (Dados Mascarados)

Existem duas variantes — mesmo dado mascarado, diferença é só a autenticação:

Endpoint	Autenticação	Quando usar
`GET /receive-requests/{id}`	Nenhuma	Remetente sem conta na plataforma (ex: pagando via Pix ou carteira externa)
`GET /receive-requests/{id}/public`	JWT do remetente	Remetente que já é um usuário autenticado

curl https://api.dexkey.finance/v1/receive-requests/{id}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chaveDeX": "(11) 9XXXX-1234",
  "receiverName": "João Silva",
  "receiverId": "660e8400-e29b-41d4-a716-446655440001",
  "receiverWalletAddress": "0x4a1b2c3d4e5f6789012345678901234567890abc",
  "amount": "20004001",
  "amountFormatted": "20.004001",
  "displayCurrency": "BRL",
  "token": "USDT",
  "blockchain": "polygon",
  "status": "PENDING",
  "blockchainUri": "ethereum:0x...@137/transfer?address=0x...&uint256=20004001",
  "description": "Venda de iPhone 15 Pro",
  "expiresAt": null
}

Nota: chaveDeX (telefone) vem mascarado, mas receiverId não é mascarado — é o UUID interno real do recebedor, retornado mesmo no endpoint sem autenticação. receiverName aparece de propósito (mesma lógica do Pix — confirmar "pra quem estou pagando" antes de enviar).

404 se a solicitação não existir, já tiver sido paga/cancelada, ou tiver expirado.

4. Cancelar uma Cobrança

curl -X PATCH https://api.dexkey.finance/v1/receive-requests/{id}/cancel \
  -H "Authorization: Bearer $JWT"

Só funciona se o status ainda for PENDING.

409 se já tiver sido paga, cancelada ou expirada.

📖 Referência Completa do Ledger (Saldo, Extrato e Comprovante)

💵 Referência de Taxas (Fees)