Skip to main content
POST
/
api
/
canary
/
payment-links
Create Payment Link
curl --request POST \
  --url https://api.cashful.africa/api/canary/payment-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "totalAmount": 123,
  "currency": "<string>",
  "mode": "payment",
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "metadata": {
    "orderId": "12345",
    "customField": "value"
  }
}
'
{
  "id": "plink_001",
  "name": "Summer Sale Link",
  "description": "Payment link for the summer sale campaign",
  "merchantId": "merchant_456",
  "url": "https://checkout.cashful.africa/plink_001",
  "totalAmount": 15000,
  "currency": "ZAR",
  "mode": "payment",
  "active": true,
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "lineItems": [
    {
      "name": "Product A",
      "amount": 15000,
      "quantity": 1,
      "currency": "ZAR"
    }
  ],
  "metadata": {
    "campaign": "summer_sale"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "deletedAt": null
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Payment link details

totalAmount
number
required

The total amount in the smallest currency unit

currency
string
required

The three-letter ISO 4217 currency code

mode
enum<string>
required

The payment mode (e.g., 'payment' or 'subscription')

Available options:
payment,
setup,
subscription
successUrl
string
required

The URL to redirect to on successful payment

cancelUrl
string
required

The URL to redirect to if customer cancels

metadata
object
required

Optional custom metadata

Example:
{
"orderId": "12345",
"customField": "value"
}
name
string

The name of the payment link

description
string

A description of the payment link

merchantId
string

The ID of the merchant whose balance is being requested. If omitted, defaults to the authenticated merchant.

lineItems
object[]

Array of line items for the checkout

customerId
string

The unique identifier of the customer

hostedCheckoutConfig
object

Configuration for the hosted checkout page

Response

Payment link created successfully

id
string
required
merchantId
string
required
url
string
required
totalAmount
number
required
currency
string
required
mode
enum<string>
required
Available options:
payment,
setup,
subscription
active
boolean
required
successUrl
string
required
cancelUrl
string
required
metadata
object
required
Example:
{ "customField": "value" }
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
name
string
description
string
lineItems
object[]
customerId
string
hostedCheckoutConfig
object

Configuration for the hosted checkout page

deletedAt
string<date-time>