Payment Links

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:

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

Key Requirements

Retrieve your API keys from your dashboard by following the steps on our Authentication page. Use your public API key for all payment link requests.

Set the following headers on every request:

{
  "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.

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"
  }'

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"
  }'

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

{
  "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
  }
}

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.

API reference: Create Payment 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.

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.

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"
  }'

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

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

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.

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

Sample response

{
  "status": true,
  "message": "Payment link de-activated successfully"
}

API reference: 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.

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

Sample response

{
  "status": true,
  "message": "Payment link activated successfully"
}

API reference: 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.

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

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

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

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

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.

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

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

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

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.

Get Started

Developer Tools

Accept Payments

Send Money

Disputes & Refunds

Account Management

Subscriptions

Split Settlements

Payment Links

Overview

Key Requirements

Fixed amount vs open amount

Who pays the fee?

Step 1 — Create a Payment Link

Step 3 — Update a Payment Link

Step 4 — Deactivate a Payment Link

Step 5 — Activate a Payment Link (optional)

Step 6 — Fetch all Payment Links

Step 7 — Fetch Payment Link Transactions

Error handling

Developer notes

​Overview

​Key Requirements

​Fixed amount vs open amount

​Who pays the fee?

​Step 1 — Create a Payment Link

​Step 2 — Share the link

​Step 3 — Update a Payment Link

​Step 4 — Deactivate a Payment Link

​Step 5 — Activate a Payment Link (optional)

​Step 6 — Fetch all Payment Links

​Step 7 — Fetch Payment Link Transactions

​Error handling

​Developer notes

Overview

Key Requirements

Fixed amount vs open amount

Who pays the fee?

Step 1 — Create a Payment Link

Step 2 — Share the link

Step 3 — Update a Payment Link

Step 4 — Deactivate a Payment Link

Step 5 — Activate a Payment Link (optional)

Step 6 — Fetch all Payment Links

Step 7 — Fetch Payment Link Transactions

Error handling

Developer notes