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

# Checkout Links API — generate hosted payment URLs

> Create hosted checkout pages that your customers click to pay. Supports one-time amounts, invoice-linked payments, and inline line-item checkout flows.

Checkout links give you a hosted payment page that you can share with customers via email, SMS, or your website. When a customer clicks the link, they see a branded payment page and can complete their payment without you needing to build any frontend. Dubu automatically reconciles the payment against your account and, if the link is tied to an invoice, marks that invoice as paid. All routes require authentication.

## Checkout link object

<ResponseField name="id" type="string">
  Unique checkout link identifier (UUID).
</ResponseField>

<ResponseField name="title" type="string">
  Display title shown on the hosted payment page.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description shown to the customer. `null` if not set.
</ResponseField>

<ResponseField name="url" type="string">
  The hosted checkout URL your customers visit to complete payment. Share this link directly.
</ResponseField>

<ResponseField name="slug" type="string">
  URL-friendly identifier used in the hosted page URL. Lowercase alphanumeric with dashes.
</ResponseField>

<ResponseField name="type" type="string">
  `one_time` for a standalone payment or `invoice` for a link tied to an existing invoice.
</ResponseField>

<ResponseField name="amount" type="number">
  Payment amount for `one_time` links.
</ResponseField>

<ResponseField name="currency" type="string">
  Payment currency: `NGN` or `USD`.
</ResponseField>

<ResponseField name="status" type="string">
  `active` or `inactive`. Inactive links cannot be used for new payments.
</ResponseField>

<ResponseField name="redirect_url" type="string">
  URL customers are redirected to after a successful payment. `null` if not set.
</ResponseField>

<ResponseField name="success_message" type="string">
  Custom message shown to customers after payment. `null` if not set.
</ResponseField>

<ResponseField name="invoice_id" type="string">
  UUID of the linked invoice, if `type` is `invoice`. `null` otherwise.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

***

## Create a checkout link

```
POST /checkout-links
```

You can create three flavors of checkout link:

* **One-time amount** — set `type: "one_time"` and provide `amount` and `currency`.
* **Invoice-linked** — set `type: "invoice"` and provide `invoice_id` to link an existing invoice.
* **Inline invoice** — provide `customer_name`, `customer_email`, and `line_items` to create a new invoice and checkout link in one call.

### Request body

<ParamField body="title" type="string" required>
  Title shown on the checkout page. Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description shown to the customer. Maximum 2,000 characters.
</ParamField>

<ParamField body="type" type="string">
  `one_time` or `invoice`. Defaults to `one_time`.
</ParamField>

<ParamField body="slug" type="string">
  Custom URL slug for the checkout page (e.g. `my-product-payment`). Must be lowercase alphanumeric with dashes, 3–100 characters. Auto-generated if omitted.
</ParamField>

<ParamField body="currency" type="string">
  `NGN` or `USD`. Defaults to your account currency.
</ParamField>

<ParamField body="redirect_url" type="string">
  URL to redirect the customer to after successful payment.
</ParamField>

<ParamField body="success_message" type="string">
  Custom message displayed after payment completes. Maximum 500 characters.
</ParamField>

<ParamField body="amount" type="number">
  Fixed payment amount. Required for `one_time` links without `line_items`.
</ParamField>

<ParamField body="invoice_id" type="string">
  UUID of an existing invoice to link. Use this for `invoice` type links.
</ParamField>

<ParamField body="customer_name" type="string">
  Customer name for inline invoice creation.
</ParamField>

<ParamField body="customer_email" type="string">
  Customer email for inline invoice creation.
</ParamField>

<ParamField body="line_items" type="array">
  Line items for inline invoice creation. Each item requires `description`, `quantity`, and `unit_price`. Optionally include `product_id` to link a catalog product.
</ParamField>

### Example — one-time payment

```bash theme={null}
curl -X POST https://api.dubupay.com/api/v1/checkout-links \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment for Logo Design",
    "amount": 75000,
    "currency": "NGN",
    "redirect_url": "https://yoursite.com/thank-you"
  }'
```

### Example response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Payment for Logo Design",
    "url": "https://pay.dubupay.com/c/xk9p2mq3",
    "slug": "xk9p2mq3",
    "type": "one_time",
    "amount": 75000,
    "currency": "NGN",
    "status": "active",
    "redirect_url": "https://yoursite.com/thank-you",
    "success_message": null,
    "invoice_id": null,
    "created_at": "2024-01-15T10:00:00.000Z"
  }
}
```

***

## List checkout links

```
GET /checkout-links
```

Returns a paginated list of your checkout links.

### Query parameters

<ParamField query="status" type="string">
  Filter by status: `active` or `inactive`.
</ParamField>

<ParamField query="page" type="number">
  Page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number">
  Results per page. Maximum `100`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/checkout-links?status=active" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

***

## Get a checkout link

```
GET /checkout-links/:id
```

Retrieve a single checkout link by its UUID.

<ParamField path="id" type="string" required>
  UUID of the checkout link.
</ParamField>

```bash theme={null}
curl https://api.dubupay.com/api/v1/checkout-links/link_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

***

## Update a checkout link

```
PATCH /checkout-links/:id
```

Update a checkout link's display settings or status. You cannot change the `amount`, `currency`, or linked invoice after creation.

<ParamField path="id" type="string" required>
  UUID of the checkout link to update.
</ParamField>

<ParamField body="title" type="string">
  New title.
</ParamField>

<ParamField body="description" type="string">
  New description. Pass `null` to clear.
</ParamField>

<ParamField body="redirect_url" type="string">
  New redirect URL. Pass `null` to remove.
</ParamField>

<ParamField body="success_message" type="string">
  New success message. Pass `null` to clear.
</ParamField>

<ParamField body="status" type="string">
  Set to `inactive` to disable the link, or `active` to re-enable it.
</ParamField>

### Example

```bash theme={null}
curl -X PATCH https://api.dubupay.com/api/v1/checkout-links/link_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'
```

***

## Delete a checkout link

```
DELETE /checkout-links/:id
```

Permanently deletes a checkout link. The hosted URL immediately stops working. This action cannot be undone.

<ParamField path="id" type="string" required>
  UUID of the checkout link to delete.
</ParamField>

```bash theme={null}
curl -X DELETE https://api.dubupay.com/api/v1/checkout-links/link_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```