Webhook

Configures (creates) the integrator's webhook to receive notifications for customer registration, payment, and chargeback. Here, the URL of the endpoint on the integrator's side must be provided; this endpoint will receive notifications when any asynchronous stage is completed. Examples of Callback are described below.

ATTENTION: To update the webhook URL, it is necessary to request it from the Fiserv team, as it is required to whitelist the URL on the proxy.

GET /v1/webhook

Displays the Integrator Webhook URL, noting that it will only receive callbacks if it is authorized by the Fiserv team.

{
  "WebhookUrl": "https://pix.example.com/api/webhook/"
}

DELETE /v1/webhook

Deletes the Integrator Webhook URL, which will no longer receive notifications for asynchronous processes after deletion. It will only be possible to receive notifications again by registering a new URL and requesting authorization from the Fiserv team.

Customer Callback

POST /client

After the customer registration and the KYC(1) process is completed, the URL registered for the webhook receives the following notification:

{
  "protocolId": "347acdf2-7b01-4191-acff-36bd23639e43",
  "externalProtocolId": "8dd562ee4a7a",
  "omniClientId": "f932d207-573c-439c-b444-6ca26afff066",
  "document": {
    "type": "CNPJ",
    "number": "60664745000187"
  },
  "status": "DONE",
  "errors": [
    {
      "code": "FEP_123",
      "message": "string"
    }
  ]
}

KYC (1) has different approval or rejection criteria depending on the environment. Therefore, it is necessary to send the approved CNPJ(s) to the Fiserv team to facilitate development.

⚠️

When Status = DONE, indicates that processing has been completed in the final KYC(1) status and the customer information can be requested.

Transaction Callback

POST /v1/apm/pix/charges

After the transaction charge is completed, the URL registered in the webhook receives the following notification:

{
  "Pix": {
    "endToEndId": "E049627722026040614084ORtFB8IsmF",
    "txid": "669af61af8d74553948e96514ed24804",
    "chave": "d5150516-3723-45ea-99ec-434e5ad28d45",
    "Status": 1,
    "OperationType": 0,
  }
}

POST /v2/apm/pix/charge/due-date/{txid}

After the transaction [charge due date] is completed, the URL registered in the webhook receives the following notification:

{
  "Pix": {
    "endToEndId": "E049627722026040614084ORtFB8IsmF",
    "txid": "669af61af8d74553948e96514ed24804",
    "chave": "d5150516-3723-45ea-99ec-434e5ad28d45",
    "Status": 1,
    "OperationType": 0,
    "Amount": 363.47,
    "OriginalAmount": 370,
    "Discount": 4.2,
    "Reduction": 2.33,
    "Penalty": 0,
    "Interest": 0
  }
}

POST /v2/apm/pix/charge/static

After the static transaction [charge] is completed, the URL registered in the webhook receives the following notification:

{
  "Pix": {
    "endToEndId": "D13207930202410252046wrzeq7wrQZ8",
    "txid": "D13207930202410252034KgylGnIt2T3",
    "chave": "ac2ce947-fa51-4dd1-a4f9-52181bcc971f",
    "Status": 1,
    "OperationType": 0,
    "Amount": 363.47,
    "OriginalAmount": 370,
    "Discount": 4.2,
    "Reduction": 2.33,
    "Penalty": 0,
    "Interest": 0
  }
}

PUT /v1/apm/pix/{endToEndId}/reverse/{txid}

After the transaction reverse is completed, the URL registered in the webhook receives the following notification:

{
  "Pix": {
    "endToEndId": "D13207930202410252046wrzeq7wrQZ8",
    "txid": "D13207930202410252034KgylGnIt2T3",
    "chave": "ac2ce947-fa51-4dd1-a4f9-52181bcc971f",
    "Status": 1,
    "OperationType": 2
  }
}

Cash-out Callback

POST /v2/apm/pix/cashout

After the cashout request is made, the URL registered in the webhook receives the notification below:

{
  "pix": [
    {
      "txid": "bec7e05d-484e-4814-a432-dde637f84408",
      "endToEndId": null,
      "createdAt": "2025-01-16T09:30:01.5730000",
      "confirmedAt": null,
      "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
      "receiverDocument": "3626416467",
      "receiverPixKey": "[email protected]",
      "amount": 99.99,
      "confirmationKey": "4826e6ec-9bd2-4045-b030-f10e519d584a",
      "status": 2,
      "operationType": 7
    }
  ]
}

Cashout callback occurs in two stages as described below:

⚠️

After requesting a withdrawal operation, some validations will be performed asynchronously, and the request may still be denied. The result of this validation, along with the confirmation key needed for the confirmation request, will be sent to the webhook.

⚠️

Once the confirmation key is received from the notification, the confirmation request (/cashout/confirm) must be called to confirm the withdrawal. After the confirmation, the withdrawal may still fail in some scenarios, thus a new notification will be sent to the configured webhook to indicate whether the withdrawal was completed successfully (status 1) or if it failed (status 2). The confirmation payload has the same structure as the withdrawal request payload, with the only main difference being in the "status."

Additional Information