> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puplar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Collect a one-time payment with a hosted checkout link

Create a payment, share `payment_link`, then look it up by your `reference`.

## Create a payment

`POST /payments` returns a hosted checkout URL. Amounts are **minor units**. `reference` must be unique — reusing one returns `409`.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payments \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_98234",
    "amount": 7500,
    "currency": "ngn",
    "title": "Invoice #98234",
    "customer": {
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Obi"
    },
    "callback_url": "https://yourapp.com/orders/98234/complete"
  }'
```

Share `payment_link` with the customer. Do not fulfill from `callback_url` alone — retrieve the payment first.

For a reusable link, use [Collections](/guides/collections). To bill from a catalog, use [Invoices](/guides/invoices). Test cards: [Test vs Live](/guides/test-vs-live#card-payments-in-test-mode).

## Retrieve

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl "https://api.puplar.com/payments/order_98234" \
  -H "Authorization: Bearer sk_live_your_key"
```

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl "https://api.puplar.com/payments?status=completed&currency=ngn" \
  -H "Authorization: Bearer sk_live_your_key"
```

## Cancel

Cancel by payment **id**, not `reference`. Only `pending` or `processing`.

```bash theme={"theme":{"light":"min-light","dark":"poimandres"}}
curl -X POST https://api.puplar.com/payments/64f1a2b3c4d5e6f7a8b9c0d1/cancel \
  -H "Authorization: Bearer sk_live_your_key"
```

Listen for `payment.completed`, `payment.failed`, `payment.expired`, and `payment.canceled`. See [Webhooks](/guides/webhooks). Refund a completed payment with [Refunds](/guides/refunds).

```json theme={"theme":{"light":"min-light","dark":"poimandres"}}
{
  "id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "type": "payment.completed",
  "timestamp": "2026-07-26T12:00:00.000Z",
  "payload": {
    "id": "64f9b3c4d5e6f7a8b9c0d1e2",
    "status": "completed",
    "livemode": true,
    "customer_id": "64aa11b2c3d4e5f6a7b8c9d0",
    "reference": "order_98234",
    "amount": 7500,
    "currency": "ngn",
    "metadata": {},
    "completed_at": "2026-07-26T12:00:00.000Z",
    "transaction_id": "64bb22c3d4e5f6a7b8c9d0e1"
  }
}
```