---
title: "Create a payment link"
method: POST
path: "/paymentlink"
tags: ["Payment Link"]
---

# Create a payment link

`POST /paymentlink`

Create a hosted payment link for collecting payments. Payment links simplify the checkout process by creating a hosted payment page where users can complete payments.

## Request body

- CreatePaymentLink
  - `name` string, required — Name or title for the payment link
  - `description` string — Description of the payment
  - `type` 'One_Time' — Type of payment link
  - `addFeeToTotalCost` boolean — Whether to add transaction fees to the total cost
  - `settlementCurrency` 'NGN, ZAR, BTC', required — The currency to settle in
  - `settlementMethod` 'ONCHAIN' | 'LIGHTNING', required — Settlement method for Bitcoin. ONCHAIN for on-chain transactions, LIGHTNING for Lightning Network
  - `speed` 'slow' | 'medium' | 'fast' — Network fee priority for on-chain transactions. Required when settlementMethod is ONCHAIN
  - `paymentCurrency` 'NGN, ZAR, BTC', required — The currency the user pays in
  - `paymentMethods` string[], required — Accepted payment methods. Currently only BANKTRANSFER and LIGHTNING are supported e.g for ZAR payment link, you can specify two payment methods [BANKTRANSFER, LIGHTNING]
  - `beneficiary` union, required — Beneficiary details for settlement. Structure depends on settlement type: Bitcoin (on-chain or Lightning), NGN bank account, or ZAR bank account.
    - object — For BTC settlement via on-chain or Lightning
      - `onChainAddress` string — Bitcoin on-chain address for settlement (required for ONCHAIN settlementMethod)
      - `lnAddress` string — Lightning address for settlement (for LIGHTNING settlementMethod)
      - `lnInvoice` string — Lightning invoice for settlement (for LIGHTNING settlementMethod)
    - object — For NGN settlement to a Nigerian bank account
      - `bankAccountNumber` string, required — Nigerian bank account number
      - `bankAccountName` string, required — Account holder name
      - `bankCode` string, required — Nigerian bank code (NIP code)
      - `bankName` string, required — Name of the bank
    - object — For ZAR settlement to a South African bank account
      - `bankAccountNumber` string, required — South African bank account number
      - `bankName` string, required — Name of the bank
      - `name` string, required — Account holder name
  - `amount` number, required — Amount in the lowest denomination of the payment currency (e.g., kobo for NGN)
  - `callbackUrl` string, uri — Redirect URL where users are sent after payment completion

## Response `200`

Payment link created successfully

- object
  - `status` string
  - `message` string
  - `data` PaymentLinkResponse
    - `paymentLink` string, uri — The hosted payment page URL
    - `paymentRef` string, uuid — Unique reference for the payment link

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/stealthmoney/apis/mavapay-api.md) · [All operations](https://skmtc.net/stealthmoney/apis/mavapay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stealthmoney/mavapay-api/revisions/842376cab855/schema)