> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Payin Webhook

> Receive real-time notifications about payin status changes

Webhooks allow you to receive automatic notifications about payin events in real-time. When a payin status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data.

## How It Works

1. **Configure your notification URL** when creating the payin charge using the `notification_url` parameter
2. **Receive notifications** automatically when payin status changes
3. **Process the payload** containing the complete payin details
4. **Return a 200 OK** response to acknowledge receipt

<Note>
  Webhooks are sent only for **final statuses**: Credited, Canceled, Rejected
</Note>

## Setting Up Webhooks

To receive webhook notifications for payin transactions, include the `notification_url` parameter when [creating a charge](/api-reference/cash-in/payin/create-charge):

```json theme={null}
{
  "invoice": "ORDER-12345",
  "notification_url": "https://your-domain.com/webhooks/payin",
  "payment_method": "pix",
  "amount": 10000,
  "currency": "BRL",
  "country": "BR",
  "buyer": { ... }
}
```

The notification URL is defined in the `notification_url` field in the request body when creating a charge. Each charge can have its own notification URL, allowing you to route notifications to different endpoints based on your needs.

## Webhook Payload

When a payin status changes, you'll receive a POST request with the following data:

### Response Fields

<ResponseField name="id" type="integer">
  Payin ID

  Example: `113589233`
</ResponseField>

<ResponseField name="hash" type="string">
  Unique hash identifier for the payin transaction

  Example: `54a3cbc66f4ec54a10826edc62ff3f8f8f706c5c54a9db22e1f57fcfff4516d8`
</ResponseField>

<ResponseField name="invoice" type="string">
  Payin invoice

  Example: `eb21ce52-2897-475b-85af-a5201f4035bf`
</ResponseField>

<ResponseField name="end_to_end" type="string">
  Payin end-to-end identifier

  Example: `E12345678202603191234567890AB1`
</ResponseField>

<ResponseField name="status" type="object">
  Object that contains the current status of your payin.

  <Expandable title="Status Object">
    <ResponseField name="id" type="integer">
      Current status ID of your payin

      Example: `4`
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the current status of your payin

      Example: `Credited`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status_detail" type="object">
  This object will only be returned if the payin is rejected and the merchant is using the "Account Mismatch" functionality. It provides more details on the reason for the rejection.

  <Expandable title="Status Detail Object">
    <ResponseField name="code" type="string">
      Code that represents the reason for the rejection

      Example: `WE0001`

      See [Status Detail Codes](#status-detail-codes) table below for all possible values.
    </ResponseField>

    <ResponseField name="detail" type="string">
      Explanation of the reason for the rejection

      Example: `The payment was made from an unregistered account.`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update of your payin.

  Format: `<date-time>`

  Example: `2024-09-09T20:55:56.000000Z`
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata about the payment.

  <Expandable title="Metadata Object">
    <ResponseField name="paid_amount" type="number">
      Amount paid by the end user.

      <Warning>
        Since the `paid_amount` parameter contains sensitive financial information, we recommend considering this data only if you are verifying the webhook signature.
      </Warning>

      Example: `97`
    </ResponseField>

    <ResponseField name="payer" type="object">
      Information about the payer of the payin.

      <Expandable title="Payer Object">
        <ResponseField name="document" type="string">
          Payer's document (CPF/CNPJ)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bank_payer" type="object">
      Information about the end user's bank account used to pay the QR Code.

      <Expandable title="Bank Payer Object">
        <ResponseField name="name" type="string">
          Bank name

          Example: `033 - BCO SANTANDER (BRASIL) S.A.`
        </ResponseField>

        <ResponseField name="bank_ispb" type="string">
          Bank ISPB code
        </ResponseField>

        <ResponseField name="bank_account" type="string">
          Bank account number
        </ResponseField>

        <ResponseField name="bank_branch" type="string">
          Bank branch (agência)
        </ResponseField>

        <ResponseField name="bank_account_type" type="string">
          Account type (e.g. `CACC` for checking account)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Payload

```json theme={null}
{
  "id": 123456789,
  "hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "invoice": "ORDER-12345",
  "end_to_end": "E12345678202603191234567890AB1",
  "status": {
    "id": 4,
    "name": "Credited"
  },
  "metadata": {
    "paid_amount": 97,
    "payer": {
      "document": "12345678900"
    },
    "bank_payer": {
      "name": "033 - BCO SANTANDER (BRASIL) S.A.",
      "bank_ispb": "60746948",
      "bank_account": "12345678",
      "bank_branch": "1234",
      "bank_account_type": "CACC"
    }
  },
  "updated_at": "2026-03-19T15:13:18.000000Z"
}
```

## Status Codes

Common payin status codes:

| Status ID | Status Name     | Description                                 |
| --------- | --------------- | ------------------------------------------- |
| 1         | Created         | Charge has been created                     |
| 2         | Canceled        | Charge canceled due to expiration           |
| 3         | Rejected        | Charge rejected due to compliance           |
| 4         | Paid            | Charge successfully paid                    |
| 5         | Credited        | Amount is paid and available for withdrawal |
| 6         | Drop\_requested | Cancellation requested                      |

See [Payin Status Flow](/cash-in/status-flow) for detailed status information.

## Status Detail Codes

When a PIX transaction is rejected, the `status_detail.code` field provides specific information about the rejection reason:

| Code                                              | Description                                           |
| ------------------------------------------------- | ----------------------------------------------------- |
| `reason_payer_divergence`                         | CPF mismatch                                          |
| `reason_payer_restriction_deceased_holder`        | CPF restriction: deceased holder                      |
| `reason_payer_restriction_canceled`               | CPF restriction: canceled document                    |
| `reason_payer_restriction_suspended`              | CPF restriction: suspended document                   |
| `reason_payer_pending_regularization`             | CPF restriction: pending regularization               |
| `reason_payer_restriction_unknown`                | CPF restriction: unknown document                     |
| `gl_cpf_payer_restriction_underage`               | CPF restriction: underage (Brazilian law)             |
| `reason_payer_restriction_age_above_limit`        | Restriction: age above limit (> 80 years)             |
| `pending_challenge`                               | Pending challenge                                     |
| `reason_payer_restriction_receita`                | CPF restriction (Tax Authority)                       |
| `payer_restriction_high_risk`                     | CPF high risk                                         |
| `pending_review_manual`                           | Payment created; awaiting manual review               |
| `payer_restriction`                               | Rejected per compliance policy                        |
| `reason_payer_restriction_pep`                    | PEP (Politically Exposed Person)                      |
| `reason_payer_restriction_list_restrict`          | CPF on restriction list                               |
| `reason_payer_restriction_cpf_irregular`          | Irregular CPF                                         |
| `reason_payer_restriction_judicial_block`         | Judicial block                                        |
| `reason_payer_restriction_partners_and_ownership` | Certified restriction (partners/ownership)            |
| `reason_payer_restriction_ofac`                   | CPF on OFAC list                                      |
| `reason_payer_restriction_interpol`               | CPF on INTERPOL list                                  |
| `reason_payer_restriction_onu`                    | CPF on UN list                                        |
| `reason_payer_restriction_euro`                   | CPF on European restriction list                      |
| `WE0001`                                          | The payment was made from an unregistered account     |
| `WE0002`                                          | The payment was made from an unauthorized institution |
| `reason_payer_restriction_pld`                    | KYC restriction                                       |

<Note>
  These codes are only returned when the payin status is **Rejected** and the merchant has the "Account Mismatch" functionality enabled.
</Note>

## Webhook Endpoint Requirements

Your webhook endpoint must:

* **Accept POST requests** - All webhook notifications are sent via POST
* **Use HTTPS** - Only secure HTTPS URLs are accepted
* **Return 200 OK** - Respond with a 200 status code within 5 seconds
* **Be publicly accessible** - The endpoint must be reachable from the internet

## Retry Policy

<Note>
  If your endpoint responds with a failure (status code different from 200), **15 retry attempts** will be made to deliver the webhook notification.
</Note>

## Best Practices

<Note>
  **Always Respond 200 OK**: Your endpoint must respond with HTTP 200 to acknowledge receipt.
</Note>

<Warning>
  **Validate Webhook Signature**: Always validate the webhook signature to ensure it's from WEpayments. See [Webhook Signature Documentation](/concepts/webhooks) for details.
</Warning>

<Warning>
  **Verify paid\_amount**: The `paid_amount` field represents the actual amount paid by the customer and is important to consider for reconciliation.
</Warning>

## Related Resources

<CardGroup cols={2}>
  <Card title="Status Flow" icon="diagram-project" href="/cash-in/status-flow">
    Understand payin status lifecycle
  </Card>
</CardGroup>