/unified/.../transactions/...). O acesso direto ao registro bruto do adquirente é reservado para diagnósticos — veja Recuperar transação legada.1. Caminhos de criação
Uma transação pode nascer de qualquer um dos quatro fluxos. Todos convergem para o mesmo par de registros.Link de checkout hospedado
OnlineSell) e compartilha o link. O comprador acessa a página pública de pagamento e paga via cartão, PIX ou boleto.Cobrança direta via API
Cobrança de assinatura
Subscriber) é cobrado no intervalo do seu plano. Cada ciclo cria uma transação.Checkout de ingresso de evento
EventCheckout. Na confirmação, o checkout cria uma transação e abate o estoque.Link de checkout hospedado
O painel do vendedor cria uma cobrança avulsa (OnlineSell) atrelada a um OnlineSellPaymentPlan. O comprador é enviado para a página pública de pagamento.
Criar o link de checkout
POST /sales/seller/{seller_id}/checkout-links/ — veja Criar link de checkout.Enviar o comprador para a página de pagamento
/sales/pay/{id}/ (renderizado no servidor) ou sua própria página, que chama Contexto da venda.Pagar a cobrança
OnlineSellPayment é registrado ligando o comprador à venda.Cobrança direta via API
Servidor para servidor. Nenhuma cobrança avulsa é criada — útil para fluxos personalizados ou integradores em conformidade com PCI.Enviar os detalhes do pagamento
POST /sales/seller/{seller_id}/payment com valor, descrição e um objeto charge. Veja Pagamento direto.Receber o status síncrono
acquirer_id (id no adquirente) e o status atual. Para PIX, você também recebe o QR code e o payload copia-e-cola; para boleto, recebe uma URL.Cobrança de assinatura
Cada ciclo da assinatura dispara uma tarefa que envia a cobrança ao adquirente e vincula a transação unificada resultante a umSubscriptionPayment. Veja Fluxo de assinatura para detalhes — o ciclo de vida da transação a partir desse ponto é idêntico.
Checkout de ingresso de evento
OEventCheckout agrega o carrinho do comprador e, na confirmação, cria uma transação. O status da transação alimenta as métricas pré-agregadas do evento via uma rotina chamada pelo mesmo job que sincroniza a transação. Veja Bilheteria de eventos.
2. Máquina de estados do status
As strings de status vêm do adquirente e são armazenadas literalmente em ambas as camadas. Os valores em uso são:captured (booleano) e pre_authorization, e não no status. Uma transação de cartão pré-autorizada permanece em status = pending com captured = false e pre_authorization = "captured" após o bloqueio.3. Fluxo webhook → tarefa → unificado
Toda mudança em uma transação após a criação chega à plataforma como um webhook da infraestrutura de processamento. O webhook não altera registros diretamente; ele enfileira uma tarefa que rebusca os dados no adquirente, atualiza o registro específico, espelha para o registro unificado, recalcula métricas e, por fim, dispara os webhooks de saída para os vendedores. Os tipos de evento recebidos do adquirente atualmente tratados:resource_id + job_type enquanto estão em WAITING — uma rajada de webhooks para a mesma transação se reduz a uma única sincronização.
4. Recebíveis
Assim que uma transação de cartão liquida, a infraestrutura gera um recebível por parcela por destinatário. Para PIX e boleto, um único recebível é criado para o vendedor no sucesso. O registro unificado de recebível carrega:status do recebível:
deleted em vez de removidos fisicamente.
Recebíveis são listados em Listar recebíveis.
5. Depósitos (consolidação de liquidações)
Quando o banco efetivamente paga o vendedor, vários recebíveis são consolidados em um único depósito (unified.AccountDeposit). O depósito carrega um ou mais vínculos AccountDepositTransactions — eles relacionam o depósito de volta às transações cujos recebíveis o compõem. O adquirente reporta o evento como uma transferência (transfer.created, transfer.succeeded, etc.), e um job da plataforma constrói o depósito unificado e seus vínculos.
Um depósito é, em essência, a resposta voltada ao vendedor para a pergunta “o que efetivamente caiu na minha conta bancária hoje?”.
Endpoints:
- Listar depósitos
- Transações do depósito — as transações cujos recebíveis estão dentro deste depósito.
- Resumo de depósitos — totais em um intervalo de datas.
6. Estornos e chargebacks
A plataforma expõe duas formas de desfazer uma captura:Anular / cancelar uma transação (iniciada pelo vendedor)
Anular / cancelar uma transação (iniciada pelo vendedor)
POST /sales/seller/{seller_id}/transactions/{id}/void/. A rotina de anulação rejeita o pedido se a transação já estiver confirmed, canceled ou pending, e então solicita a anulação ao adquirente. A resposta do adquirente dispara um webhook que retroalimenta o fluxo padrão e atualiza o status para canceled. Os recebíveis são revertidos automaticamente.Use este caminho para estornos / cancelamentos explícitos feitos pelo vendedor.Disputa / chargeback iniciado pelo comprador
Disputa / chargeback iniciado pelo comprador
transaction.disputed e, mais tarde, dispute.succeeded (estabelecimento ganha) ou transaction.charged_back (estabelecimento perde).Um ChargebackTransaction é uma visão alternativa — a mesma transação física exposta por Listar chargebacks quando o status pertence à família disputa/estorno.refunded e, no lado bancário, gera um lançamento negativo no próximo depósito.
7. Armadilhas comuns
Capturar a mesma intenção em duplicidade
Capturar a mesma intenção em duplicidade
- Para Pagamento direto: em uma nova tentativa com cartão, envie o cartão via
charge.card.id(token) — se o adquirente já aceitou o token, retorna a transação existente em vez de criar uma nova (a view de pagamento volta para umGETquando a resposta do adquirente vem com status200em vez de201). - Para links de checkout: rastreie linhas
OnlineSellPaymentno seu código — uma por tentativa de pagamento — e verifique o status antes de reemitir.
Confundir id e zoop_id
Confundir id e zoop_id
Transaction.id) e o id do adquirente (zoop_id, sem hífens, 32 caracteres). A chave primária da camada unificada é o UUID interno. Webhooks e URLs da API do adquirente usam apenas o zoop_id. A resposta de Pagamento direto expõe ambos como payment.id (interno) e payment.acquirer_id (adquirente). Use o UUID unificado em todos os lugares, exceto quando estiver falando diretamente com o adquirente.Ler o status sem aguardar o webhook
Ler o status sem aguardar o webhook
pending; não faça polling no adquirente. Aguarde o transaction.succeeded no webhook do vendedor (configure um em Webhooks do vendedor) ou consulte o estado mais recente em Recuperar transação.Recebíveis obsoletos
Recebíveis obsoletos
deleted localmente em vez de removido — isso preserva o histórico de auditoria, mas significa que um count(*) sobre todos os recebíveis incluirá linhas canceladas. Filtre por status em qualquer consulta de relatório.Fusos horários em timestamps
Fusos horários em timestamps
created_at / updated_at com offset -03:00, mas os valores estão de fato em UTC. A camada de desserialização sobrescreve o fuso para UTC antes de gravar. Trate todos os timestamps armazenados como UTC; a API os entrega com o offset America/Sao_Paulo. Todos os timestamps obedecem ao formato ISO 8601.Exemplo ponta a ponta
O exemplo abaixo cobra R$ 199,90 de um comprador via link de checkout hospedado e, em seguida, lê a transação unificada resultante e seus recebíveis.Criar o link de checkout
Enviar o comprador para a página de pagamento
https://api.dlpay.cloud/sales/pay/{sell.id}/ — o comprador preenche o formulário e envia. A página chama Pagar cobrança por baixo dos panos.Receber o webhook
transaction.update.status. No sucesso, você recebe um payload succeeded — neste ponto, a transação unificada já existe.Ler a transação unificada
Listar os recebíveis produzidos
Aguardar o depósito
expected_on chega e o adquirente emite transfer.succeeded, os recebíveis são agrupados em um AccountDeposit. Inspecione via Listar depósitos e Transações do depósito.