Qual a diferença entre Pedido (Order) e Cobrança (Charge)

Resumo rápido

Order = pedido / intenção de venda. Representa o contexto comercial: quem compra, o que está sendo comprado, valor total, parcelas, metadata e regras de negócio.
Charge = ação de cobrança / evento financeiro. Representa a tentativa/registro de cobrança efetiva (autorização, captura, estorno, etc.). Uma order pode ter 1 ou várias charges associadas.

É a entidade de nível de negócio.
Contém informações como uuid do comprador (uuidBuyer), value total, installments, title, description, metadata e dados que descrevem a venda.
A order não é uma cobrança em si — é o agrupador/contrato que descreve a transação a ser cobrada.
A order controla o fluxo: regras de pagamento, parcelamento, soft descriptor, vínculo com split, entre outros.

É a entidade de nível financeiro que representa uma tentativa ou registro de débito contra um meio de pagamento.
Cada charge tem seu próprio uuid, value (pode ser parcial ou total), expirationDate, status e outros campos específicos.
Operações financeiras (capturar, estornar, cancelar, antecipar, consultar status, reprocessar) são feitas sobre charges, não sobre a order.

Parcelamento no tempo (ex.: 3x, 4x sem juros)
- Quando a order é parcelada em fluxo do tempo, são criadas múltiplas charges, uma por parcela.
- Cada charge representa a cobrança daquele vencimento específico (valor da parcela, data de vencimento, status próprio).
- Isso facilita conciliação, reprocessamento de parcelas individualmente e controle de inadimplência por parcela.
Captura única / Antecipação
- Quando a operação é feita via antecipação (ex.: CREDIT_CARD_EARLY_SELLER ou CREDIT_CARD_EARLY_BUYER), normalmente apenas uma charge é criada para a order (representando o valor total que será antecipado).
- Ou seja: em cenários de antecipação, não se fragmenta em múltiplas charges por parcela — a cobrança é consolidada.

Order: tipicamente possui status como SENT, ABANDONED, PAID, CANCELED, LATE, PARTIALLY_PAID, REFUND, CHARGEBACK e PRE_AUTHORIZED.
Charge: status financeiro como PENDING, AUTHORIZED, CAPTURED, CANCELED, REFUNDED, PARTIALLY_REFUNDED, CHARGEBACK, EXPIRED.

Criação de pedido → POST /v2/orders (enviar uuidBuyer, value, installments, payment, metadata, etc.).

Consultas de status → buscar tanto a order quanto as charges associadas; sempre verifique o status da charge para decisões financeiras.
Captura → POST /v2/charges/{uuid}/capture (opera sobre a charge).

Estorno / Refund → ação sobre a charge (ou sobre transação financeira específica retornada pela charge).

Cancelamento → pode existir endpoint de cancelamento de order e/ou de charge — o cancelamento financeiro efetivo age sobre charges.

Guarde ambos os IDs: mantenha order.uuid e charge.uuid no seu sistema para rastrear contexto de negócio e eventos financeiros separadamente.
Conciliação: faça reconciliação financeira por charge (cada charge é um evento financeiro com status e valores próprios).
Webhooks: escute eventos de charge e eventos de order quando existirem — atualize seu domínio por charge e, quando apropriado, sincronize o status da order.
Retries: use o campo retryable para decidir se vale a pena re-tentar a captura. Não tente capturar indefinidamente.
Pré-captura: se adotar pré-captura (capture: false), implemente um processo para: (a) rodar verificações antifraude; (b) capturar dentro do prazo (ex.: 6 dias); (c) cancelar e notificar quando não capturado.
Metadados: utilize metadata na order para ligar facilmente a order/charge ao seu ERP, pedido interno ou referência do cliente.
Erros e idempotência: ao criar orders/charges, use chaves de idempotência para evitar duplicidade em falhas de rede.

Order → camada de aplicação / domínio (o “pedido” que seu negócio precisa rastrear).
Charge → camada de pagamentos / financeira (monitoramento de autorizações, capturas, estornos e repasses).

Last updated 1 month ago

Was this helpful?