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

> Create a Broco Pay payment from your server, let the customer authorize it in Broco and confirm the order from the payment event.

This quickstart follows order `ORD-10482` for **12 500 DZD**, paid by a customer from their Broco balance to a merchant connected as `conn_mrc_4f7Kp2`.

**1. Prepare the order**

When the customer selects **Broco Pay** at checkout, your server gathers the payment details.

| Field | Value |
| - | - |
| `amount` | `1250000` (12 500 DZD) |
| `currency` | `DZD` |
| `order_reference` | `ORD-10482` |
| `merchant_connection` | `conn_mrc_4f7Kp2` |

**2. Create the payment**

Use a key tied to the order attempt, so a retry never creates a second payment.

```bash Request theme={null}
curl -X POST https://api.broco.example/v1/payments \
  -H "Authorization: Bearer $BROCO_SECRET_KEY" \
  -H "Idempotency-Key: ORD-10482-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1250000,
    "currency": "DZD",
    "order_reference": "ORD-10482",
    "merchant_connection": "conn_mrc_4f7Kp2",
    "return_url": "https://shop.example.com/orders/ORD-10482"
  }'
```

```json Response theme={null}
{
  "id": "pay_9Xc2LmQ7",
  "object": "payment",
  "status": "pending",
  "amount": 1250000,
  "currency": "DZD",
  "order_reference": "ORD-10482",
  "merchant_connection": "conn_mrc_4f7Kp2",
  "authorization_url": "https://pay.broco.example/authorize/pay_9Xc2LmQ7",
  "expires_at": "2026-10-12T10:15:00Z",
  "created_at": "2026-10-12T10:00:00Z"
}
```

**3. Send the customer to Broco**

Redirect the customer to `authorization_url`. The customer sees the merchant and the amount, signs in if needed, and confirms. On a phone, the Broco app can open instead.

**4. Receive the result on your server**

Broco sends `payment.succeeded` to your webhook endpoint. Check that `data.id` is the payment you created, then check `data.merchant_connection`, `data.order_reference`, `data.amount` and `data.currency` against the order. Then mark it as paid.

```json Event (excerpt) theme={null}
{
  "id": "evt_P3n8Tq1v",
  "type": "payment.succeeded",
  "created_at": "2026-10-12T10:02:41Z",
  "data": {
    "id": "pay_9Xc2LmQ7",
    "object": "payment",
    "status": "succeeded",
    "amount": 1250000,
    "currency": "DZD",
    "order_reference": "ORD-10482",
    "merchant_connection": "conn_mrc_4f7Kp2",
    "fee_amount": 0,
    "net_amount": 1250000,
    "succeeded_at": "2026-10-12T10:02:40Z"
  }
}
```

If the customer returns before the event arrives, retrieve the payment with `GET /v1/payments/pay_9Xc2LmQ7`.

**5. Show the confirmation**

When the customer returns to `return_url`, display the status your server confirmed.

## Next step

> [card] [Payment lifecycle](https://docs.broco.app/broco-pay/payment-lifecycle.md)
>
> Handle pending, declined, canceled and expired payments.


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