Site

Webhook

Most transactions in Aurix Pay integrations are asynchronous, meaning background processes complete and commit the transaction. To effectively communicate with external systems and customers, we use webhooks.

Technical Specifications

Endpoint Requirements

  • Method: HTTP POST

  • Format: JSON payload

  • Timeout: 3 seconds (a 2XX HTTP status code is required to confirm delivery)

Retry Policy

  1. Attempts: 5 total retries

  2. Exponential backoff:

    • 1st failure: 16 seconds

    • 2nd failure: 32 seconds

    • 3rd failure: 104 seconds

    • 4th failure: 208 seconds

    • (Double the previous interval each time)

Security Requirements

  • HTTPS is mandatory for all endpoints.

  • Validate SSL certificates.

  • Implement basic auth or signature verification.

Example Webhook Payload Payin (Pending)

{
  "event_type": "pix.in",
  "data": {
    "merchant_id": "0197ea98-dc93-732f-a98c-1546fe4566af",
    "bank_account_id": "0197ea98-dc9a-72ad-bbe4-939285db145a",
    "virtual_account_id": "0197ea98-dc9c-71aa-8ced-46ef77577230",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "deposit",
    "amount": "300",
    "currency": "BRL",
    "reference": "212131",
    "status": "pending",
    "initializer": {
      "type": "PIX",
      "id": "0197eaa9-6451-7355-be46-cd687ea5ef0f",
      "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUGXznOg..."
      "br_code": "00020126860014br.gov.bcb.pix2564pix.sandbox.com.br/qr/v3/at/087fb6a4..."
    }
  }
}

Example Webhook Payload Payin (Approved)

{
  "event_type": "pix.in",
  "data": {
    "merchant_id": "0197ea98-dc93-732f-a98c-1546fe4566af",
    "bank_account_id": "0197ea98-dc9a-72ad-bbe4-939285db145a",
    "virtual_account_id": "0197ea98-dc9c-71aa-8ced-46ef77577230",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "deposit",
    "amount": "300",
    "currency": "BRL",
    "reference": "212131",
    "status": "approved",
    "initializer": {
      "type": "PIX",
      "id": "0197eaa9-6451-7355-be46-cd687ea5ef0f",
      "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUGXznOg..."
      "br_code": "00020126860014br.gov.bcb.pix2564pix.sandbox.com.br/qr/v3/at/087fb6a4..."
    }
  }
}

Example Webhook Payload Payin (Declined)

{
  "event_type": "pix.in",
  "data": {
    "merchant_id": "0197ea98-dc93-732f-a98c-1546fe4566af",
    "bank_account_id": "0197ea98-dc9a-72ad-bbe4-939285db145a",
    "virtual_account_id": "0197ea98-dc9c-71aa-8ced-46ef77577230",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "deposit",
    "amount": "300",
    "currency": "BRL",
    "reference": "212131",
    "status": "declined",
    "initializer": {
      "type": "PIX",
      "id": "0197eaa9-6451-7355-be46-cd687ea5ef0f",
      "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUGXznOg..."
      "br_code": "00020126860014br.gov.bcb.pix2564pix.sandbox.com.br/qr/v3/at/087fb6a4..."
    }
  }
}

Example Webhook Payload Payout (Pending)

{
  "event_type": "pix.out",
  "data": {
    "merchant_id": "0197d627-a062-7196-9b5e-04847339e140",
    "bank_account_id": "0197d62a-2ff6-71d8-b62c-9a416dc1f108",
    "virtual_account_id": "0197d62a-2ffa-73ee-8fd8-15dc59659f39",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "withdraw",
    "amount": "100",
    "currency": "BRL",
    "reference": "52ebfe07-e401-4b38-85a2-fc3643dcd227",
    "status": "pending",
    "initializer": null,
    "created_at": "2025-07-04T18:26:28.000Z",
    "updated_at": "2025-07-04T18:26:33.000Z"
  }
}

Example Webhook Payload Payout (Approved)

{
  "event_type": "pix.out",
  "data": {
    "merchant_id": "0197d627-a062-7196-9b5e-04847339e140",
    "bank_account_id": "0197d62a-2ff6-71d8-b62c-9a416dc1f108",
    "virtual_account_id": "0197d62a-2ffa-73ee-8fd8-15dc59659f39",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "withdraw",
    "amount": "100",
    "currency": "BRL",
    "reference": "52ebfe07-e401-4b38-85a2-fc3643dcd227",
    "status": "approved",
    "initializer": null,
    "created_at": "2025-07-04T18:26:28.000Z",
    "updated_at": "2025-07-04T18:26:33.000Z"
  }
}

Example Webhook Payload Payout (Declined)

{
  "event_type": "pix.out",
  "data": {
    "merchant_id": "0197d627-a062-7196-9b5e-04847339e140",
    "bank_account_id": "0197d62a-2ff6-71d8-b62c-9a416dc1f108",
    "virtual_account_id": "0197d62a-2ffa-73ee-8fd8-15dc59659f39",
    "endToEndId": "E357134912025080616503607272518b",
    "type": "withdraw",
    "amount": "100",
    "currency": "BRL",
    "reference": "52ebfe07-e401-4b38-85a2-fc3643dcd227",
    "status": "declined",
    "initializer": null,
    "created_at": "2025-07-04T18:26:28.000Z",
    "updated_at": "2025-07-04T18:26:33.000Z"
  }
}

Example Webhook Payload Payout (Refund)

{
    "event_type": "pix.refund",
    "data": {
        "merchant_id": "0198803c-440f-70ed-9b7b-2389b504e163",
        "bank_account_id": "0198803d-3074-712c-814c-205b546d55f4",
        "virtual_account_id": "0198803d-3088-72ed-b173-c412d9de86ce",
        "endToEndId": "E357134912025080616503607272518b",
        "type": "withdraw",
        "amount": "1",
        "currency": "BRL",
        "reference": "ac9093cf-a817-4083-81b9-b069f1acf7b4",
        "status": "refunded",
        "initializer": null,
        "created_at": "2025-08-07T16:44:41.000Z",
        "updated_at": "2025-08-08T22:39:13.000Z"
    }
}

Example Webhook Infraction Payload (Created)

{
  "event": "infraction.created",
  "payload": {
    "id": "01989fb7-8b31-725e-b3c6-350ae004034f",
    "merchant_id": "01981e2e-8ef0-721d-96e6-b992495f0b2f",
    "virtual_account_id": "01983e7e-4a53-735e-855e-35926d16ead9",
    "end_to_end_id": "E35713491202508071358199765e3c8e",
    "type": "REFUND_REQUEST",
    "status": "WAITING_PSP",
    "reported_by": "DEBITED_PARTICIPANT",
    "report_details": "Modalidade de Golpes não enquadradas nos tipos acima.",
    "analysis_result": null,
    "analysis_details": null,
    "transaction_amount": {
      "amount": 4.26,
      "currency": "BRL"
    },
    "creation_date": "2025-08-05T19:06:00.000000Z",
    "last_modification_date": "2025-08-05T19:06:00.000000Z",
    "defense_histories": null,
    "last_sync_at": "2025-08-12T19:17:42.000000Z",
    "created_at": "2025-08-12T19:17:42.000000Z",
    "updated_at": "2025-08-12T19:17:42.000000Z"
  },
  "timestamp": 1755026262
}

Example Webhook Infraction Payload (Updated)

{
  "event": "infraction.updated",
  "payload": {
    "id": "01989fb7-8b31-725e-b3c6-350ae004034f",
    "merchant_id": "01981e2e-8ef0-721d-96e6-b992495f0b2f",
    "virtual_account_id": "01983e7e-4a53-735e-855e-35926d16ead9",
    "end_to_end_id": "E35713491202508071358199765e3c8e",
    "type": "REFUND_REQUEST",
    "status": "WAITING_PSP",
    "reported_by": "DEBITED_PARTICIPANT",
    "report_details": "Modalidade de Golpes não enquadradas nos tipos acima.",
    "analysis_result": null,
    "analysis_details": null,
    "transaction_amount": {
      "amount": 4.26,
      "currency": "BRL"
    },
    "creation_date": "2025-08-05T19:06:00.000000Z",
    "last_modification_date": "2025-08-05T19:06:00.000000Z",
    "defense_histories": null,
    "last_sync_at": "2025-08-12T19:17:42.000000Z",
    "created_at": "2025-08-12T19:17:42.000000Z",
    "updated_at": "2025-08-12T19:17:42.000000Z"
  },
  "timestamp": 1755026262
}

Key Notes

  1. Always return HTTP 200 immediately (even for async processing).

  2. Failure logs are available in the dashboard for 72 hours.

PreviousRate limit

Last updated