logo ← gs-payment-ecommerce / Hooks de Pagamento de Recorrência de Cartão

Hooks de Pagamento de Recorrência de Cartão

#Introdução

Os Hooks de recorrencia de cartão podem ser configurados de acordo com os tipos de eventos desejados. Novos eventos podem ser adicionados conforme a necessidade.

Em casos de falha por problemas de comunicação, autenticação ou indisponibilidade, as notificações serão reenviadas a cada 5 minutos por um período de 2 horas. Após este período o reenvio será a cada 5 horas por um período de 3 dias.

Se após estas tentativas a notificação não tiver sucesso na entrega, será necessário a consulta do status da transação no endpoint:

https://api.gsurfnet.com/gs-payment-ecommerce/v1/payments/card/{gti}

#Tipos de eventos

RECURRENCE_FINALIZATION: Evento emitido quando uma recorrencia é finalizada, seja por sucesso, cancelada por erro ou cancelada manualmente.

Obs: O payload do hook é versionado. As versões indicam os campos que são contidos no payload.

#Payload

#V1.4

versionstringconst: "1.4"
event_typestringconst: "RECURRENCE_FINALIZATION"
entitystringconst: "EcommerceCardRecurrence"
payloadobject
sale_dataobject
Dados referentes a venda.
amountinteger
Valor da venda.
merchant_correlation_idstring
Identificador da venda na loja.
order_idstring
Número do pedido.
submerchant_idstring
Identificador da loja.
recurrence_dataobject
Dados referentes a recorrencia.
idstring
Id da recorrencia.
time_intervalinteger
Intervalo entre cada transação da recorrencia.
time_unit_intervalstring
Unidade de medida do intervalo.
Enum: "MONTH", "DAY"
start_datestring
Data de inicio da recorrencia.
creation_datestring
Data de criação da recorrencia.
recurrence_timesinteger
Quantidade de execuções.
retries_on_errorinteger
Quantidade de tentativas com erro.
success_execution_timesinteger
Quantidade de execuções com sucesso.
actual_errors_countinteger
Quantidade atual de erros ocorridos.
next_payment_datestring | null
Data da próxima transação.
previous_payment_datestring | null
Data da última transação com sucesso.
statusstring
Status da recorrencia.
Enum: "CONCLUDED", "ERROR_CANCELED", "MANUAL_CANCELED", "ACTIVE"
transaction_dataobject
Dados referentes a transação.
cardobject
Cartão utilizado na recorrencia.
masked_cardstring
Cartão mascarado.
card_brandobject
descriptionstring
Descrição da bandeira.
gsurf_codeinteger
Codigo gsurf da bandeira.
use_anti_fraudstring
Uso do anti fraud.
Enum: "FIRST", "ALL", "NEVER"
payerobject
Dados do pagador.
namestring
Nome do pagador.
documentstring
Documento do pagador.

#Exemplo

{
  "version": "1.4",
  "entity": "EcommerceCardRecurrence",
  "event_type": "RECURRENCE_FINALIZATION",
  "payload": {
    "sale_data": {
      "amount": 48655,
      "merchant_correlation_id": "YBOG2LFZAV",
      "order_id": "XPQYTE0XKY",
      "submerchant_id": "48627192000197"
    },
    "recurrence_data": {
      "id": "27c877cb-52cf-46ac-bfeb-cb7b62f7f118",
      "time_interval": 1,
      "time_unit_interval": "MONTH",
      "start_date": "2026-05-08",
      "recurrence_times": 2,
      "retries_on_error": 4,
      "success_execution_times": 0,
      "actual_errors_count": 0,
      "next_payment_date": null,
      "creation_date": "2026-05-08",
      "previous_payment_date": null,
      "status": "MANUAL_CANCELED"
    },
    "transaction_data": {
      "card": {
        "masked_card": "542911******7161",
        "card_brand": {
          "description": "Mastercard",
          "gsurf_code": 55
        }
      },
      "use_anti_fraud": "FIRST",
      "payer": {
        "name": "Jhon Snow",
        "document": "12312312387"
      }
    }
  }
}