> ## 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.

# Broco Pay overview

> Let customers pay from their Broco balance at your online checkout.

Broco Pay lets a customer pay an online order from their Broco balance. The customer's balance is debited and the merchant's balance is credited. The money stays inside the Broco network.

## How a payment works

```mermaid theme={null}
flowchart TD

  A["Your server creates the payment<br/>status: pending"]:::step --> B["Customer authorizes in Broco"]:::check
  B --> C["Broco debits the customer<br/>and credits the merchant<br/>status: succeeded"]:::money
  C -.-> D["payment.succeeded<br/>sent to your server"]:::notify
  D --> E["Your server confirms the order"]:::step
  classDef money fill:#158FAB,stroke:#0E6F86,color:#FFFFFF
  classDef check fill:#E8F4F7,stroke:#158FAB,color:#0E1C29
  classDef notify fill:#FFF6C2,stroke:#B89400,color:#0E1C29,stroke-dasharray:4 3
  classDef step fill:#FFFFFF,stroke:#C9D0D6,color:#0E1C29
```

In this diagram, blue steps move money, light blue steps are validations, and dashed yellow steps are notifications.

**1. The merchant connects their Broco account**

The merchant authorizes your website to receive payments into their Broco account and adds Broco Pay to the payment methods at checkout.

**2. Your server creates the payment**

When the customer selects Broco Pay, your server sends the amount, the currency, the order reference and the merchant connection.

**3. The customer authorizes the payment in Broco**

A Broco page or the Broco app opens. The customer sees the merchant and the amount, signs in if needed, and confirms.

**4. Broco records the payment**

The customer's balance is debited and the merchant's balance is credited, net of any agreed fees.

**5. Your server confirms the result**

Broco sends `payment.succeeded` to your server. Your server marks the order as paid and starts fulfilment.

**6. Both parties see the transaction**

The customer and the merchant find the payment in their Broco history.

> [!WARNING]
>
> A customer returning to your website does not prove that the payment succeeded. Confirm the status on your server before you fulfil the order.

## Accounts and confirmation

| Question | Answer |
| - | - |
| Who needs a Broco account? | The customer, who pays from their balance, and the merchant, who receives the funds. Your platform uses integration credentials. |
| What confirms a payment? | The `succeeded` status. Your server receives it with the `payment.succeeded` event or reads it with `GET /v1/payments/{id}`. |
| Why is the customer's return not enough? | The return is a browser redirect. It can follow a refusal or an expired payment, or not happen at all. Only the status on your server shows that money moved. |
| What do webhooks do? | Broco sends `payment.succeeded` to your webhook endpoint when the payment succeeds. Your server verifies the event before it updates the order. See [Events & webhooks](https://docs.broco.app/developer/events-and-webhooks.md). |

## What you need

| Item | Description |
| - | - |
| Merchant connection | Created once, when the merchant connects their Broco account |
| Integration credentials | Used by your server only |
| Order reference | Your own identifier, such as `ORD-10482` |
| Webhook endpoint | A URL on your server that receives Broco events |

## When a payment does not go through

| Situation | Result | Money moved |
| - | - | - |
| The customer's balance is too low | `declined`, reason `insufficient_balance` | No |
| The customer refuses | `declined`, reason `customer_declined` | No |
| Your platform cancels before authorization | `canceled` | No |
| No authorization before the deadline | `expired` | No |
| The same request is sent twice | The first payment is returned | Once |

## Next steps

> [card] [Quickstart](https://docs.broco.app/broco-pay/quickstart.md)
>
> Integrate a 12 500 DZD order step by step.

> [card] [Payments API](https://docs.broco.app/api-reference/payments.md)
>
> Fields, statuses and examples.


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