Webhook

When the payment of the charge is made, the address provided in the webhook_url field during charge creation will be triggered using the POST method with the status update. An HTTP 2xx status is expected as the response.

informação

If the webhook call is not successful (that is, your endpoint does not return an HTTP 2xx status), a retry policy is applied. The request is retried up to 10 times, with intervals defined by the formula below (in seconds).

$$t = 30 \cdot \left( 2^{\frac{\mathrm{numberOfAttempts}}{2}} \right)$$

aviso

From 19/12/2024 onward, Lulipay sends 3 new fields in the webhook payload:

• e2eid - End-to-End ID from the financial institution
• payer_cpf - CPF of the person who paid the QR Code
• buyer_cpf - CPF of the person who generated the QR Code

Webhook Payload (Successfully Paid)

{
  "id": "bac1b8d7-24ce-4b53-b6d9-babd3aa60968", // transaction ID
  "value": 30,
  "status": "paid",
  "paid_at": "2022-03-08T17:24:53+00:00", // ISO format
  "description": "12a3", // can be used as third-party ID for reconciliation
  "hash": "MD5(SECRET_KEY + id + STRING(value) + status)", // MD5 hexadecimal digits
  "e2eid": "E2E123456789PIX",
  "payer_cpf": "12345678909",
  "buyer_cpf": "12345678909"
}

informação

The hash field contains an MD5-generated hash that can be used to validate webhook integrity.

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

• SECRET_KEY: must be requested from support
• id: payload field id
• value: payload field value (must be formatted with 2 decimal places, e.g. 30.00)
• status: payload field status

aviso

The value field must always be converted to two decimal places and use a dot before applying MD5:

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

Below is an example of a webhook payload and how the source string (string_hash) and resulting hash (md5_string_hash) are formed:

{
  "id": "58f1ada2-95ae-49bb-b73a-fd961922daaa",
  "value": 46.0,
  "status": "paid",
  "paid_at": "2022-08-02T12:42:03+00:00",
  "hash": "85e51fe29341627194eef2ba04a2f742"
}

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