#Introdução

Os Hooks 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-physical/v1/payments/card/{gti}

#Tipos de eventos

AUTHORIZATION: Evento emitido quando uma transação de cartão é autorizada no provedor (Gerado no banco emissor).

CHANGED: Evento emitido quando uma transação de cartão é estornada no provedor.

AUTHORIZATION_ERROR: Evento emitido quando houver erro na autorização da transação de cartão no provedor.

CONFIRMATION: Evento emitido quando uma transação de cartão é confirmada no provedor.

CONFIRMATION_ERROR: Evento emitido quando houver erro na confirmação da transação de cartão no provedor.

UNDOING: Evento disparado quando a transação é desfeita no provedor. O pagamento não foi realizado.

UNDOING_ERROR: Evento disparado quando houve erro no processo de desfazimento da transação no provedor e esgotou-se as tentativas.

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

#Payload

#V1.0

versionstringconst: "1.0"

event_typestring

Enum: "AUTHORIZATION", "AUTHORIZATION_ERROR", "CONFIRMATION_ERROR", "UNDOING", "UNDOING_ERROR", "CHANGED"

entitystringconst: "CardPayment"

payloadobject

payment_dataobject

gtistring

Identificador único da transação de cartão.

statusstring

Enum: "NEW", "EXPIRED", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "CONFIRMATION_IN_PROGRESS", "CONFIRMED", "CONFIRMATION_ERROR", "UNDOING_IN_PROGRESS", "UNDONE", "UNDOING_ERROR", "DENIED"

channelstring

Canal.

creation_timestring

Data de criação do pagamento.

update_timestring

Data da última atualização do pagamento.

effective_timestring | null

Data do pagamento no provedor.

confirm_timestring | null

Data da confirmação do pagamento no gateway.

subacquirer_documentstring

Documento do subadquirente

creation_originstringconst: "NORMAL"

Origem da criação da transação.

terminal_idstring

Identificador do terminal.

sale_dataobject

amountinteger

Valor da venda.

merchant_correlation_idstring

Identificador da venda na loja.

order_idstring

Número do pedido.

installmentsinteger

Número da parcela.

submerchant_idstring

Identificador da loja.

dynamic_dataarray[object]

Dados dinâmicos. Máximo 100 itens.

keystring

Chave.

valuestring

Valor. Máximo 40 caracteres.

transaction_dataobject

gsurf_usnstring

Número sequencial gsurf.

card_dataobject

masked_panstring | null

Número do cartão mascarado.

card_brandobject

descriptionstring | null

Nome da bandeira do cartão.

gsurf_codeinteger

Código da bandeira na gsurf.

card_brand_idstring

Identificador único da bandeira na gsurf.

entry_modestring

Modo de entrada. Valores permitidos.

Enum: "CHIP", "CONTACTLESS", "MAGNETIC_STRIPE", "TYPED", "TAP_ON_PHONE", "CONTACTLESS_MAGNETIC"

transaction_typestring

Tipo de transação.

Enum: "DEBIT", "CREDIT"

installment_typestring

Tipo de parcelamento.

Enum: "BY_ISSUER", "BY_MERCHANT"

input_modestring

Tipo de Input.

provider_dataobject

Dados do provedor/adquirente.

response_messagestring | null

Mensagem de resposta da provedor/adquirente.

response_codestring | null

Código da resposta da provedor/adquirente.

acquirer_response_messagestring

Mensagem de resposta do adquirente.

acquirer_response_codestring

Código da resposta do adquirente.

authorization_codestring | null

Código de autorização da transação.

acquirer_namestring | null

Nome do adquirente.

provider_namestring | null

Nome do provedor.

provider_idstring | null

Id do resgistro da provedor/adquirente na GSurf.

gsurf_correlation_idstring | null

Identificação da transação de cartão no provedor/adquirente.

acquirer_authorization_usnstring | null

Número sequencial único da autorização da transação no adquirente.

acquirer_confirmation_usnstring | null

Número sequencial único da confirmação da transação no adquirente.

provider_usnstring | null

Número sequencial único da autorização da transação no provedor. Será o mesmo que o acquirer_authorization_usn para casos de comunicação direta com o adquirente.

#Exemplo

{
    "version": "1.0",
    "entity": "CardPayment",
    "event_type": "AUTHORIZATION",
    "payload": {
        "payment_data": {
            "gti": "1b6ba410-64e0-4cc1-a312-2ec6ecbc3a15",
            "status": "AUTHORIZED",
            "channel": "gTapp",
            "creation_time": "2025-02-17T10:38:43-03:00",
            "update_time": "2025-02-17T10:38:50-03:00",
            "effective_time": "2025-02-17T10:38:50-03:00",
            "confirm_time": null,
            "subacquirer_document": "05643319000159",
            "creation_origin": "NORMAL",
            "terminal_id": "094c5ff7"
        },
        "sale_data": {
            "amount": 100,
            "merchant_correlation_id": "POSTAN_VISA_DEBIT_38503",
            "order_id": "VISA_DEBIT_38503",
            "installments": 1,
            "submerchant_id": "53391845015"
        },
        "dynamic_data": [
            {
                "key": "NAME",
                "value": "POSTAN_VISA_DEBIT_38503"
            }
        ],
        "transaction_data": {
            "gsurf_usn": "250217000005",
            "card_data": {
                "masked_pan": "485464******9319",
                "card_brand": {
                    "description": "Visa",
                    "gsurf_code": 85,
                    "card_brand_id": "59782e56-87e1-4230-8782-4246ac9de18e"
                }
            },
            "entry_mode": "TAP_ON_PHONE",
            "transaction_type": "DEBIT",
            "installment_type": "BY_MERCHANT",
            "input_mode": "TAP_ON_PHONE",
            "provider_data": {
                "response_message": "Success",
                "response_code": "00",
                "acquirer_response_message": "APROVADA 854171",
                "acquirer_response_code": "000",
                "authorization_code": "854171",
                "acquirer_name": "Cielo",
                "provider_name": "cielo",
                "provider_id": "0a02e36a-e368-4b95-a5de-929760566d20",
                "gsurf_correlation_id": "7a3cc09c-c991-4921-9586-d549fcb5e78c",
                "acquirer_authorization_usn": "985261",
                "acquirer_confirmation_usn": "985261",
                "provider_usn": "985261"
            }
        }
    }
}

Hooks de Pagamento de Cartão

#Introdução

#Tipos de eventos

#Payload

#V1.0

#Exemplo