Uma transação é o registro central da plataforma para uma única tentativa de movimentar dinheiro entre um comprador e um vendedor. Toda cobrança — seja originada de um link de checkout hospedado, de uma chamada direta de API, de um ciclo de cobrança de assinatura ou da compra de um ingresso de evento — termina como uma transação, com o mesmo ciclo de vida e o mesmo vocabulário de status. A transação vive em duas camadas ao mesmo tempo:
CamadaFinalidade
Específica do adquirenteVerdade bruta e autoritativa fornecida pela infraestrutura de processamento. Identificada pelo zoop_id. Guarda dados de cartão, plano de parcelamento, ponto de venda, autorização de pagamento, regras de split e histórico.
Agnóstica de adquirenteEspelho usado pelo painel, relatórios, métricas e webhooks de saída. Identificada por um UUID próprio, com vínculos para a conta do vendedor (acquirer_account) e para a conta que efetivamente recebe o dinheiro após um redirecionamento (receiver_account).
As duas camadas são mantidas em sincronia: toda gravação na camada específica enfileira uma tarefa que reconstrói o registro unificado e recalcula as métricas relacionadas. Os fluxos de aplicação de splits e de recebíveis sempre operam sobre o lado unificado.
Ao consumir a API, você quase sempre lê a representação unificada (/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

Um usuário do painel cria uma cobrança avulsa (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

Um servidor de confiança envia valor + comprador + meio de pagamento para um único endpoint. Nenhuma cobrança avulsa é criada.

Cobrança de assinatura

Um assinante (Subscriber) é cobrado no intervalo do seu plano. Cada ciclo cria uma transação.

Checkout de ingresso de evento

Um comprador público reserva ingressos via EventCheckout. Na confirmação, o checkout cria uma transação e abate o estoque.
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.
1

Criar o link de checkout

POST /sales/seller/{seller_id}/checkout-links/ — veja Criar link de checkout.
2

Enviar o comprador para a página de pagamento

O comprador abre /sales/pay/{id}/ (renderizado no servidor) ou sua própria página, que chama Contexto da venda.
3

Pagar a cobrança

A página de pagamento chama Pagar cobrança, que repassa para a infraestrutura de processamento e cria a transação. Um 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.
1

Enviar os detalhes do pagamento

POST /sales/seller/{seller_id}/payment com valor, descrição e um objeto charge. Veja Pagamento direto.
2

Receber o status síncrono

A resposta contém o id da nova transação, o 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 um SubscriptionPayment. Veja Fluxo de assinatura para detalhes — o ciclo de vida da transação a partir desse ponto é idêntico.

​
Checkout de ingresso de evento

O EventCheckout 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:
statusSignificadoAlcançável a partir de
pendingCriada no adquirente, mas ainda não capturada (PIX aguardando o comprador, boleto não pago, cartão pré-autorizado).(inicial)
succeededO adquirente confirmou a captura. Uma transação succeeded com confirmed = "1" é o estado canônico de “paga”.pending
failedA captura foi recusada ou retornou erro. Terminal, a não ser que o comprador tente novamente com uma nova transação.pending
canceledA transação foi anulada antes de liquidar (cartões) ou marcada como expirada (PIX/boleto).pending, succeeded
reversedO adquirente reverteu a captura depois do fato.succeeded
refundedEstornada integralmente.succeeded
partial_refundedEstornada parcialmente.succeeded
dispute / disputedO comprador abriu uma contestação. Fundos ficam retidos enquanto se aguarda a resposta do estabelecimento.succeeded
dispute.succeededO estabelecimento venceu a disputa.disputed
charged_backChargeback definitivo contra o estabelecimento.disputed
deletedSoft delete no lado unificado (usado quando o adquirente deixa de retornar o registro).qualquer um
Existe uma distinção entre “capturada / pré-autorizada” para cartões, mas ela é representada nos campos 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.
As transições não são impostas localmente — toda mudança é orientada por um webhook do adquirente (veja abaixo). A cadeia disputa → chargeback é o único caminho em que múltiplos estados terminais podem ocorrer em sequência.

​
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:
EventoEfeito
transaction.createdLinha inicial em pending.
transaction.succeededCaptura os fundos; recebíveis são criados em seguida.
transaction.failedEncerra o fluxo; nenhum recebível é gerado.
transaction.canceledAnulada.
transaction.disputed / buyer.transaction.disputedAciona o estado de disputa; fundos congelados no adquirente.
transaction.reversed / buyer.transaction.reversedReversão de uma captura anteriormente bem-sucedida.
transaction.charged_backChargeback definitivo.
transaction.void.succeeded / transaction.void.failedResultado de uma anulação explícita.
receivable.created, receivable.canceledAcionam um job separado de sincronização de recebíveis — veja abaixo.
O sistema de jobs está detalhado em Webhooks e jobs. Importante: os jobs são deduplicados por 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:
CampoSignificado
amountValor líquido que cairá na receiver_account na data expected_on.
gross_amountValor antes das tarifas do adquirente (MDR).
anticipation_feeCobrada quando o vendedor antecipa o recebível.
installmentNúmero da parcela para vendas no crédito (1 para PIX/boleto).
expected_onData prevista de liquidação dos fundos.
paid_atPreenchida quando o recebível é efetivamente pago (consolidado em um depósito).
statusVeja a tabela abaixo.
has_split_linkedtrue se este recebível pertence a uma regra de split (e não à cota do próprio vendedor).
Valores possíveis de status do recebível:
statusSignificado
predictedPrevisão; ainda não elegível para antecipação.
waiting_fundsO adquirente já comprometeu o recebível; aguardando data de liquidação.
paidLiquidado; consolidado em um depósito (AccountDeposit).
deletedOriginalmente canceled no adquirente; substituído localmente porque o termo é mais familiar no painel.
refundedO recebível foi revertido em razão de um estorno ou chargeback.
Quando uma transação é concluída, a plataforma sincroniza automaticamente os recebíveis ao salvar. Recebíveis obsoletos (retornados anteriormente mas ausentes na última resposta do adquirente) são marcados como 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:

​
6. Estornos e chargebacks

A plataforma expõe duas formas de desfazer uma captura:
Chame 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.
Iniciado pelo comprador junto ao emissor do cartão. A plataforma recebe 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.
Um estorno ou chargeback bem-sucedido marca os recebíveis originadores como refunded e, no lado bancário, gera um lançamento negativo no próximo depósito.

​
7. Armadilhas comuns

Tanto Pagar cobrança quanto Pagamento direto criarão duas transações se você chamá-los duas vezes. Não existe uma chave global de idempotência no corpo da requisição. Mitigações:
  • 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 um GET quando a resposta do adquirente vem com status 200 em vez de 201).
  • Para links de checkout: rastreie linhas OnlineSellPayment no seu código — uma por tentativa de pagamento — e verifique o status antes de reemitir.
Internamente, cada transação tem dois identificadores: o UUID interno (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.
Uma chamada de cobrança direta retorna um status da resposta síncrona do adquirente, mas o estado definitivo chega via webhook + job. Para PIX e boleto, a resposta síncrona é sempre 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 são reconciliados com o adquirente a cada gravação de transação. Se um recebível some da resposta do adquirente, ele é marcado como 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.
O adquirente retorna 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.
1

Criar o link de checkout

curl -X POST "https://api.dlpay.cloud/sales/seller/$SELLER_ID/checkout-links/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order #4521",
    "reference": "4521",
    "description": "Custom T-shirt",
    "amount": "199.90",
    "expiration_date": "2026-06-30",
    "payment_plan": "<online_sell_payment_plan_id>"
  }'
2

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.
3

Receber o webhook

Configure um webhook do vendedor (Criar webhook do vendedor) para transaction.update.status. No sucesso, você recebe um payload succeeded — neste ponto, a transação unificada já existe.
4

Ler a transação unificada

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.dlpay.cloud/unified/accounts/sellers/$ACCOUNT_ID/transactions/$TX_ID/"
Veja Recuperar transação.
5

Listar os recebíveis produzidos

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.dlpay.cloud/unified/accounts/sellers/$ACCOUNT_ID/receivables/?transaction=$TX_ID"
Veja Listar recebíveis.
6

Aguardar o depósito

Assim que a data 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.

​
Páginas relacionadas

Splits e planos

Como o valor de cada transação é dividido entre vendedor, agentes, distribuidores, desenvolvedor e plataforma.

Modelo unificado de dados

O padrão de espelhamento entre a camada específica do adquirente e a camada unificada que sustenta tudo descrito aqui.

Webhooks e jobs

A infraestrutura por trás do tratamento de webhooks do adquirente, jobs em segundo plano e webhooks de saída para vendedores.

API de transações

A lista completa de endpoints de transação na referência da API.