> ## 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 Status Flow

> Understanding the lifecycle of PIX and Boleto payin transactions

We will show the life cycle for PIX payins, regarding the status.

The notification sent to the payin will be based on the **final status**. The final status represents when the payment is completed, approved by compliance, and with the value available for withdrawal.

<Warning>
  Charges (payin) in final statuses (`CREATED`, `CANCELED`, `REJECTED`) can no longer be updated.
</Warning>

The status will follow the cycle below:

## Payin pix

```mermaid theme={null}
graph TD
    A[CREATED] --> B[Payment done by customer]
    A --> C[CANCELED]
    B --> D[CREDITED]
    B --> E[REJECTED]
    C --> F[Canceled by operator/Expired]
    D --> G[Payment approved]
    E --> H[Blocked by compliance review]
    G --> I[SEND WEBHOOK]
    H --> J[SEND WEBHOOK]
    I --> K[Webhook sent]
    J --> L[Webhook sent]
```

<Note>
  PIX notifications will be completed shortly after the payment is done.
</Note>

### PIX Status Flow Explanation

1. **CREATED**: Initial status when the payin is created
2. **CANCELED**: Canceled by operator or expired
3. **PAID**: Payment paid
4. **CREDITED**: Payment credited, final status
5. **REJECTED**: Blocked by compliance review

## Payin boleto

```mermaid theme={null}
graph TD
    A[CREATED] --> B[Payment done by customer]
    A --> C[DROP_REQUESTED]
    B --> D[CREDITED]
    C --> E[CANCELED]
    C --> F[When the boleto has expired and it goes into the cancellation queue]
    D --> G[Payment approved]
    E --> H[Canceled by operator/Expired]
    G --> I[SEND WEBHOOK]
    H --> J[SEND WEBHOOK]
    I --> K[Webhook sent]
    J --> L[Webhook sent]
```

<Warning>
  Payments made by boleto do not undergo compliance validation after payment, as it is not possible to automatically refund this form of payment.

  Boleto notifications will be cleared after 1 working days.
</Warning>

<Note>
  **Note**: refunds done to customers must be done apart the api
</Note>

### Boleto Status Flow Explanation

1. **CREATED**: Initial status when the payin is created
2. **CANCELED**: Canceled by operator or expired
3. **PAID**: Payment paid
4. **CREDITED**: Payment credited, final status
5. **DROP\_REQUESTED**: Cancellation requested (when boleto expires)
6. **REJECTED**: Blocked by compliance review

## Possible charge (payin) status

| ENUM\_CODE | STATUS          | EXPLANATION                                                  |   |
| ---------- | --------------- | ------------------------------------------------------------ | - |
| 1          | Created         | The first status when the payin is created                   |   |
| 2          | Canceled        | Payin canceled due to expiration                             |   |
| 3          | Paid            | Payin successfully paid                                      |   |
| 4          | Credited        | The amount is paid and available for withdrawal / settlement |   |
| 5          | Drop\_requested | Payin transaction canceled at the user's request             |   |
| 7          | Rejected        | Payin rejected due to compliance reason                      |   |

## Status Details

<AccordionGroup>
  <Accordion title="1 - Created">
    **Initial Status**

    This is the first status when a payin is created. The charge is active and waiting for payment.

    * **PIX**: QR Code is generated and ready to be scanned
    * **Boleto**: Boleto is generated and ready to be paid

    **Next possible statuses**: Paid, Canceled, Drop\_requested
  </Accordion>

  <Accordion title="2 - Canceled">
    **Final Status**

    Payin was canceled due to expiration or operator action.

    **Reasons**:

    * Expiration date reached without payment
    * Manual cancellation by operator
    * Automatic cancellation after drop\_requested

    **Action**: No further action possible. Create a new charge if needed.
  </Accordion>

  <Accordion title="3 - Paid">
    **Intermediate Status**

    Payment was successfully received but is under compliance review.

    * **PIX**: Payment confirmed in seconds
    * **Boleto**: Payment confirmed after bank processing (D+1)

    **Next possible statuses**: Credited, Rejected
  </Accordion>

  <Accordion title="4 - Credited">
    **Final Status**

    The amount is paid, approved by compliance, and available for withdrawal/settlement.

    **This is the final success status**:

    * Funds are available in your wallet
    * Webhook notification is sent
    * Ready for withdrawal or settlement

    **Action**: Funds can now be withdrawn or used for payouts.
  </Accordion>

  <Accordion title="5 - Drop_requested">
    **Intermediate Status**

    Payin transaction cancellation was requested.

    * **PIX**: Canceled immediately
    * **Boleto**: Enters cancellation queue, takes 1 working day

    **Next status**: Canceled
  </Accordion>

  <Accordion title="7 - Rejected">
    **Final Status**

    Payin was rejected due to compliance validation.

    **Reasons**:

    * Failed compliance checks
    * Document restrictions
    * Blocked by fraud prevention

    **Action**: Review rejection reason and create new charge with corrected information.

    See [Rejection Reasons](/payin/rejection-reasons) for more details.
  </Accordion>
</AccordionGroup>

## Webhook Notifications

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

### When to Expect Webhooks

<Tabs>
  <Tab title="PIX">
    **Fast Notifications**

    PIX webhooks are sent shortly after payment completion:

    * **Credited**: Within seconds after payment approval
    * **Rejected**: Within seconds if compliance fails
    * **Canceled**: Immediately after cancellation

    ```json theme={null}
    {
      "id": 32457,
      "invoice": "YOUR-CODE1234",
      "end_to_end": "END-TO-END-ID",
      "status": {
        "id": 5,
        "name": "Credited"
      },
      "updated_at": "2024-06-12T23:04:27.000000Z"
    }
    ```
  </Tab>

  <Tab title="Boleto">
    **Delayed Notifications**

    Boleto webhooks are sent after bank processing:

    * **Credited**: After 1 working day
    * **Canceled**: After 1 working day (if drop\_requested)

    ```json theme={null}
    {
      "id": 32462,
      "invoice": "YOUR-CODE1234",
      "end_to_end": "END-TO-END-ID",
      "status": {
        "id": 5,
        "name": "Credited"
      },
      "updated_at": "2024-06-13T10:30:00.000000Z"
    }
    ```
  </Tab>
</Tabs>

## Status Monitoring

<Steps>
  <Step title="Create Charge">
    Use [Create Charge](/api-reference/cash-in/payin/create-charge) to generate a PIX or Boleto.

    Initial status: **Created (1)**
  </Step>

  <Step title="Customer Pays">
    Customer completes payment using PIX QR Code or Boleto.

    Status changes to: **Paid (4)**
  </Step>

  <Step title="Compliance Check">
    System performs compliance validation (PIX only).

    * If approved: **Credited (5)**
    * If rejected: **Rejected (3)**
  </Step>

  <Step title="Receive Webhook">
    Webhook notification is sent with final status.

    Your system receives the notification and processes accordingly.
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Implement Webhooks" icon="webhook" color="#10B981">
    Always use webhooks instead of polling to receive status updates efficiently.
  </Card>

  <Card title="Handle All Statuses" icon="list-check" color="#3B82F6">
    Implement logic to handle all possible statuses in your application.
  </Card>

  <Card title="Check Final Status" icon="circle-check" color="#8B5CF6">
    Only consider Credited (5) as successful payment. Paid (4) is still under review.
  </Card>

  <Card title="Monitor Expiration" icon="clock" color="#F59E0B">
    Set appropriate expiration dates and handle Canceled status gracefully.
  </Card>
</CardGroup>

## Related Resources

<CardGroup cols={3}>
  <Card title="Create Charge" icon="plus" href="/api-reference/cash-in/payin/create-charge">
    Create PIX or Boleto charges
  </Card>

  <Card title="Get Charge" icon="magnifying-glass" href="/api-reference/cash-in/payin/get-unique-charge">
    Check charge status
  </Card>

  <Card title="Payin Webhook" icon="webhook" href="/cash-in/payin-webhook">
    Configure webhook notifications
  </Card>

  <Card title="Rejection Reasons" icon="circle-xmark" href="/cash-in/rejection-reasons">
    Understand rejection codes
  </Card>

  <Card title="About Charges" icon="circle-info" href="/cash-in/about-charges">
    Learn about Payin solutions
  </Card>

  <Card title="Refunds" icon="rotate-left" href="/api-reference/cash-in/refund/create-refund">
    Process PIX refunds
  </Card>
</CardGroup>

## Additional Notes

<Note>
  You can check the reasons why our compliance team will reject a payment in our article [Rejection reasons payin](/cash-in/rejection-reasons).
</Note>

<Note>
  For more information about webhook, check our article [Webhook Signature Documentation](/api-reference/account/webhook/webhook-setup).
</Note>