# Webhook

A maioria das transações nas integrações do Aurix Pay é assíncrona, ou seja, processos em segundo plano completam e confirmam a transação. Para se comunicar de forma eficaz com sistemas externos e clientes, utilizamos **webhooks**.

***

#### **Especificações Técnicas**

**Requisitos do Endpoint**

* **Método:** HTTP POST
* **Formato:** Carga útil (payload) em JSON
* **Timeout:** 3 segundos (um código de status HTTP 2XX é necessário para confirmar o recebimento)

**Política de Tentativas (Retry)**

* **Tentativas:** 5 no total
* **Backoff exponencial:**
  * 1ª falha: 16 segundos
  * 2ª falha: 32 segundos
  * 3ª falha: 104 segundos
  * 4ª falha: 208 segundos\
    \&#xNAN;*(O intervalo dobra a cada tentativa)*

**Requisitos de Segurança**

* **HTTPS é obrigatório** para todos os endpoints.
* Valide **certificados SSL**.
* Implemente **autenticação básica (Basic Auth)** ou **verificação de assinatura**.

***

#### **Exemplos de Payload de Webhook**

**Pagamento Recebido (Pendente)**

```json
{
  "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..."
    }
  }
}
```

**Pagamento Recebido (Aprovado)**

```json
{
  "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..."
    }
  }
}
```

**Pagamento Recebido (Recusado)**

```json
{
  "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..."
    }
  }
}
```

**Pagamento Enviado (Pendente)**

```json
{
  "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"
  }
}
```

**Pagamento Enviado (Aprovado)**

```json
{
  "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"
  }
}
```

***

**Pagamento Enviado (Recusado)**

```json
{
  "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"
  }
}
```

**Infração Criada**

```json
{
  "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
}
```

**Infração atualizada**

```json
{
  "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
}
```

#### **Observações Importantes**

* **Sempre retorne HTTP 200 imediatamente** (mesmo que o processamento seja assíncrono).
* Logs de falhas ficam disponíveis no **dashboard por 72 horas**.