logo ← gs-payment-ecommerce / Hook de Pagamento de Pix

Hook de Pagamento de Pix

#Introdução

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

#Tipos de eventos

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

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

AUTHORIZATION_ERROR: Evento emitido quando houver erro na autorização do pix no provedor

CONFIRMATION: Evento emitido na recepção da confirmação do pagamento. Geralmente via hook do banco emissor, ou rotina online de conciliação.

DISABLED: Evento disparado quando há um cancelamento do pix que veio diretamente do emissor sem passar por alguma requisição através da gsurf.

EXPIRATION: Evento emitido quando um pix é expirado impossibilitando seu pagamento

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

#Payload

#Changelog

Versão

Alterações

V1.3

Adicionado o campo current_amount (Valor atual da venda) dentro do objeto sale_data.

V1.2

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

V1.1

Adicionado o campo submerchant_id (Identificador da loja) dentro de sale_data (removido de payment_data). Adicionado o campo subacquirer_document em payment_data. Adicionado o campo due_date_type (com os valores NORMAL ou DIRECT) dentro de pix_data.

V1.0

Estrutura inicial do payload de hooks para pagamentos via Pix.

#V1.0

versionstringconst: "1.0"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "CONFIRMATION", "REFUNDED", "EXPIRATION", "DISABLED"
entitystringconst: "PixPayment"
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 pix.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZED", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "EXPIRED"
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.
pix_dataobject
provider_creation_timestring | null
Data de criação no provedor.
due_datestring
Data de vencimento.
payer_information_requestedstring | null
Mensagem a ser exibida ao pagador.
payer_information_responsestring | null
Mensagem recebida pelo pagador
allows_amount_changeboolean
Indica se é permitido que o pagador altere o valor antes de efetuar o pagamento.
gsurf_usninteger
Número sequencial gsurf.
gsurf_correlation_idstring
Identificação do pix no provedor de pagamento,
emvstring | null
Código onde estão contidos os dados representados na imagem do QR Code.
e2e_idstring | null
Identificação do pix no Bacen
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": "PixPayment",
  "event_type": "AUTHORIZATION",
  "payload": {
    "payment_data": {
      "gti": "bb6ad821-fe48-461e-adb8-f741f704e551",
      "status": "AUTHORIZED",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:47:08",
      "update_time": "2022-04-26T21:47:08",
      "effective_time": null,
      "confirm_time": null,
      "submerchant_id": "53391845015"
    },
    "sale_data": {
      "amount": 100,
      "merchant_correlation_id": "20220426jaqy",
      "order_id": "20220426jaqy",
      "installments": 1
    },
    "pix_data": {
      "provider_creation_time": "2022-04-26T18:47:08.506",
      "due_date": "2022-04-26",
      "payer_information_requested": "O que achou do produto?",
      "payer_information_response": null,
      "allows_amount_change": false,
      "gsurf_usn": 28,
      "gsurf_correlation_id": "bb6ad821fe48461eadb8f741f704e551",
      "emv": "00020101021226910014BR.GOV.BCB.PIX2569spi-h.itau.com.br/pix/qr/v2/cobv/af581bdc-624e-4333-af38-1adaddfa6ce05204000053039865802BR5914PMD BASHAR RIO6009SAO PAULO62070503***6304E7DB",
      "e2e_id": null
    }
  }
}

#V1.1

versionstringconst: "1.1"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "CONFIRMATION", "REFUNDED", "EXPIRATION", "DISABLED"
entitystringconst: "PixPayment"
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 pix.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZED", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "EXPIRED"
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
pix_dataobject
provider_creation_timestring | null
Data de criação no provedor.
due_datestring
Data de vencimento.
due_date_typestring
Enum: "NORMAL", "DIRECT"
payer_information_requestedstring | null
Mensagem a ser exibida ao pagador.
payer_information_responsestring | null
Mensagem recebida pelo pagador
allows_amount_changeboolean
Indica se é permitido que o pagador altere o valor antes de efetuar o pagamento.
gsurf_usninteger
Número sequencial gsurf.
gsurf_correlation_idstring
Identificação do pix no provedor de pagamento,
emvstring | null
Código onde estão contidos os dados representados na imagem do QR Code.
e2e_idstring | null
Identificação do pix no Bacen
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": "PixPayment",
  "event_type": "AUTHORIZATION",
  "payload": {
    "payment_data": {
      "gti": "bb6ad821-fe48-461e-adb8-f741f704e551",
      "status": "AUTHORIZED",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:47:08",
      "update_time": "2022-04-26T21:47:08",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 100,
      "merchant_correlation_id": "20220426jaqy",
      "order_id": "20220426jaqy",
      "installments": 1,
      "submerchant_id": "53391845015"
    },
    "pix_data": {
      "provider_creation_time": "2022-04-26T18:47:08.506",
      "due_date": "2022-04-26",
      "due_date_type": "NORMAL",
      "payer_information_requested": "O que achou do produto?",
      "payer_information_response": null,
      "allows_amount_change": false,
      "gsurf_usn": 28,
      "gsurf_correlation_id": "bb6ad821fe48461eadb8f741f704e551",
      "emv": "00020101021226910014BR.GOV.BCB.PIX2569spi-h.itau.com.br/pix/qr/v2/cobv/af581bdc-624e-4333-af38-1adaddfa6ce05204000053039865802BR5914PMD BASHAR RIO6009SAO PAULO62070503***6304E7DB",
      "e2e_id": null
    }
  }
}

#V1.2

versionstringconst: "1.2"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "CONFIRMATION", "REFUNDED", "EXPIRATION", "DISABLED"
entitystringconst: "PixPayment"
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 pix.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZED", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "EXPIRED"
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
pix_dataobject
provider_creation_timestring | null
Data de criação no provedor.
due_datestring
Data de vencimento.
due_date_typestring
Enum: "NORMAL", "DIRECT"
payer_information_requestedstring | null
Mensagem a ser exibida ao pagador.
payer_information_responsestring | null
Mensagem recebida pelo pagador
allows_amount_changeboolean
Indica se é permitido que o pagador altere o valor antes de efetuar o pagamento.
gsurf_usninteger
Número sequencial gsurf.
gsurf_correlation_idstring
Identificação do pix no provedor de pagamento,
emvstring | null
Código onde estão contidos os dados representados na imagem do QR Code.
e2e_idstring | null
Identificação do pix no Bacen
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": "PixPayment",
  "event_type": "AUTHORIZATION",
  "payload": {
    "payment_data": {
      "gti": "bb6ad821-fe48-461e-adb8-f741f704e551",
      "status": "AUTHORIZED",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:47:08-03:00",
      "update_time": "2022-04-26T21:47:08-03:00",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 100,
      "merchant_correlation_id": "20220426jaqy",
      "order_id": "20220426jaqy",
      "installments": 1,
      "submerchant_id": "53391845015"
    },
    "pix_data": {
      "provider_creation_time": "2022-04-26T18:47:08.506",
      "due_date": "2022-04-26",
      "due_date_type": "NORMAL",
      "payer_information_requested": "O que achou do produto?",
      "payer_information_response": null,
      "allows_amount_change": false,
      "gsurf_usn": 28,
      "gsurf_correlation_id": "bb6ad821fe48461eadb8f741f704e551",
      "emv": "00020101021226910014BR.GOV.BCB.PIX2569spi-h.itau.com.br/pix/qr/v2/cobv/af581bdc-624e-4333-af38-1adaddfa6ce05204000053039865802BR5914PMD BASHAR RIO6009SAO PAULO62070503***6304E7DB",
      "e2e_id": null
    }
  }
}

#V1.3

versionstringconst: "1.3"
event_typestring
Enum: "CREATION", "AUTHORIZATION", "AUTHORIZATION_ERROR", "CONFIRMATION", "REFUNDED", "EXPIRATION", "DISABLED"
entitystringconst: "PixPayment"
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 atual da venda.
payment_dataobject
Dados do pagamento.
gtistring
Identificador único do pix.
statusstring
Status do pagamento.
Enum: "NEW", "AUTHORIZED", "AUTHORIZATION_IN_PROGRESS", "AUTHORIZATION_ERROR", "DISABLED", "CONFIRMED", "EXPIRED"
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
pix_dataobject
provider_creation_timestring | null
Data de criação no provedor.
due_datestring
Data de vencimento.
due_date_typestring
Enum: "NORMAL", "DIRECT"
payer_information_requestedstring | null
Mensagem a ser exibida ao pagador.
payer_information_responsestring | null
Mensagem recebida pelo pagador
allows_amount_changeboolean
Indica se é permitido que o pagador altere o valor antes de efetuar o pagamento.
gsurf_usninteger
Número sequencial gsurf.
gsurf_correlation_idstring
Identificação do pix no provedor de pagamento,
emvstring | null
Código onde estão contidos os dados representados na imagem do QR Code.
e2e_idstring | null
Identificação do pix no Bacen
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": "PixPayment",
  "event_type": "AUTHORIZATION",
  "payload": {
    "payment_data": {
      "gti": "bb6ad821-fe48-461e-adb8-f741f704e551",
      "status": "AUTHORIZED",
      "amount_paid": 0,
      "channel": "ECOMMERCE",
      "creation_time": "2022-04-26T21:47:08-03:00",
      "update_time": "2022-04-26T21:47:08-03:00",
      "effective_time": null,
      "confirm_time": null,
      "subacquirer_document": "35524559000103"
    },
    "sale_data": {
      "amount": 100,
      "merchant_correlation_id": "20220426jaqy",
      "order_id": "20220426jaqy",
      "installments": 1,
      "submerchant_id": "53391845015",
      "current_amount": 100
    },
    "pix_data": {
      "provider_creation_time": "2022-04-26T18:47:08.506",
      "due_date": "2022-04-26",
      "due_date_type": "NORMAL",
      "payer_information_requested": "O que achou do produto?",
      "payer_information_response": null,
      "allows_amount_change": false,
      "gsurf_usn": 28,
      "gsurf_correlation_id": "bb6ad821fe48461eadb8f741f704e551",
      "emv": "00020101021226910014BR.GOV.BCB.PIX2569spi-h.itau.com.br/pix/qr/v2/cobv/af581bdc-624e-4333-af38-1adaddfa6ce05204000053039865802BR5914PMD BASHAR RIO6009SAO PAULO62070503***6304E7DB",
      "e2e_id": null
    }
  }
}