Convenções da API

​

Autenticação

Todos os endpoints exigem um bearer token (Authorization: Bearer <token>), exceto GET /v1/health.

​

Princípios

• Cotação e operação são domínios separados. A cotação (POST /v1/fx/quotes) é apenas preço e não cria remessa. A remessa nasce da operação que você quer realizar; na v1, um withdrawal para um beneficiário: POST /v1/fx/quotes → POST /v1/remittances/withdrawals.
• A cotação é apenas preço: um único preço, igual para PREFUNDED e CREDIT, válido para qualquer remetente seu. A única tarifa da remessa é o spread de câmbio, em percentual. O custo da antecipação (CREDIT) segue o contrato e é cobrado no lote de liquidação. Remetente, beneficiário, finalidade e funding são informados no withdrawal.
• USDC Inventory: você pode contratar câmbio antecipadamente. Uma cotação com usage = INVENTORY é usada uma única vez para criar um Inventory Lot (POST /v1/inventories), que fixa taxa, volume e validade e gera a promessa de pagamento em USDC. O lote é consumido depois por withdrawals com funding.mode = INVENTORY. Veja USDC Inventory.
• Valores monetários são strings decimais. Valores de requisição devem ser maiores que zero.
• Listas usam paginação por cursor (cursor, limit; a resposta traz nextCursor).

​

Rate limiting

Respostas 429 trazem Retry-After (segundos). Respeite o header e aplique backoff exponencial com jitter.

​

Erros

Todo erro retorna ApiError. O campo code segue o catálogo abaixo. Novos códigos podem ser adicionados sem mudança de versão, então trate códigos desconhecidos pelo status HTTP.

​

Entrega de webhooks

Os eventos estão listados em Notificações (webhooks). Cada entrega é um POST com envelope WebhookEvent e estes headers:

• LBPay-Event-Id: igual a eventId. Use para deduplicar; a entrega é at-least-once.
• LBPay-Timestamp: unix epoch (segundos) do envio.
• LBPay-Signature: v1=<hex(HMAC-SHA256(signingSecret, timestamp + "." + rawBody))>. Rejeite a entrega se a assinatura não bater ou se a diferença entre agora e o timestamp for maior que 300 segundos.

Responda 2xx em até 10 segundos. Falhas são reenviadas com backoff exponencial por até 24 horas. A ordem de entrega não é garantida: use occurredAt e o estado do recurso, ou consulte o recurso via GET.

​

Chaves de conciliação

Toda remessa é rastreável pelas mesmas chaves em todos os objetos: externalId (seu ID, único na sua conta e imutável), quoteId, remittanceId, settlementId (CREDIT), transactionId (pagamento Pix) e inventoryId (INVENTORY).

• Quote → remittanceId, externalId (preenchidos quando a cotação é usada por um withdrawal)
• Remittance → externalId, quoteId (null em INVENTORY), inventoryId (INVENTORY), settlement.settlementId, payout.transactionId
• Inventory → quoteId (cotação que originou o lote), externalId; remessas do lote em GET /v1/remittances?inventoryId=
• SettlementItem → remittanceId, externalId, quoteId, transactionId
• WalletTransaction → remittanceId, externalId, quoteId, settlementId
• Receipt → remittanceId, externalId, quoteId, transactionId
• Webhooks de remessa → snapshot completo da Remittance