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

# Payment lifecycle

> The statuses of a Broco Pay payment and how your platform handles each one.

A payment starts as `pending` and ends in exactly one final status. Only `succeeded` means money moved.

```mermaid theme={null}
flowchart TD
  A[pending] --> B[succeeded]
  A --> C[declined]
  A --> D[canceled]
  A --> E[expired]
  classDef money fill:#158FAB,stroke:#0E6F86,color:#FFFFFF
  class B money
```

## Statuses

| Status | Meaning | What your platform does |
| - | - | - |
| `pending` | Waiting for the customer to authorize | Do not mark the order as paid |
| `succeeded` | Customer debited, merchant credited | Mark the order as paid and fulfil it |
| `declined` | The payment was refused | Offer another payment method |
| `canceled` | Canceled before authorization | Do not mark the order as paid |
| `expired` | No authorization before `expires_at` | Create a new payment if the customer tries again |

`succeeded`, `declined`, `canceled` and `expired` are final. A final payment never changes status.

## Declined payments

A declined payment includes a `decline_reason`.

| `decline_reason` | Meaning |
| - | - |
| `insufficient_balance` | The customer's balance does not cover the amount |
| `customer_declined` | The customer refused the payment in Broco |

```json Response theme={null}
{
  "id": "pay_9Xc2LmQ7",
  "object": "payment",
  "status": "declined",
  "decline_reason": "insufficient_balance",
  "amount": 1250000,
  "currency": "DZD",
  "order_reference": "ORD-10482"
}
```

## Canceling a payment

While a payment is `pending`, your server can cancel it with `POST /v1/payments/{id}/cancel`, for example when the customer changes the payment method. A payment that already reached a final status cannot be canceled.

## Repeated requests

If your server sends the same creation request twice with the same `Idempotency-Key`, Broco returns the original payment. The customer is debited at most once for one key.

After a payment expired or was declined, a new attempt uses a new key, such as `ORD-10482-attempt-2`.

## Next steps

<CardGroup cols={2}>
  <Card title="Payments API" href="/api-reference/payments">
    The payment object and its operations.
  </Card>

  <Card title="Events & webhooks" href="/developer/events-and-webhooks">
    Receive `payment.succeeded` on your server.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.