Payment lifecycle

A payment starts as pending and ends in exactly one final status. Only succeeded means money moved.

Statuses

Status	Meaning	What your platform does
`pending`	Waiting for the customer to authorize	Do not mark the order as paid
`succeeded`	Customer debited, merchant credited	Mark the order as paid and fulfil it
`declined`	The payment was refused	Offer another payment method
`canceled`	Canceled before authorization	Do not mark the order as paid
`expired`	No authorization before `expires_at`	Create a new payment if the customer tries again

succeeded, declined, canceled and expired are final. A final payment never changes status.

Declined payments

A declined payment includes a decline_reason.

`decline_reason`	Meaning
`insufficient_balance`	The customer’s balance does not cover the amount
`customer_declined`	The customer refused the payment in Broco

Response

{
  "id": "pay_9Xc2LmQ7",
  "object": "payment",
  "status": "declined",
  "decline_reason": "insufficient_balance",
  "amount": 1250000,
  "currency": "DZD",
  "order_reference": "ORD-10482"
}

Canceling a payment

While a payment is pending, your server can cancel it with POST /v1/payments/{id}/cancel, for example when the customer changes the payment method. A payment that already reached a final status cannot be canceled.

Repeated requests

If your server sends the same creation request twice with the same Idempotency-Key, Broco returns the original payment. The customer is debited at most once for one key. After a payment expired or was declined, a new attempt uses a new key, such as ORD-10482-attempt-2.

Next steps

Payments API

The payment object and its operations.

Events & webhooks

Receive payment.succeeded on your server.

Get started

Product

Developer

API Reference

Statuses

Declined payments

Canceling a payment

Repeated requests

Next steps

Payments API

Events & webhooks

​Statuses

​Declined payments

​Canceling a payment

​Repeated requests

​Next steps

Payments API

Events & webhooks

Statuses

Declined payments

Canceling a payment

Repeated requests

Next steps