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

# Payments

> Create, retrieve and cancel Broco Pay payments.

A payment debits a customer's Broco balance and credits a merchant after the customer authorizes it in Broco. Guide: [Broco Pay](/broco-pay/overview).

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

```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",
  "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}`

```bash Request theme={null}
curl https://api.broco.example/v1/payments/pay_9Xc2LmQ7 \
  -H "Authorization: Bearer $BROCO_SECRET_KEY"
```

```json Response theme={null}
{
  "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.

```bash Request theme={null}
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](/developer/errors-and-retries).


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