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

# Payment Links

> This is used to create shareable payment pages in seconds — no checkout integration required. The links can be to your customers to collect payments instantly.

## Overview

A **Payment Link** is a hosted payment page that Payaza generates for you. Instead of building a checkout flow from scratch, you create a link via the API, share it with your customer, and they pay on a Payaza-hosted page — no frontend work needed on your end.

Payment links are ideal for:

* **Invoices** — send a payment link in an email instead of a bank account number
* **Event tickets** — one link handles unlimited attendee payments
* **Donations** — open-amount links let customers pay whatever they want
* **One-time products** — single-use links that expire after one payment
* **Social selling** — share on WhatsApp, Instagram bio, or anywhere a URL works

**How it works in three steps:**

1. Call **Create Payment Link** → get back a `link` URL (e.g. `https://business.payaza.africa/pay/techmeetup2027`)
2. Share that URL with your customers — by email, WhatsApp, SMS, or embed it as a button on your site
3. Customers open the link, fill in their details, and pay — you get notified via your configured webhook

***

## Key Requirements

<Info>
  Retrieve your API keys from your dashboard by following the steps on our
  [Authentication](/guides/authentication) page. Use your **public API key** for
  all payment link requests.
</Info>

Set the following headers on every request:

```json theme={null}
{
  "Authorization": "Payaza <Public API Key encoded in Base 64>"
}
```

***

## Fixed amount vs open amount

When creating a payment link, you choose whether it charges a set amount or lets the customer decide.

|                        | Fixed amount                          | Open amount                             |
| ---------------------- | ------------------------------------- | --------------------------------------- |
| **`has_fixed_amount`** | `true`                                | `false`                                 |
| **`payment_amount`**   | Required — the exact amount to charge | Omit — customer enters their own amount |
| **Best for**           | Event tickets, invoices, products     | Donations, tips, flexible payments      |

***

## Who pays the fee?

Transaction processing fees can be absorbed by you or passed to the customer. Set this with `fee_bearer_type`:

| `fee_bearer_type` | What happens                                                                          |
| ----------------- | ------------------------------------------------------------------------------------- |
| `Business`        | You absorb the fee — the customer pays exactly the stated amount                      |
| `Customer`        | The fee is added on top — the customer pays the stated amount plus the processing fee |

***

## Step 1 — Create a Payment Link

Creates a new payment link. The `link` in the response is the URL you share with customers.

<CodeGroup>
  ```bash cURL — Fixed amount theme={null}
  curl --request POST \
    --url https://api.payaza.africa/live/payment-link/merchant/create-payment-link \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
    --header 'Content-Type: application/json' \
    --data '{
      "payment_link_name": "TechMeetup2027",
      "payment_description": "Ticket for the Annual Tech Innovators Meetup",
      "has_fixed_amount": true,
      "payment_amount": 1500,
      "country_code": "NGA",
      "currency_code": "NGN",
      "collect_customer_first_and_last_name": true,
      "collect_customer_email": true,
      "collect_customer_phone_number": true,
      "redirect_url": "https://example.com/success",
      "fee_bearer_type": "Business",
      "payment_link_image": "https://example.com/images/banner.png"
    }'
  ```

  ```bash cURL — theme={null}
  curl --request POST \
    --url https://api.payaza.africa/live/payment-link/merchant/create-payment-link \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
    --header 'Content-Type: application/json' \
    --data '{
      "payment_link_name": "GiveFund2027",
      "payment_description": "Support our annual charity drive — give whatever you can",
      "has_fixed_amount": false,
      "country_code": "NGA",
      "currency_code": "NGN",
      "collect_customer_first_and_last_name": true,
      "collect_customer_email": true,
      "collect_customer_phone_number": false,
      "fee_bearer_type": "Customer"
    }'
  ```
</CodeGroup>

**Request body parameters**

| Parameter                              | Type         | Required                    | Description                                                                                      |
| -------------------------------------- | ------------ | --------------------------- | ------------------------------------------------------------------------------------------------ |
| `payment_link_name`                    | String       | ✓                           | The name of the link — also becomes the URL slug (e.g. `TechMeetup2027` → `/pay/techmeetup2027`) |
| `payment_description`                  | String       | No                          | A short description shown on the payment page                                                    |
| `has_fixed_amount`                     | Boolean      | ✓                           | `true` for a fixed charge; `false` to let the customer enter any amount                          |
| `payment_amount`                       | Number       | If `has_fixed_amount: true` | The exact amount to charge                                                                       |
| `country_code`                         | String       | ✓                           | ISO 3166-1 Alpha-3 country code (e.g. `NGA`)                                                     |
| `currency_code`                        | String       | ✓                           | ISO 4217 currency code (e.g. `NGN`, `USD`)                                                       |
| `collect_customer_first_and_last_name` | Boolean      | No                          | Whether to show a name field on the payment page                                                 |
| `collect_customer_email`               | Boolean      | No                          | Whether to show an email field on the payment page                                               |
| `collect_customer_phone_number`        | Boolean      | No                          | Whether to show a phone number field on the payment page                                         |
| `redirect_url`                         | String       | No                          | Where to send the customer after a successful payment                                            |
| `custom_url`                           | String       | No                          | A custom slug for the payment link (e.g. `"techmeetup2027"` → `/pay/techmeetup2027`)             |
| `fee_bearer_type`                      | String       | ✓                           | `Business` (you absorb the fee) or `Customer` (fee added on top)                                 |
| `payment_link_image`                   | String (URL) | No                          | Logo or banner image displayed on the payment page                                               |

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment Link created successfully",
  "data": {
    "id": 84021,
    "link": "https://business.payaza.africa/pay/techmeetup2027",
    "has_fixed_amount": true,
    "created_date": "2026-09-25T14:15:00.000000000",
    "start_date": "2026-09-25T14:15:00.500000000",
    "business_name": "Acme Innovations",
    "payment_description": "Ticket for the Annual Tech Innovators Meetup",
    "payment_link_name": "TechMeetup2027",
    "custom_url": "techmeetup2027"
    "image_url": "https://example.com/images/banner.png",
    "fee_bearer": "Pay by Business",
    "total_collected_amount": 0,
    "number_of_usage": 0,
    "is_single_use": false
  }
}
```

<Warning>
  Save `data.id` immediately — it is the `link_id` used in every other endpoint
  (update, activate, deactivate, and fetch transactions). The `link` URL is
  permanent and can be shared right away.
</Warning>

**API reference:** [Create Payment Link](/api-reference/payment-links/create-payment-link)

***

## Step 2 — Share the link

Once you have `data.link`, you can share it anywhere:

* **Email** — paste it directly as a button or hyperlink
* **WhatsApp / SMS** — send it as a message
* **Website** — embed it as a button: `<a href="{{link}}">Pay Now</a>`
* **Invoice** — include it alongside the invoice total

The customer opens the link, fills in the fields you configured (name, email, phone), and completes payment on Payaza's hosted page. You don't need to build anything on the frontend.

***

## Step 3 — Update a Payment Link

This is used to update the details of an existing payment link using its `link_id`. All body fields are optional — include only the fields you want to change. The link URL itself (`data.link`) does not change when you update other fields.

<Note>
  `payment_link_name` cannot be updated after creation — the URL slug is fixed
  at the time the link is created. To change the name, create a new payment
  link.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://api.payaza.africa/live/payment-link/merchant/update-payment-link?link_id=84021' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
    --header 'Content-Type: application/json' \
    --data '{
      "payment_description": "Updated: Ticket for the Annual Tech Innovators Meetup 2027",
      "payment_amount": 2000,
      "fee_bearer_type": "Customer",
      "success_message": "Thanks for registering! See you at the event.",
      "failure_message": "Payment failed. Please try again or contact support.",
      "redirect_url": "https://example.com/confirmation",
      "custom_url": "tech-meetup-2027"
    }'
  ```
</CodeGroup>

**Query parameter**

| Parameter | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| `link_id` | Integer | The `id` from the Create Payment Link response |

**Updatable body parameters** *(all optional)*

| Parameter                              | Type         | Description                                                                          |
| -------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
| `payment_description`                  | String       | Updated description shown on the payment page                                        |
| `has_fixed_amount`                     | Boolean      | Switch between fixed and open amount                                                 |
| `payment_amount`                       | Number       | Updated charge amount (when `has_fixed_amount: true`)                                |
| `country_code`                         | String       | Updated country code                                                                 |
| `currency_code`                        | String       | Updated currency code                                                                |
| `collect_customer_first_and_last_name` | Boolean      | Toggle name field on the payment page                                                |
| `collect_customer_email`               | Boolean      | Toggle email field on the payment page                                               |
| `collect_customer_phone_number`        | Boolean      | Toggle phone number field on the payment page                                        |
| `success_message`                      | String       | Custom message shown to the customer after a successful payment                      |
| `failure_message`                      | String       | Custom message shown if the payment fails                                            |
| `redirect_url`                         | String       | Updated redirect URL after successful payment                                        |
| `custom_url`                           | String       | A custom slug for the payment link (e.g. `"techmeetup2027"` → `/pay/techmeetup2027`) |
| `additional_info`                      | String       | Any additional instructions displayed on the payment page                            |
| `fee_bearer_type`                      | String       | `Business` or `Customer`                                                             |
| `payment_link_image`                   | String (URL) | Updated image URL for the payment page                                               |

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment Link updated successfully",
  "data": {
    "id": 84021,
    "link": "https://business.payaza.africa/pay/techmeetup2027",
    "has_fixed_amount": true,
    "payment_description": "Updated: Ticket for the Annual Tech Innovators Meetup 2027",
    "payment_link_name": "TechMeetup2027",
    "fee_bearer": "Pay by Customer",
    "redirect_url": "https://example.com/confirmation",
    "total_collected_amount": 0,
    "number_of_usage": 0,
    "is_single_use": false
  }
}
```

**API reference:** [Update Payment Link](/api-reference/payment-links/update-payment-link)

***

## Step 4 — Deactivate a Payment Link

Temporarily disables a payment link. Customers who visit a deactivated link will not be able to complete a payment. The link is not deleted — you can reactivate it at any time.

**When to use it:** Close registrations for an event once tickets sell out, pause a donation campaign, or temporarily suspend a link without losing its transaction history.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://api.payaza.africa/live/payment-link/merchant/deactivate-payment-link?link_id=84021' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \

  ```
</CodeGroup>

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment link de-activated successfully"
}
```

**API reference:** [Deactivate Payment Link](/api-reference/payment-links/deactivate-payment-link)

***

## Step 5 — Activate a Payment Link *(optional)*

Re-enables a previously deactivated payment link. Customers can immediately start making payments again once activated. No request body is needed — just the `link_id` in the query string.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://api.payaza.africa/live/payment-link/merchant/activate-payment-link?link_id=84021' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
  ```
</CodeGroup>

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment link activated successfully"
}
```

**API reference:** [Activate Payment Link](/api-reference/payment-links/activate-payment-link)

***

## Step 6 — Fetch all Payment Links

Retrieve a paginated list of all payment links on your account. Use the optional `search` parameter to filter by name. Each result includes `total_collected_amount` and `number_of_usage` so you can track performance at a glance.

<CodeGroup>
  ```bash cURL — All links theme={null}
  curl --request GET \
    --url 'https://api.payaza.africa/live/payment-link/merchant/fetch-payment-links?page=1&size=10' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
  ```

  ```bash cURL — Search by name theme={null}
  curl --request GET \
    --url 'https://api.payaza.africa/live/payment-link/merchant/fetch-payment-links?search=TechMeetup&page=1&size=10' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
  ```
</CodeGroup>

**Query parameters**

| Parameter | Required | Description                          |
| --------- | -------- | ------------------------------------ |
| `page`    | ✓        | Page number — starts at `1`          |
| `size`    | ✓        | Number of records per page           |
| `search`  | No       | Filter links by name (partial match) |

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment Links fetched successfully",
  "data": {
    "items": [
      {
        "id": 10011,
        "link": "https://business.payaza.africa/pay/devconference",
        "has_fixed_amount": true,
        "payment_amount": 5000,
        "payment_link_name": "DevConference",
        "fee_bearer": "Pay by Customer",
        "total_collected_amount": 15000,
        "number_of_usage": 3,
        "collect_customer_email": true,
        "is_single_use": false,
        "created_date": "2026-01-10T08:30:00.000000",
        "requested_information": [
          {
            "id": 991,
            "attribute_name": "CUSTOMER_EMAIL",
            "reference_type": "Email Address"
          }
        ]
      },
      {
        "id": 10012,
        "link": "https://business.payaza.africa/pay/charityfund",
        "has_fixed_amount": false,
        "payment_link_name": "CharityFund",
        "fee_bearer": "Pay by Business",
        "total_collected_amount": 8500.5,
        "number_of_usage": 12,
        "is_single_use": false,
        "created_date": "2026-02-15T14:22:10.123456"
      }
    ],
    "pagination": {
      "total": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
```

**Key fields explained**

| Field                    | What it tells you                                                      |
| ------------------------ | ---------------------------------------------------------------------- |
| `total_collected_amount` | Total amount received through this link so far                         |
| `number_of_usage`        | Total number of successful payments made on this link                  |
| `is_single_use`          | Whether the link expires after one payment                             |
| `requested_information`  | Which customer fields (name, email, phone) are configured on this link |

**API reference:** [Fetch Payment Links](/api-reference/payment-links/fetch-payment-links)

***

## Step 7 — Fetch Payment Link Transactions

Retrieve a paginated list of all transactions made through a specific payment link. Use this for reconciliation, customer lookups, or building a payments dashboard.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.payaza.africa/live/payment-link/merchant/fetch-payment-link-transactions?link_id=84021&page=1' \
    --header 'Authorization: Payaza <Public API Key encoded in Base 64>' \
  ```
</CodeGroup>

**Query parameters**

| Parameter | Required | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `link_id` | ✓        | The `id` of the payment link to fetch transactions for |
| `page`    | ✓        | Page number — starts at `1`                            |

**Sample response**

```json theme={null}
{
  "status": true,
  "message": "Payment Link Transactions fetched successfully",
  "data": {
    "items": [
      {
        "transaction_id": 90123451,
        "transaction_payable_amount": 15000,
        "transaction_amount": 15000,
        "transaction_fee_amount": 250,
        "transaction_start_date": "2026-09-25T10:15:30.123456",
        "transaction_status": "Completed",
        "currency_name": "Naira",
        "transaction_reference": "P-C-20260925-ABCDEF123",
        "transaction_channel": "Checkout",
        "transaction_mode": "Card",
        "customer_pay_fee": false,
        "customer_response": {
          "email_address": "customer1@example.com"
        }
      },
      {
        "transaction_id": 90123452,
        "transaction_payable_amount": 5500,
        "transaction_amount": 5500,
        "transaction_fee_amount": 100,
        "transaction_start_date": "2026-09-24T14:45:12.654321",
        "transaction_status": "Failed",
        "currency_name": "Naira",
        "transaction_reference": "P-C-20260924-XYZ987UIO",
        "transaction_channel": "Checkout",
        "transaction_mode": "VirtualAccount",
        "customer_pay_fee": false,
        "customer_response": {
          "email_address": "johndoe@example.com"
        }
      }
    ],
    "pagination": {
      "total": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
```

**Transaction status values**

| `transaction_status` | What it means                                         |
| -------------------- | ----------------------------------------------------- |
| `Completed`          | Payment was successful — funds received               |
| `Failed`             | Payment attempt was made but declined or failed       |
| `Initialized`        | Customer opened the payment page but has not yet paid |

**Key fields explained**

| Field                             | What it tells you                                                 |
| --------------------------------- | ----------------------------------------------------------------- |
| `transaction_amount`              | The base payment amount                                           |
| `transaction_fee_amount`          | The processing fee charged                                        |
| `transaction_payable_amount`      | What the customer actually paid (base + fee if customer bears it) |
| `transaction_mode`                | How the customer paid — `Card`, `VirtualAccount`                  |
| `customer_response.email_address` | The email the customer entered on the payment page                |
| `transaction_reference`           | Unique reference — use this for reconciliation or support queries |

**API reference:** [Fetch Payment Link Transactions](/api-reference/payment-links/fetch-payment-link-transactions)

***

## Error handling

| Scenario                              | What to check                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `payment_amount` ignored              | Ensure `has_fixed_amount: true` is set — amount is only applied when this is `true`     |
| Link not accessible to customers      | Check if the link was deactivated. Use Activate Payment Link to re-enable it            |
| Customers reaching a deactivated link | The page will not load for payment. Always reactivate before sharing with new customers |
| `payment_link_name` already taken     | Payment link names must be unique per account. Use a different name for each request    |

***

## Developer notes

* Always save `data.id` (`link_id`) from the Create Payment Link response — every other endpoint in this guide uses it.
* `data.link` is the shareable URL. It is permanent and does not change even after you update the link's other details.
* Payment link names become URL slugs — keep them short, descriptive, and without spaces (use camelCase or hyphens). `TechMeetup2027` becomes `/pay/techmeetup2027`.
* You can set a custom slug after creation using the `custom_url` field in the Update endpoint — useful if you want a cleaner URL like `/pay/tech-meetup-2027`.
* Payment links support multiple payment methods on the hosted page (card, virtual account, etc.) — the `transaction_mode` field in the transactions response tells you which method each customer used.