Reembolsar um Pagamento

Este guia explica como processar reembolsos e cancelamentos para pagamentos previamente autorizados usando a Global API da Getnet. Dependendo de quando o reembolso for solicitado, o sistema o tratará de forma diferente: os reembolsos no mesmo dia são processados como cancelamentos (anulando a transação antes da liquidação), enquanto os reembolsos no dia seguinte são processados como ajustes (depois que a liquidação ocorreu).

Requisitos

Antes de seguir os passos, você precisa:

• Criar sua conta entrando em contato com a equipe de Suporte à Integração para obter suas credenciais de API client_id e client_secret.
• Gerar seu token com suas credenciais usando o endpoint de Authentication.
• Ter um pagamento previamente autorizado ou capturado que você deseja reembolsar.

A Getnet fornece uma Postman Collection para ajudá-lo a replicar esses casos de uso localmente. Você também pode testar a API no ambiente sandbox usando a API Reference disponível na documentação.

Especificidades dos Casos de Uso

Ao integrar qualquer solução da Getnet, aplicam-se requisitos específicos do mercado. Certifique-se de revisar os recursos abaixo antes de entrar em produção:

• Códigos de moeda
• Tipos de documento
• Impostos e regulamentações locais

Você também pode usar cartões de teste para simular cenários específicos. Mais informações sobre os requisitos específicos para cada país podem ser encontradas na seção Developer Resources da documentação da Getnet.

Disponibilidade da plataforma

O suporte a reembolso e cancelamento varia por país, bandeira do cartão e método de pagamento. Para uma referência completa dos esquemas de cartão suportados e regras específicas para cada mercado, consulte a Disponibilidade de Cancelamentos e Reembolsos.

Entendendo o Momento do Reembolso

A Global API da Getnet lida com reembolsos de forma diferente com base em quando eles são solicitados em relação à transação original:

Cancelamentos no Mesmo Dia (D+0)

Quando um reembolso é processado no mesmo dia da transação original, antes do horário de corte diário, ele é processado como um cancelamento. A transação é anulada antes de entrar no fluxo de liquidação da rede.

Características:

• Apenas reembolsos totais são permitidos (reembolsos parciais não suportados)
• A transação é anulada antes da liquidação
• Processamento mais rápido, pois os fundos nunca saem da conta do cliente

Para horários de corte e disponibilidade específicos de cada país, consulte a referência de Core Cards.

Reembolsos no Dia Seguinte (D+1 ou Posterior)

Quando um reembolso é processado no dia seguinte à transação original ou mais tarde, após o horário de corte diário, ele é processado como um reembolso/ajuste. Neste ponto, a transação já foi enviada através do fluxo de liquidação da rede de cartões.

Características:

• Tanto reembolsos totais quanto parciais são permitidos (sujeito à disponibilidade no país)
• Processado como uma transação de reembolso separada através do sistema de liquidação
• Pode demorar mais para refletir na conta do cliente

Para obter informações específicas do país sobre a disponibilidade de reembolso parcial, consulte a referência de Core Cards.

O diagrama abaixo ilustra o fluxo de reembolso, mostrando os diferentes caminhos para cancelamentos no mesmo dia em oposição aos reembolsos no dia seguinte:

Processo de Reembolso de Pagamento

Esta seção o orienta através do processo de reembolso de uma transação de pagamento.

A tabela abaixo lista os campos mínimos que você precisa enviar:

Reembolsos Parciais: O campo amount permite que você especifique um valor de reembolso parcial (igual ou inferior à transação original). No entanto, os reembolsos parciais estão disponíveis apenas a partir de D+1 em diante e a disponibilidade varia por país. Para obter informações específicas do país, consulte a referência de Core Cards.

Etapa 1: Solicitar o Reembolso ou Cancelamento

Apesar do nome do endpoint, este endpoint lida com os cancelamentos no mesmo dia e os reembolsos no dia seguinte automaticamente com base no momento da solicitação.

Para processar um reembolso ou cancelamento, use o endpoint de Cancel Payment.

Requisição O bloco de código a seguir mostra um exemplo de uma solicitação de reembolso total:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/cancel \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "payment_method": "CREDIT"
}'

Exemplo de uma solicitação de reembolso parcial (disponível apenas em D+1 ou posterior, sujeito à disponibilidade no país):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/cancel \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "b2c3d4e5-f6a7-5890-bcde-fg2345678901",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "payment_method": "CREDIT",
  "amount": 50000
}'

Resposta Exemplo de resposta de cancelamento bem-sucedido:

{
  "idempotency_key": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "amount": 118708,
  "currency": "BRL",
  "status": "CANCELED",
  "reason_code": "00",
  "reason_message": "Cancellation successful",
  "canceled_at": "2025-10-31T14:30:25.166Z"
}

Exemplo de resposta de cancelamento negado:

{
  "idempotency_key": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "amount": 118708,
  "currency": "BRL",
  "status": "DENIED",
  "reason_code": "05",
  "reason_message": "Cancellation not allowed - transaction already settled"
}

Etapa 2: Verificar o Status do Reembolso

Para confirmar que o reembolso foi processado com sucesso, verifique o campo status na resposta:

• CANCELED: O reembolso foi processado com sucesso
• DENIED: O reembolso foi rejeitado

Se o reembolso foi negado, verifique os campos reason_code e reason_message para obter mais detalhes sobre o motivo da falha no reembolso.

Você também pode consultar o status da transação a qualquer momento usando o endpoint de Get Transaction. Para atualizações em tempo real, é recomendável usar Webhooks para receber notificações para cada alteração de status.

Reembolsar Pagamentos Combinados

Pagamentos combinados requerem um tratamento especial ao processar reembolsos:

Transações com Cartão

• O cancelamento está disponível para transações confirmadas feitas há mais de 1 dia.

Cartões de Crédito

• Pagamentos combinados com cartões de crédito podem ser cancelados por meio de uma solicitação que inclui o mesmo número de objetos de pagamento enviado na solicitação de autorização anterior.
• Dependendo do status da autorização da transação atual, o cancelamento pode ser revertido no mesmo dia (já confirmada) ou em até 7 dias (já autorizada).

Para cancelar um pagamento combinado, use o endpoint de Combined Payments - Cancel em vez do endpoint de cancelamento normal.

Melhores Práticas

Ao processar reembolsos, siga estas melhores práticas:

1. Esteja ciente dos horários de corte diários para o seu mercado para entender se o seu reembolso será processado como um cancelamento no mesmo dia ou um reembolso no dia seguinte.
2. Lembre-se de que reembolsos parciais estão disponíveis apenas a partir de D+1 em diante e a disponibilidade varia por país. Verifique a referência de Core Cards para obter informações específicas do país.
3. Sempre use uma idempotency_key exclusiva para cada solicitação de reembolso para evitar reembolsos duplicados acidentais.
4. Use webhooks para receber atualizações em tempo real sobre o processamento de reembolsos em vez de consultar repetidamente a API (polling).
5. Mantenha o payment_id, payment_method e amount da transação original para facilitar o processamento do reembolso.

Próximos Passos

Agora que você entende como reembolsar pagamentos, você pode explorar mais recursos da Global API da Getnet:

• Aprenda a criar Pagamentos Combinados.
• Aprenda a criar Pagamentos Parcelados.
• Explore Webhooks para receber atualizações de transações em tempo real.
• Entenda o Ciclo de Vida da Transação em detalhes.