logo ← gs-payment-ecommerce / Hooks de Pagamento de Boleto

Hooks de Pagamento de Boleto

#Introdução

Hooks de boleto 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/slip/{gti}

#Tipos de eventos

CREATION: Evento emitido quando um boleto for criado no gateway (Salvo na base gsurf).

AUTHORIZATION: Evento emitido quando um boleto é autorizado no provedor (Gerado no banco emissor).

AUTHORIZATION_ERROR: Evento emitido quando houver erro na autorização do boleto e todas as retentativas falharam.

OP_CONFIRMATION: Evento emitido quando o banco emissor envia cnabs intermediários. Indica que foi recebida uma liquidação operacional, mas a confirmação do boleto em definitivo virá posteriormente, ou não.

CONFIRMATION: Evento emitido na recepção da confirmação do pagamento. Geralmente via cnab ou hook do banco emissor.

CHANGE: Evento emitido quando há solicitação de alteração de vencimento. O dado é alterado na base gsurf.

CHANGED: Evento emitido quando a solicitação de alteração de vencimento é efetivada no emissor do boleto.

CHANGE_ERROR: Evento emitido quando ocorre erro na alteração de vencimento no banco emissor do boleto e todas as retentativas falharam.

DISABLE: Evento emitido quando há solicitação de baixa do boleto. O dado é alterado na base gsurf

DISABLED: Evento emitido quando a solicitação de baixa é efetivada no banco emissor do boleto.

DISABLE_ERROR: Evento emitido quando ocorre erro na baixa no emissor do boleto e todas as retentativas falharam.

OP_DISABLED: Evento emitido quando há a baixa operacional do boleto através do processamento do cnab ou outro meio (hook por exemplo, se o emissor suportar). Neste caso a baixa veio diretamente do emissor sem passar por alguma requisição através da gsurf.

OP_CONFIRMATION_UNDONE: Evento emitido quando o status de liquidação operacional (OP_CONFIRMATION) é desfeito, pois no houve o recebimento da confirmação definitiva após o período definido para recepção do cnab com os dados finais.

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

#Simulação de eventos em HML

No ambiente de homologação, é possível utilizar o seguinte endpoint com os seguintes parâmetros para simular alguns eventos que necessitam do processamento do cnab para serem emitidos:

POST /payments/slip/event_simulator/{gti}

{
  "event_type": "OP_CONFIRMATION"
}

#Possíveis event_types

CONFIRMATION

OP_CONFIRMATION

OP_DISABLED

OP_CONFIRMATION_UNDONE

DISABLE_ERROR

AUTHORIZATION_ERROR

CHANGE_ERROR

#Payload

#Changelog

Versão

Alterações

V1.3

Adicionado o campo current_amount dentro de sale_data.

V1.2

Mudança no formato das datas (creation_time, update_time), que passaram a incluir o fuso horário (ex: ...T21:35:03-03:00).

V1.1

Adicionado o campo subacquirer_document em payment_data. O campo submerchant_id foi movido de payment_data para sale_data.

V1.0

Estrutura inicial do payload.

#V1.0

versionstringconst: "1.0"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "OP_CONFIRMATION", "CONFIRMATION", "CHANGE", "CHANGE_ERROR", "DISABLE", "DISABLED", "DISABLE_ERROR", "OP_DISABLED"
entitystringconst: "SlipPayment"
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.
installmentsinteger
Número da parcela.
payment_dataobject
Dados do pagamento.
gtistring
Identificador único do boleto.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "OP_CONFIRMED", "OP_DISABLED"
amount_paidinteger
Valor pago.
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.
submerchant_idstring
Identificador da loja.
slip_dataobject
bank_codestring
Código do banco.
bank_accountstring
Número da conta
bank_account_digitinteger
Dígito verificador da conta.
bank_branchstring
Número da agência.
due_datestring
Data de vencimento.
credit_datestring | null
Data de crédito.
op_confirm_timestring | null
Data e hora da confirmação intermediária (se tiver).
digitable_linestring
Linha digitável.
bar_codestring
Código de barras.
bank_issue_numberinteger
Número de emissão do provedor (Nosso número).
bank_issue_number_verifierinteger
Dígito verificador do nosso número.
gsurf_usninteger
Número sequencial gsurf (Seu Número).
gsurf_correlation_idstring
Identificação do boleto no provedor de pagamento
error_infoobject
Atributo recebido somente em eventos Emitidos para erro. Contém os dados com os valores de erro
codestring
Código do erro.
messagestring
Mensagem descritiva do erro.

#Exemplo

{
  "version": "1.0",
  "entity": "SlipPayment",
  "event_type": "AUTHORIZATION_ERROR",
  "payload": {
    "payment_data": {
      "gti": "5290c53a-600e-46a5-b1ae-65b6c2f4685f",
      "status": "AUTHORIZATION_ERROR",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:35:03",
      "update_time": "2022-04-26T21:35:04",
      "effective_time": null,
      "confirm_time": null,
      "submerchant_id": "53391845015"
    },
    "sale_data": {
      "amount": 10000,
      "merchant_correlation_id": "2022042640rv",
      "order_id": "2022042640rv",
      "installments": 1
    },
    "slip_data": {
      "bank_code": "341",
      "bank_account": "52282",
      "bank_account_digit": 4,
      "bank_branch": "2938",
      "due_date": "2022-04-26",
      "credit_date": null,
      "op_confirm_time": null,
      "digitable_line": "34191092060000899293585228240009489670000010000",
      "bar_code": "34194896700000100001092000008992938522824000",
      "bank_issue_number": 20000089,
      "bank_issue_number_verifier": 9,
      "gsurf_usn": 2000000089,
      "gsurf_correlation_id": "29380052282410920000089"
    },
    "error_info": {
      "code": "INTEGRATION_ERROR",
      "message": "Response From Itaú does not represent success! - status_code = 403"
    }
  }
}

#V1.1

versionstringconst: "1.1"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "OP_CONFIRMATION", "CONFIRMATION", "CHANGE", "CHANGE_ERROR", "DISABLE", "DISABLED", "DISABLE_ERROR", "OP_DISABLED"
entitystringconst: "SlipPayment"
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.
installmentsinteger
Número da parcela.
submerchant_idstring
Identificador da loja.
payment_dataobject
Dados do pagamento.
gtistring
Identificador único do boleto.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "OP_CONFIRMED", "OP_DISABLED"
amount_paidinteger
Valor pago.
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
slip_dataobject
bank_codestring
Código do banco.
bank_accountstring
Número da conta
bank_account_digitinteger
Dígito verificador da conta.
bank_branchstring
Número da agência.
due_datestring
Data de vencimento.
credit_datestring | null
Data de crédito.
op_confirm_timestring | null
Data e hora da confirmação intermediária (se tiver).
digitable_linestring
Linha digitável.
bar_codestring
Código de barras.
bank_issue_numberinteger
Número de emissão do provedor (Nosso número).
bank_issue_number_verifierinteger
Dígito verificador do nosso número.
gsurf_usninteger
Número sequencial gsurf (Seu Número).
gsurf_correlation_idstring
Identificação do boleto no provedor de pagamento
error_infoobject
Atributo recebido somente em eventos Emitidos para erro. Contém os dados com os valores de erro
codestring
Código do erro.
messagestring
Mensagem descritiva do erro.

#Exemplo

{
  "version": "1.1",
  "entity": "SlipPayment",
  "event_type": "AUTHORIZATION_ERROR",
  "payload": {
    "payment_data": {
      "gti": "5290c53a-600e-46a5-b1ae-65b6c2f4685f",
      "status": "AUTHORIZATION_ERROR",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:35:03",
      "update_time": "2022-04-26T21:35:04",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 10000,
      "merchant_correlation_id": "2022042640rv",
      "order_id": "2022042640rv",
      "installments": 1,
      "submerchant_id": "53391845015"
    },
    "slip_data": {
      "bank_code": "341",
      "bank_account": "52282",
      "bank_account_digit": 4,
      "bank_branch": "2938",
      "due_date": "2022-04-26",
      "credit_date": null,
      "op_confirm_time": null,
      "digitable_line": "34191092060000899293585228240009489670000010000",
      "bar_code": "34194896700000100001092000008992938522824000",
      "bank_issue_number": 20000089,
      "bank_issue_number_verifier": 9,
      "gsurf_usn": 2000000089,
      "gsurf_correlation_id": "29380052282410920000089"
    },
    "error_info": {
      "code": "INTEGRATION_ERROR",
      "message": "Response From Itaú does not represent success! - status_code = 403"
    }
  }
}

#V1.2

versionstringconst: "1.2"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "OP_CONFIRMATION", "CONFIRMATION", "CHANGE", "CHANGE_ERROR", "DISABLE", "DISABLED", "DISABLE_ERROR", "OP_DISABLED"
entitystringconst: "SlipPayment"
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.
installmentsinteger
Número da parcela.
submerchant_idstring
Identificador da loja.
payment_dataobject
Dados do pagamento.
gtistring
Identificador único do boleto.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "OP_CONFIRMED", "OP_DISABLED"
amount_paidinteger
Valor pago.
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
slip_dataobject
bank_codestring
Código do banco.
bank_accountstring
Número da conta
bank_account_digitinteger
Dígito verificador da conta.
bank_branchstring
Número da agência.
due_datestring
Data de vencimento.
credit_datestring | null
Data de crédito.
op_confirm_timestring | null
Data e hora da confirmação intermediária (se tiver).
digitable_linestring
Linha digitável.
bar_codestring
Código de barras.
bank_issue_numberinteger
Número de emissão do provedor (Nosso número).
bank_issue_number_verifierinteger
Dígito verificador do nosso número.
gsurf_usninteger
Número sequencial gsurf (Seu Número).
gsurf_correlation_idstring
Identificação do boleto no provedor de pagamento
error_infoobject
Atributo recebido somente em eventos Emitidos para erro. Contém os dados com os valores de erro
codestring
Código do erro.
messagestring
Mensagem descritiva do erro.

#Exemplo

{
  "version": "1.2",
  "entity": "SlipPayment",
  "event_type": "AUTHORIZATION_ERROR",
  "payload": {
    "payment_data": {
      "gti": "5290c53a-600e-46a5-b1ae-65b6c2f4685f",
      "status": "AUTHORIZATION_ERROR",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:35:03-03:00",
      "update_time": "2022-04-26T21:35:04-03:00",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 10000,
      "merchant_correlation_id": "2022042640rv",
      "order_id": "2022042640rv",
      "installments": 1,
      "submerchant_id": "53391845015"
    },
    "slip_data": {
      "bank_code": "341",
      "bank_account": "52282",
      "bank_account_digit": 4,
      "bank_branch": "2938",
      "due_date": "2022-04-26",
      "credit_date": null,
      "op_confirm_time": null,
      "digitable_line": "34191092060000899293585228240009489670000010000",
      "bar_code": "34194896700000100001092000008992938522824000",
      "bank_issue_number": 20000089,
      "bank_issue_number_verifier": 9,
      "gsurf_usn": 2000000089,
      "gsurf_correlation_id": "29380052282410920000089"
    },
    "error_info": {
      "code": "INTEGRATION_ERROR",
      "message": "Response From Itaú does not represent success! - status_code = 403"
    }
  }
}

#V1.3

versionstringconst: "1.3"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "OP_CONFIRMATION", "CONFIRMATION", "CHANGE", "CHANGE_ERROR", "DISABLE", "DISABLED", "DISABLE_ERROR", "OP_DISABLED"
entitystringconst: "SlipPayment"
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.
installmentsinteger
Número da parcela.
submerchant_idstring
Identificador da loja.
current_amountinteger
Valor da atual venda.
payment_dataobject
Dados do pagamento.
gtistring
Identificador único do boleto.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "OP_CONFIRMED", "OP_DISABLED"
amount_paidinteger
Valor pago.
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
slip_dataobject
bank_codestring
Código do banco.
bank_accountstring
Número da conta
bank_account_digitinteger
Dígito verificador da conta.
bank_branchstring
Número da agência.
due_datestring
Data de vencimento.
credit_datestring | null
Data de crédito.
op_confirm_timestring | null
Data e hora da confirmação intermediária (se tiver).
digitable_linestring
Linha digitável.
bar_codestring
Código de barras.
bank_issue_numberinteger
Número de emissão do provedor (Nosso número).
bank_issue_number_verifierinteger
Dígito verificador do nosso número.
gsurf_usninteger
Número sequencial gsurf (Seu Número).
gsurf_correlation_idstring
Identificação do boleto no provedor de pagamento
error_infoobject
Atributo recebido somente em eventos Emitidos para erro. Contém os dados com os valores de erro
codestring
Código do erro.
messagestring
Mensagem descritiva do erro.

#Exemplo

{
  "version": "1.3",
  "entity": "SlipPayment",
  "event_type": "AUTHORIZATION_ERROR",
  "payload": {
    "payment_data": {
      "gti": "5290c53a-600e-46a5-b1ae-65b6c2f4685f",
      "status": "AUTHORIZATION_ERROR",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:35:03-03:00",
      "update_time": "2022-04-26T21:35:04-03:00",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 10000,
      "merchant_correlation_id": "2022042640rv",
      "order_id": "2022042640rv",
      "installments": 1,
      "submerchant_id": "53391845015",
      "current_amount": 10000
    },
    "slip_data": {
      "bank_code": "341",
      "bank_account": "52282",
      "bank_account_digit": 4,
      "bank_branch": "2938",
      "due_date": "2022-04-26",
      "credit_date": null,
      "op_confirm_time": null,
      "digitable_line": "34191092060000899293585228240009489670000010000",
      "bar_code": "34194896700000100001092000008992938522824000",
      "bank_issue_number": 20000089,
      "bank_issue_number_verifier": 9,
      "gsurf_usn": 2000000089,
      "gsurf_correlation_id": "29380052282410920000089"
    },
    "error_info": {
      "code": "INTEGRATION_ERROR",
      "message": "Response From Itaú does not represent success! - status_code = 403"
    }
  }
}