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