Payment Links API

Create and manage shareable payment links.

Payment links are standalone URLs that customers can use to make payments without an invoice or order. Use them for donations, deposits, flexible billing, or any scenario where you need a quick payment page.

Use Cases

• Deposits: Collect upfront deposits before starting work
• Event Tickets: Sell tickets with a simple shareable link
• Donations: Accept contributions with no invoice required
• Quick Billing: Send a payment link via SMS or email in seconds

Endpoints

Method	Endpoint	Description
POST	/business/payment-link/create	Create a new payment link
GET	/business/payment-link/list	List all payment links
GET	/business/payment-link/details/:id	Get payment link details

---

Create Payment Link

Generate a new standalone payment link.

POST /business/payment-link/create

Request Body

Field	Type	Required	Description
title	string	Yes	Payment link title (shown on the payment page)
amount	number	Yes	Payment amount
type	string	No	Link type (default: general)

Example Request

cURL

curl -X POST "https://api.cashfin.africa/business/payment-link/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Deposit - Acme Corp",
    "amount": 25000.00,
    "type": "deposit"
  }'

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/payment-link/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Website Deposit - Acme Corp",
      amount: 25000.0,
      type: "deposit",
    }),
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/payment-link/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'title'  => 'Website Deposit - Acme Corp',
    'amount' => 25000.00,
    'type'   => 'deposit',
  ]),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$result = json_decode(curl_exec($curl), true);

Python

import requests

response = requests.post(
    'https://api.cashfin.africa/business/payment-link/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Website Deposit - Acme Corp',
        'amount': 25000.00,
        'type': 'deposit',
    }
)

Success Response

{
  "success": true,
  "message": "Payment link created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "title": "Website Deposit - Acme Corp",
    "amount": 25000.0,
    "type": "deposit",
    "status": "unpaid",
    "shorturl": "https://pay.cashfin.africa/a1b2c3d4e5f6g7h8",
    "rawurl": "https://acmecorp.cashfin.africa/pay/a1b2c3d4e5f6g7h8",
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

---

List Payment Links

Retrieve a paginated list of payment links.

GET /business/payment-link/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by title or short URL
status	string	-	Filter by status: unpaid, paid, expired
type	string	-	Filter by type: general, deposit, invoice, etc.

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/payment-link/list?page=1&limit=10&status=unpaid" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/payment-link/list?page=1&limit=10",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/payment-link/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10, 'status': 'unpaid'}
)

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439060",
      "title": "Website Deposit - Acme Corp",
      "type": "deposit",
      "status": "unpaid",
      "balance": 25000.0,
      "shorturl": "https://pay.cashfin.africa/a1b2c3d4e5f6g7h8",
      "rawurl": "https://acmecorp.cashfin.africa/pay/a1b2c3d4e5f6g7h8",
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 18,
    "page": 1,
    "limit": 10,
    "pages": 2
  }
}

---

Get Payment Link Details

Retrieve full details of a specific payment link.

GET /business/payment-link/details/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Link ID (MongoDB ObjectID)

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/payment-link/details/507f1f77bcf86cd799439060" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const linkId = "507f1f77bcf86cd799439060";

const response = await fetch(
  `https://api.cashfin.africa/business/payment-link/details/${linkId}`,
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

link_id = '507f1f77bcf86cd799439060'

response = requests.get(
    f'https://api.cashfin.africa/business/payment-link/details/{link_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "title": "Website Deposit - Acme Corp",
    "type": "deposit",
    "status": "unpaid",
    "balance": 25000.0,
    "shorturl": "https://pay.cashfin.africa/a1b2c3d4e5f6g7h8",
    "rawurl": "https://acmecorp.cashfin.africa/pay/a1b2c3d4e5f6g7h8",
    "sourceorigin": "api",
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

---

Payment Link Statuses

Status	Description
unpaid	Link is active, awaiting payment
paid	Payment received in full
expired	Link has expired

---

Error Responses

Validation Error

{
  "success": false,
  "error": "amount must be greater than zero"
}

Payment Link Not Found

{
  "success": false,
  "error": "Payment link not found"
}