Ledger e liquidações

A Astron Pay mantém um ledger de partidas dobradas para todas as operações. Cada transação gera entries balanceados (débito + crédito) entre contas lógicas.

Tipos de conta

AccountType	Descrição
`RECEIVER_BRL`	Saldo em BRL do receiver
`RECEIVER_CRYPTO`	Saldo em crypto do receiver
`RECEIVER_BANK`	Banco real do receiver (origem do PIX de entrada)
`MERCHANT_FEE`	Taxas do merchant a liquidar
`PLATFORM_FEE`	Taxas da plataforma
`PLATFORM_PIX_HOLDING`	Conta de custódia BRL da plataforma (PIX)
`PLATFORM_CRYPTO_HOLDING`	Conta de custódia crypto da plataforma
`PLATFORM_EQUITY`	Equity da plataforma (reservas em USDC)
`PLATFORM_EQUITY_BRL`	Equity da plataforma em BRL
`PLATFORM_OUTGOING`	Saídas da plataforma (legado)
`PLATFORM_SETTLEMENT`	Liquidações da plataforma (legado)
`EXTERNAL`	Contrapartida externa — pagadores BRL/PIX não identificados
`EXTERNAL_CRYPTO`	Contrapartida on-chain — fonte de depósitos USDC inbound

Idempotência

Cada entry tem um idempotencyKey único baseado no contexto. Padrões:

Fluxo	Chave
Payin — PIX recebido	`payin:pix_received:{orderId}`
Payin — taxa da plataforma	`payin:platform_fee:{orderId}`
Payin — taxa do merchant	`payin:merchant_fee:{orderId}`
Payin — conversão	`payin:conversion:{orderId}`
Payin — transferência saída	`payin:transfer_out:{orderId}`
Payout — depósito crypto	`payout:deposit:{orderId}`
Payout — conversão	`payout:conversion:{orderId}`
Payout — taxa da plataforma	`payout:platform_fee:{orderId}`
Payout — taxa do merchant	`payout:merchant_fee:{orderId}`
Payout — PIX enviado	`payout:pix_out:{orderId}`

Inserções duplicadas com a mesma key são no-ops — garante segurança em retentativas.

Liquidações (settlements)

Periodicamente (diário ou semanal, conforme acordo), as taxas acumuladas no MERCHANT_FEE são sacadas e enviadas via PIX para o merchant. Isso gera um registro Settlement.

Consulta

# Saldo acumulado de taxas
curl https://api.astronpay.co/api/v1/ledger/fees/balance \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"

# Histórico de liquidações
curl https://api.astronpay.co/api/v1/ledger/settlements \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"

# Saldo de um receiver específico
curl https://api.astronpay.co/api/v1/ledger/receivers/$RECEIVER_ID/balance \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"

Ver Consultando saldos para o fluxo completo.

Introdução

Conceitos

Guias

Webhooks recebidos

Ledger e liquidações

Tipos de conta

Idempotência

Liquidações (settlements)

Consulta

​Tipos de conta

​Idempotência

​Liquidações (settlements)

​Consulta

Tipos de conta

Idempotência

Liquidações (settlements)

Consulta