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

> Take a 12 500 DZD order from checkout to confirmed payment.

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

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

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

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

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

  <Step title="Show the confirmation">
    When the customer returns to `return_url`, display the status your server confirmed.
  </Step>
</Steps>

## Next step

<Card title="Payment lifecycle" href="/broco-pay/payment-lifecycle" horizontal>
  Handle pending, declined, canceled and expired payments.
</Card>


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