Sign in

v31

latestOpenAPI 3.0.1MITraw.githubusercontent.com2026-07-082421122.2 KB
Payment Link

Create a payment link

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.

post/paymentlink

Request body

namestring required

Name or title for the payment link

descriptionstring

Description of the payment

type'One_Time'

Type of payment link

addFeeToTotalCostboolean

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

paymentMethodsstring[] 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]

amountnumber required

Amount in the lowest denomination of the payment currency (e.g., kobo for NGN)

callbackUrlstring uri

Redirect URL where users are sent after payment completion

Example request

{
  "name": "Bitcoin Purchase",
  "description": "On-chain Bitcoin payment",
  "type": "One_Time",
  "settlementCurrency": "NGN, ZAR, BTC",
  "settlementMethod": "ONCHAIN",
  "speed": "medium",
  "paymentCurrency": "NGN, ZAR, BTC",
  "paymentMethods": [
    "BANKTRANSFER, LIGHTNING"
  ],
  "beneficiary": {
    "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5",
    "lnAddress": "user@getalby.com",
    "lnInvoice": "lnbc..."
  },
  "amount": 800000,
  "callbackUrl": "https://your-app.com/payment-success"
}

Response

Payment link created successfully

statusstring
messagestring

Example response

{
  "status": "ok",
  "message": "payment link created successfully",
  "data": {
    "paymentLink": "https://checkout.staging.mavapay.co/9d1c20db-c46b-4a15-8233-1bb999e38195",
    "paymentRef": "9d1c20db-c46b-4a15-8233-1bb999e38195"
  }
}