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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Broco records the payment">
    The customer's balance is debited and the merchant's balance is credited, net of any agreed fees.
  </Step>

  <Step title="Your server confirms the result">
    Broco sends `payment.succeeded` to your server. Your server marks the order as paid and starts fulfilment.
  </Step>

  <Step title="Both parties see the transaction">
    The customer and the merchant find the payment in their Broco history.
  </Step>
</Steps>

<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.
</Warning>

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

<CardGroup cols={2}>
  <Card title="Quickstart" href="/broco-pay/quickstart">
    Integrate a 12 500 DZD order step by step.
  </Card>

  <Card title="Payments API" href="/api-reference/payments">
    Fields, statuses and examples.
  </Card>
</CardGroup>


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