Payments

A payment debits a customer’s Broco balance and credits a merchant after the customer authorizes it in Broco. Guide: Broco Pay.

Operation	Method and path
Create a payment	`POST /v1/payments`
Retrieve a payment	`GET /v1/payments/{id}`
Cancel a payment	`POST /v1/payments/{id}/cancel`

The payment object

Field	Type	Description
`id`	string	Identifier, such as `pay_9Xc2LmQ7`
`object`	string	Always `payment`
`status`	string	`pending`, `succeeded`, `declined`, `canceled` or `expired`
`decline_reason`	string or null	`insufficient_balance` or `customer_declined` when `declined`
`amount`	integer	Amount in minor units of `currency`
`currency`	string	Currency code: `DZD`, `MAD`, `TND` or `XOF`
`order_reference`	string	Your order identifier
`merchant_connection`	string	Connection of the merchant receiving the funds
`authorization_url`	string or null	Broco page where the customer authorizes. `null` once final.
`return_url`	string	Where the customer returns after authorization
`fee_amount`	integer or null	Fees, once `succeeded`
`net_amount`	integer or null	Amount credited to the merchant, once `succeeded`
`expires_at`	string	Deadline for the customer’s authorization
`succeeded_at`	string or null	Time of the debit and credit
`created_at`	string	Creation time

Create a payment

POST /v1/payments

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in minor units. 12 500 DZD is `1250000`.
`currency`	string	Yes	Currency code: `DZD`, `MAD`, `TND` or `XOF`. The balances debited and credited use this currency.
`order_reference`	string	Yes	Your order identifier
`merchant_connection`	string	Yes	Connection of the merchant
`return_url`	string	Yes	HTTPS URL on your website

Header	Required	Description
`Idempotency-Key`	Yes	Same key, same 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",
  "decline_reason": null,
  "amount": 1250000,
  "currency": "DZD",
  "order_reference": "ORD-10482",
  "merchant_connection": "conn_mrc_4f7Kp2",
  "authorization_url": "https://pay.broco.example/authorize/pay_9Xc2LmQ7",
  "return_url": "https://shop.example.com/orders/ORD-10482",
  "fee_amount": null,
  "net_amount": null,
  "expires_at": "2026-10-12T10:15:00Z",
  "succeeded_at": null,
  "created_at": "2026-10-12T10:00:00Z"
}

Retrieve a payment

GET /v1/payments/{id}

Request

curl https://api.broco.example/v1/payments/pay_9Xc2LmQ7 \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"

Response

{
  "id": "pay_9Xc2LmQ7",
  "object": "payment",
  "status": "succeeded",
  "decline_reason": null,
  "amount": 1250000,
  "currency": "DZD",
  "order_reference": "ORD-10482",
  "merchant_connection": "conn_mrc_4f7Kp2",
  "authorization_url": null,
  "return_url": "https://shop.example.com/orders/ORD-10482",
  "fee_amount": 0,
  "net_amount": 1250000,
  "expires_at": "2026-10-12T10:15:00Z",
  "succeeded_at": "2026-10-12T10:02:40Z",
  "created_at": "2026-10-12T10:00:00Z"
}

Fee values are examples.

Cancel a payment

POST /v1/payments/{id}/cancel Cancels a pending payment. Returns the payment with status canceled. Fails with invalid_status if the payment is final.

Request

curl -X POST https://api.broco.example/v1/payments/pay_9Xc2LmQ7/cancel \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"

Events

Event	Sent when
`payment.succeeded`	The customer is debited and the merchant credited

Errors

invalid_request, invalid_amount, unsupported_currency, currency_mismatch, connection_not_authorized, idempotency_key_reused, invalid_status. See Errors & retries.

Get started

Product

Developer

API Reference

The payment object

Create a payment

Retrieve a payment

Cancel a payment

Events

Errors

​The payment object

​Create a payment

​Retrieve a payment

​Cancel a payment

​Events

​Errors

The payment object

Create a payment

Retrieve a payment

Cancel a payment

Events

Errors