Skip to main content
POST
/
paymentlink
curl --request POST \
  --url https://staging.api.mavapay.co/api/v1/paymentlink \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "Bitcoin Purchase",
  "description": "On-chain Bitcoin payment",
  "type": "One_Time",
  "addFeeToTotalCost": false,
  "settlementCurrency": "BTC",
  "settlementMethod": "ONCHAIN",
  "speed": "medium",
  "paymentCurrency": "NGN",
  "paymentMethods": [
    "BANKTRANSFER"
  ],
  "beneficiary": {
    "onChainAddress": "bc1q8yz7u50r4nne2q8wkuc4kyxx0s76fxsjlac5fxd8h7tzkh4rs82qnweuv5"
  },
  "amount": 800000,
  "callbackUrl": "https://your-app.com/callback"
}
'
{
  "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"
  }
}

Authorizations

​
X-API-KEY
string
header
required

Body

application/json
​
name
string
required

Name or title for the payment link

Example:

"Bitcoin Purchase"

​
settlementCurrency
enum<string>
required

The currency to settle in

Available options:
NGN, ZAR, BTC
Example:

"NGN, ZAR, BTC"

​
settlementMethod
enum<string>
required

Settlement method for Bitcoin. ONCHAIN for on-chain transactions, LIGHTNING for Lightning Network

Available options:
ONCHAIN,
LIGHTNING
Example:

"ONCHAIN"

​
paymentCurrency
enum<string>
required

The currency the user pays in

Available options:
NGN, ZAR, BTC
Example:

"NGN, ZAR, BTC"

​
paymentMethods
enum<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]

Available options:
BANKTRANSFER, LIGHTNING
Example:
["BANKTRANSFER, LIGHTNING"]
​
beneficiary
Bitcoin Beneficiary · object
required

For BTC settlement via on-chain or Lightning

​
amount
number
required

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

Example:

800000

​
description
string

Description of the payment

Example:

"On-chain Bitcoin payment"

​
type
enum<string>

Type of payment link

Available options:
One_Time
Example:

"One_Time"

​
addFeeToTotalCost
boolean

Whether to add transaction fees to the total cost

Example:

false

​
speed
enum<string>

Network fee priority for on-chain transactions. Required when settlementMethod is ONCHAIN

Available options:
slow,
medium,
fast
Example:

"medium"

​
callbackUrl
string<uri>

Redirect URL where users are sent after payment completion

Example:

"https://your-app.com/payment-success"

Response

Payment link created successfully

​
status
string
Example:

"ok"

​
message
string
Example:

"payment link created successfully"

​
data
object