Callbacks de notificação
Além dos webhooks, a Getnet fornece notificações baseadas em callback: o servidor chama as URLs que você fornece (callbacks) para notificar seu sistema sobre eventos de pagamento. Este mecanismo utiliza requisições HTTP GET com dados na query string e é configurado no momento do credenciamento. É distinto dos webhooks oferecidos na Global API, que usam HTTP POST, assinaturas configuráveis e um formato de payload diferente.
Para configurar as notificações da Getnet via callback, você deve informar 4 URLs no momento do seu credenciamento na Plataforma Digital. Cada uma será destinada a receber notificações diferentes dos seguintes tipos:
- Transações de crédito,
- Transações de débito,
- Transações de boleto bancário (boleto),
- Transações recorrentes (assinatura)
Uma vez que as URLs de callback estejam configuradas, a Getnet enviará automaticamente os dados relevantes para cada URL quando o evento especificado ocorrer. Em caso de erro, a informação será reenviada a cada 15 minutos, até 4 vezes.
Recomendamos sempre ficar de olho na data de expiração do certificado para cada URL. Em caso de renovação ou se você precisar modificar alguma das URLs informadas originalmente, por favor, entre em contato com nossa Equipe de Suporte à Integração da Getnet.
Estrutura das notificações
Em termos gerais, as requisições HTTP possuem a seguinte estrutura:
https://YOUR_HOST_EXAMPLE/YOUR_SERVICE_EXAMPLE?query_param_1=valueExample1&query_param_2=valueExample2
Onde:
https://YOUR_HOST/YOUR_SERVICErefere-se a uma das 4 URLs de callback informadas anteriormente.?indica o início da seção da query.query_param_1=valueExample1é um exemplo de um query parameter.&é usado como um conector entre múltiplos query parameters.
As notificações HTTP GET fornecidas pela Getnet incluirão um conjunto específico de query parameters, alguns dos quais são compartilhados entre diferentes eventos de disparo, enquanto outros são únicos e específicos para um único evento de disparo.
Notificações de crédito
Query param compartilhado para todos os eventos Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados a transações de cartão de crédito: Approved, Authorized, Pending, Confirmed, Canceled, Denied e Error.
| Query parameters | Descrição |
|---|---|
| payment_type | (único valor possível:) credit |
| customer_id | (código de Id do cliente) |
| order_id | (número do pedido) |
| payment_id | (Id da transação no formato UUIDv4) |
| amount | (valor da transação) |
| status | (valores possíveis dependendo do tipo de evento da transação:) APPROVED AUTHORIZED PENDING CONFIRMED CANCELED DENIED ERROR |
| number_installments | (número de parcelas) |
| terminal_nsu | (código de autorização gerado pelo emissor quando uma transação é realizada com sucesso) |
| authorization_code | (código de autorização gerado pelo sistema de ecommerce da Getnet) |
Abaixo você encontrará os query parameters adicionais para cada evento específico.
Parâmetros adicionais para eventos de transação Approved, Authorized e Pending
| Query parameters | Descrição |
|---|---|
| acquirer_transaction_id | (código de transação do comprador) |
| authorization_timestamp | (data e hora da autorização) |
| brand | (bandeira do cartão) |
Parâmetros adicionais para eventos de transação Canceled
| Query parameters | Descrição |
|---|---|
| acquirer_transaction_id | (código de transação do comprador) |
Parâmetros adicionais para eventos de transação Denied e Error
| Query parameters | Descrição |
|---|---|
| acquirer_transaction_id | (código de transação do comprador) |
| description_detail | (descrição do erro ocorrido durante a transação) |
| error_code | (código numérico de negação ou erro) |
Notificações de débito
Query param compartilhado para todos os eventos
Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados a transações de cartão de débito: Approved, Denied e Error.
| Query parameters | Descrição |
|---|---|
| payment_type | (único valor possível:) debit |
| customer_id | (código de Id do cliente) |
| order_id | (número do pedido) |
| payment_id | (Id da transação no formato UUIDv4) |
| amount | (valor da transação) |
| status | (valores possíveis dependendo do tipo de evento da transação:) APPROVED DENIED ERROR |
| brand | (bandeira do cartão) |
Abaixo você encontrará os query parameters adicionais para cada evento específico.
Parâmetros adicionais para eventos de transação Approved
| Query parameters | Descrição |
|---|---|
| acquirer_transaction_id | (código de transação do comprador) |
| authorization_timestamp | (data e hora da autorização) |
| terminal_nsu | (código de autorização gerado pelo emissor quando uma transação é realizada com sucesso) |
| authorization_code | (código de autorização gerado pelo sistema de ecommerce da Getnet) |
Parâmetros adicionais para eventos de transação Denied e Error
| Query parameters | Descrição |
|---|---|
| description_detail | (descrição do erro ocorrido durante a transação) |
| error_code | (código numérico de negação ou erro) |
Notificações de boleto bancário (Boleto)
No caso de uma notificação de boleto bancário, ela será enviada em duas etapas. Na primeira etapa, uma notificação é enviada quando o registro do boleto bancário é finalizado e, na segunda etapa, uma notificação é enviada quando o boleto é baixado. O serviço permanece o mesmo; no entanto, os campos de resposta serão diferentes entre as duas etapas.
Primeira Etapa
Query param compartilhado para todos os eventos Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados às ações da primeira etapa: Pending, Denied e Error.
| Query parameters | Descrição |
|---|---|
| payment_type | (único valor possível:) boleto |
| order_id | (número do pedido) |
| payment_id | (identificador do pagamento) |
| amount | (valor do boleto bancário) |
| status | (valores possíveis dependendo do tipo de evento da transação:) PENDING DENIED ERROR |
| bank | (código do banco emissor do boleto bancário. O único valor possível é Banco Santander) |
| our_number | (nosso número. Se você não informar, será gerado pelo banco emissor) |
| typefull_line | (linha digitável do boleto bancário retornada pelo banco emissor) |
| issue_date | (Data de emissão, formato: DDMMYYYY) |
| expiration_date | (Data de vencimento, formato: DDMMYYYY) |
Abaixo você encontrará os query parameters adicionais para cada evento específico.
Parâmetros adicionais para eventos de transação Denied e Error
| Query parameters | Descrição |
|---|---|
| id | (identificador do boleto bancário, formato: UUIDv4. É usado para identificar o boleto bancário para a notificação de baixa) |
| description_detail | (descrição do erro ocorrido durante a transação) |
| error_code | (código numérico de negação ou erro) |
Segunda Etapa
Query param compartilhado para todos os eventos Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados às ações da segunda etapa: Paid e Canceled.
| Query parameters | Descrição |
|---|---|
| id | (identificador do boleto bancário, formato: UUIDv4. É usado para identificar o boleto bancário para a notificação de baixa) |
| amount | (valor do boleto bancário) |
| status | (valores possíveis dependendo do tipo de evento da transação:) PAID CANCELED |
| payment_date | (Data em que o seu cliente paga o boleto bancário, formato: DDMMYYYY) |
Notificações de transações recorrentes (assinatura)
Query param compartilhado para todos os eventos Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados a transações recorrentes: Authorized, Approved, Confirmed, Canceled, Denied e Error.
| Query parameters | Descrição |
|---|---|
| payment_type | (único valor possível:) credit |
| customer_id | (código de Id do cliente) |
| order_id | (número do pedido) |
| payment_id | (Id da transação no formato UUIDv4) |
| amount | (valor da transação) |
| status | (valores possíveis dependendo do tipo de evento da transação:) AUTHORIZED APPROVED CONFIRMED CANCELED DENIED ERROR |
| authorization_timestamp | (data e hora da autorização) |
| acquirer_transaction_id | (código de transação do comprador) |
| subscription_id | (identificador da assinatura, formato: UUIDv4) |
| plan_id | (identificador do plano usado na assinatura, formato: UUIDv4) |
| charge_id | (identificador da cobrança, formato: UUIDv4) |
| number_installments | (número de parcelas) |
| billing_number | (número da parcela processada) |
| brand | (bandeira do cartão) |
| terminal_nsu | (código de autorização gerado pelo emissor quando uma transação é realizada com sucesso) |
| authorization_code | (código de autorização gerado pelo sistema de ecommerce da Getnet) |
| retry_number | (número de tentativas) |
Abaixo você encontrará os query parameters adicionais para cada evento específico.
Parâmetros adicionais para eventos de transação Denied e Error
| Query parameters | Descrição |
|---|---|
| description_detail | (descrição do erro ocorrido durante a transação) |
| error_code | (código numérico de negação ou erro) |
Notificações de método de pagamento alternativo (PIX)
Query param compartilhado para todos os eventos
Abaixo você encontrará a lista dos query params compartilhados entre todos os eventos relacionados a transações PIX: Approved, Denied e Error.
| Query parameters | Descrição |
|---|---|
| payment_type | (único valor possível:) pix |
| customer_id | (código de Id do cliente) |
| order_id | (número do pedido) |
| payment_id | (Id da transação no formato UUIDv4) |
| amount | (valor da transação) |
| status | (valores possíveis dependendo do tipo de evento da transação:) APPROVED DENIED ERROR |
| transaction_id | (identificador da transação na instituição PSP após a geração do QR Code) |
| transaction_timestamp | (data e hora da transação PIX, formato: ISO) |
| terminal_nsu | (código de autorização gerado pelo emissor quando uma transação é realizada com sucesso) |
Abaixo você encontrará os query parameters adicionais para cada evento específico.
Parâmetros adicionais para eventos de transação Approved
| Query parameters | Descrição |
|---|---|
| payer_psp_name | Nome da instituição PSP do pagador |
| payer_psp_code | Código da instituição PSP do pagador |
| payer_name | Nome do pagador |
| payer_cnpj | Número do CNPJ do pagador para pessoa jurídica |
| payer_cpf | Número do CPF do pagador para pessoa física |
| receiver_psp_name | Nome da instituição PSP do recebedor |
| receiver_psp_code | Código da instituição PSP do recebedor |
| receiver_name | Nome do recebedor |
| receiver_cnpj | Número do CNPJ do recebedor para pessoa jurídica |
| receiver_cpf | Número do CPF do recebedor para pessoa física |
Parâmetros adicionais para eventos de transação Denied e Error
| Query parameters | Descrição |
|---|---|
| description_detail | (descrição do erro ocorrido durante a transação) |