Transações

O que é uma transação?

Uma transação representa uma única operação de pagamento processada através da Global API da Getnet. Cada pagamento pode ter uma ou mais transações associadas, dependendo do fluxo de pagamento utilizado. As transações rastreiam o ciclo de vida de um pagamento desde a iniciação até a conclusão, incluindo quaisquer operações pós-venda, como capturas, cancelamentos ou reembolsos.

Na Global API da Getnet, as transações são divididas em transações primárias e secundárias. Cada transação possui um status que indica seu estágio atual de processamento, e você pode rastrear todas as transações relacionadas a um pagamento usando os endpoints de consulta de transações.

Tipos e status de transação

As transações na Global API da Getnet são categorizadas por tipo e rastreadas por status ao longo de seu ciclo de vida. Entender os tipos de transação ajuda você a escolher o fluxo de pagamento correto para o seu caso de uso, enquanto monitorar os status das transações permite que você acompanhe o progresso do pagamento e lide com diferentes resultados adequadamente.

Transações primárias

As transações primárias são as operações de pagamento iniciais que iniciam um fluxo de pagamento. Elas podem ser de um dos seguintes tipos:

Transações de compra

As transações de compra são transações de venda padrão que cobram imediatamente o cartão do cliente:

• CREDIT: Uma transação de compra com cartão de crédito que é processada imediatamente.
• DEBIT: Uma transação de compra com cartão de débito que é processada imediatamente.

Transações de autorização

As transações de autorização reservam fundos no cartão do cliente sem cobrá-los imediatamente. Esses fundos ficam retidos até que você capture a transação:

• CREDIT_AUTHORIZATION: Autoriza um valor de pagamento com cartão de crédito para ser capturado posteriormente.
• CREDIT_PRE_AUTHORIZATION: Pré-autoriza um pagamento com cartão de crédito, normalmente usado para cenários em que o valor final pode variar.

Transações de verificação

As transações de verificação validam se um método de pagamento é válido sem processar uma cobrança real:

• Verificação de cartão: Verifica se o cliente está usando um método de pagamento válido utilizando uma autorização de valor zero.

Transações secundárias

As transações secundárias são operações que afetam uma transação primária existente. Elas modificam o resultado final do pagamento:

Captura

Uma captura finaliza uma transação previamente autorizada, deduzindo os fundos da conta do cliente:

• Pode ser total ou parcial (se a captura parcial for suportada).
• Deve ser realizada dentro do período de validade da autorização.
• Usada em fluxos de pagamento em duas etapas, onde a autorização e a captura são separadas.

Reembolsos

Os reembolsos devolvem fundos ao cliente por uma transação concluída. No sistema da Getnet, a terminologia usada depende de quando o reembolso é processado:

• Cancelamento: Usado quando um reembolso é processado no mesmo dia (D+0) da transação original. Neste ponto, a transação ainda não foi enviada pelo fluxo de Settlement da rede de cartões, então a Getnet a processa como um cancelamento. A transação é anulada antes que o Settlement ocorra.

• Reembolso / Ajuste: Usado quando um reembolso é processado em um dia subsequente (D+1 ou posterior) após a transação original. Neste ponto, a transação já foi enviada através do fluxo de Settlement da rede de cartões, de modo que o reembolso deve ser processado como uma transação de reembolso separada.

Ambas as operações alcançam o mesmo resultado — devolver fundos ao cliente — mas o momento determina qual processo e terminologia a Getnet utiliza. A distinção é importante para fins de conciliação e Settlement.

3D Secure (3DS)

A autenticação 3DS verifica a identidade do portador do cartão antes de processar um pagamento:

• Aprimora a segurança e reduz a responsabilidade por fraudes (Chargeback).
• Pode ser exigida com base no valor da transação, no emissor do cartão ou em regulamentações regionais.
• Pode ser realizada como parte do pagamento inicial ou como uma etapa de verificação separada.

Visão geral dos tipos e status de transação

O diagrama abaixo mostra todos os tipos de transação possíveis na GlobalAPI da Getnet e seus status em potencial. Cada tipo de transação pode transitar por diferentes status dependendo do fluxo de pagamento e do resultado do processamento.

[DIAGRAM_PLACEHOLDER: transaction-statuses-flow.mermaid]

Status das transações

Cada transação pode ter um dos seguintes status, dependendo de sua fase de processamento e tipo de transação:

Status gerais

Status específicos de operação

Alguns tipos de transação retornam status específicos de operação após a conclusão bem-sucedida:

Status de autenticação 3DS

A autenticação 3D Secure usa status específicos:

Ciclo de vida da transação

O ciclo de vida típico de uma transação depende do fluxo de pagamento:

Fluxo de pagamento em etapa única (Compra)

1. A requisição de pagamento é enviada.
2. Status da transação: PENDING → APPROVED ou DENIED.
3. Os fundos são cobrados e processados em Settlement imediatamente.

Fluxo de pagamento em duas etapas (Autorização e Captura)

1. A requisição de autorização é enviada.
2. Status da transação: PENDING → AUTHORIZED ou DENIED.
3. Os fundos são reservados, mas não cobrados.
4. A requisição de captura é enviada (dentro do período de validade).
5. Status da transação: PENDING → CAPTURED ou DENIED.
6. Os fundos são cobrados e processados em Settlement.

Operações pós-venda

• Cancelamento (Mesmo dia / D+0): Reverte um pagamento antes que ele entre no fluxo de Settlement da rede de cartões. O status da transação muda para CANCELED.
• Reembolso (D+1 ou posterior): Devolve os fundos ao cliente após a transação ter passado pelo Settlement através da rede de cartões. O status da transação muda para APPROVED (para a transação de reembolso).

Identificação da transação

Cada transação na Global API da Getnet possui vários identificadores:

• transaction_id: Identificador exclusivo atribuído pela Getnet para a transação.
• payment_id: Identificador que vincula a transação ao seu pagamento pai.
• order_id: Referência do pedido do estabelecimento comercial para a transação. Este é o campo principal que os estabelecimentos comerciais usam para conciliação, pois corresponde ao seu sistema interno de pedidos.
• request_id: Identificador exclusivo para a requisição da API.
• idempotency_key: Chave usada para evitar transações duplicadas (deve ser exclusiva por requisição).

Consultando transações

Você pode consultar os detalhes da transação usando o endpoint Get Transaction, que retorna informações detalhadas sobre uma transação específica, incluindo seu status, valor, carimbos de data/hora (timestamps) e operações relacionadas.

Prática recomendada: Embora você possa consultar transações sob demanda, recomendamos fortemente o uso de Webhooks para receber atualizações de status de transações em tempo real. Webhooks são mais eficientes e escaláveis do que consultar a API repetidamente (polling), pois eles enviam notificações para o seu sistema automaticamente quando os status das transações mudam. Essa abordagem reduz a carga de processamento tanto no seu sistema quanto na API da Getnet, garantindo melhor desempenho e confiabilidade.

Veja também

• Para informações sobre a criação de pagamentos, consulte os guias de pagamento na documentação.
• Para entender como lidar com atualizações de status de transação, consulte Webhooks.
• Para detalhes sobre o processamento seguro de pagamentos, consulte Tokenization e Autenticação 3DS 2.0.