Broco Pay quickstart

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.

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`

Create the payment

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

Request

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"
  }'

Response

{
  "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"
}

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.

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.

Event (excerpt)

{
  "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.

Show the confirmation

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

Next step

Payment lifecycle

Handle pending, declined, canceled and expired payments.

Get started

Product

Developer

API Reference

Next step

Payment lifecycle

​Next step

Payment lifecycle

Next step