Webhook

When the payment is made or canceled due to a problem with the central bank, the address provided in the webhook_url field during its generation will be activated through the POST method informing the status update, and a status code 2xx is expected as a return.

informação

If the webhook is not accessed successfully, that is, it is not obtained as a return status code 2xx, there is a retry policy where the request will be redone 10 times spaced by the formula below in seconds.

$$t=30*(2^{numberofattempts/2})$$

aviso

From 19/12/2024 onwards, we will send 3 new fields on the webhook:

• e2eid - End to End ID from the financial institution
• reference_id - Idempotency key to avoid duplicated transactions
• cancel_reason - Reason of the cancellation, only sent if status is canceled

Webhook Payload (Payment made)

{
  "id": "cd54974b-36f2-4efc-a735-2521cc5389ff", // transaction ID
  "value": 30,
  "status": "paid",
  "pix_key_type": "email",
  "pix_key": "teste@zenetpay.com",
  "paid_at": "2022-03-07T22:36:53+00:00", // isoformat
  "description": "12a3", // this field can be used to send the third party ID, to help with conciliation in possible failures with the central bank
  "hash": "MD5(SECRET_KEY + id + STRING(value) + status)", // MD5 hexadecimal digits
  "bank_name": "Cooperativa de Crédito Rural de São Miguel do Oeste - Sulcredi/São Miguel",
  "reference_id": "REF12345", // your internal ID
  "e2eid": "E2E123456789PIX" // E2E ID of the transaction
}

informação

In the hash field, a hash generated from the MD5 algorithm will be sent and can be used for conference and webhook integrity.

The string used to generate the hash is composed as follows: SECRET_KEY+id+string(value)+status

SECRET_KEY = Must be requested from support

ID = the payload id field

value = the payload value field (formatted with two decimal places, such as 30.00)

status = the payload status field

aviso

The value field must be converted to two decimal places and separated by a period before passing the MD5 algorithm:

• Correct: 30.00
• Wrong: 30
• Wrong: 30.0

Below is an example of a payload (json), how the generating string of the hash (string_hash) and generated hash (md5_string_hash) is formed:

{
  "id": "58f1ada2-95ae-49bb-b73a-fd961922daaa",
  "value": 46.0,
  "status": "paid",
  "pix_key_type": "email",
  "pix_key": "teste@zenetpay.com",
  "paid_at": "2022-08-02T12:42:03+00:00",
  "hash": "85e51fe29341627194eef2ba04a2f742",
  "bank_name": null
}

string_hash = SECRETKEY58f1ada2-95ae-49bb-b73a-fd961922daaa46.00paid
md5_string_hash = 740fe542f21cf4a3a11b57ec1a24ec2e

Webhook Payload (Payment canceled)

It is not common for the payment to be canceled, but it can occur if the PIX key entered is invalid or the account is blocked by the central bank, for example.

{
  "id": "200e3d7c-a917-4992-8f9b-7d3191d2e279", // Transaction ID
  "value": 30,
  "status": "canceled",
  "pix_key_type": "email",
  "pix_key": "teste@zenetpay.com",
  "canceled_at": "2022-03-07T22:36:53+00:00", // isoformat
  "hash": "MD5(SECRET_KEY + id + STRING(value) + status)", // MD5 hexadecimal digits
  "bank_name": null,
  "reference_id": "REF12345",
  "e2eid": "E2E123456789PIX",
  "cancel_reason": "Saldo insuficiente"
}