Orders API

Create order checkouts through the API and process customer purchases.

The Orders API enables you to create checkout sessions with automatic payment link generation. Orders can include multiple items, shipping addresses, and customer assignment. Each order generates a unique payment link that customers can use to complete their purchase.

Use Cases

E-commerce Checkout: Process online store purchases
Headless Commerce: Build custom checkout experiences with your own frontend
Order Management: Create orders from external systems or POS
Invoicing: Generate orders for manual payment processing

Endpoints

Method	Endpoint	Description
`POST`	`/business/order/checkout`	Create an order checkout
`GET`	`/business/order/list`	List all orders
`GET`	`/business/order/details/:id`	Get order details

Create Order Checkout

Create a new order with items and customer information.

http

POST /business/order/checkout

Request Body

Field	Type	Required	Description
`customeremail`	string	No	Customer's email address
`items`	array	Yes	Order items (see below)
`shippingaddress`	object	No	Shipping address details
`billingaddress`	object	No	Billing address details

Item Object

Field	Type	Required	Description
`itemid`	string	Yes	Product ID
`quantity`	integer	Yes	Quantity ordered
`rate`	number	Yes	Price per unit
`name`	string	No	Item name (for display)

Address Object

Field	Type	Required	Description
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State/Province
`zipcode`	string	No	ZIP/Postal code
`country`	string	No	Country
`phone`	string	No	Contact phone

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/order/checkout" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "customeremail": "[email protected]",
    "items": [
      {
        "itemid": "507f1f77bcf86cd799439011",
        "quantity": 2,
        "rate": 1999.99,
        "name": "Premium Widget"
      },
      {
        "itemid": "507f1f77bcf86cd799439012",
        "quantity": 1,
        "rate": 999.99,
        "name": "Standard Widget"
      }
    ],
    "shippingaddress": {
      "address": "123 Main Street",
      "city": "Nairobi",
      "country": "Kenya",
      "phone": "+254712345678"
    }
  }'

javascript

const orderData = {
  customeremail: "[email protected]",
  items: [
    {
      itemid: "507f1f77bcf86cd799439011",
      quantity: 2,
      rate: 1999.99,
      name: "Premium Widget",
    },
    {
      itemid: "507f1f77bcf86cd799439012",
      quantity: 1,
      rate: 999.99,
      name: "Standard Widget",
    },
  ],
  shippingaddress: {
    address: "123 Main Street",
    city: "Nairobi",
    country: "Kenya",
    phone: "+254712345678",
  },
};

const response = await fetch(
  "https://api.cashfin.africa/business/order/checkout",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderData),
  }
);

const data = await response.json();

php

<?php
$orderData = [
  'customeremail' => '[email protected]',
  'items' => [
    [
      'itemid' => '507f1f77bcf86cd799439011',
      'quantity' => 2,
      'rate' => 1999.99,
      'name' => 'Premium Widget'
    ],
    [
      'itemid' => '507f1f77bcf86cd799439012',
      'quantity' => 1,
      'rate' => 999.99,
      'name' => 'Standard Widget'
    ]
  ],
  'shippingaddress' => [
    'address' => '123 Main Street',
    'city' => 'Nairobi',
    'country' => 'Kenya',
    'phone' => '+254712345678'
  ]
];

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/order/checkout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($orderData),
  CURLOPT_HTTPHEADER => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

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

python

import requests

order_data = {
    'customeremail': '[email protected]',
    'items': [
        {
            'itemid': '507f1f77bcf86cd799439011',
            'quantity': 2,
            'rate': 1999.99,
            'name': 'Premium Widget'
        },
        {
            'itemid': '507f1f77bcf86cd799439012',
            'quantity': 1,
            'rate': 999.99,
            'name': 'Standard Widget'
        }
    ],
    'shippingaddress': {
        'address': '123 Main Street',
        'city': 'Nairobi',
        'country': 'Kenya',
        'phone': '+254712345678'
    }
}

response = requests.post(
    'https://api.cashfin.africa/business/order/checkout',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json=order_data
)

result = response.json()

Example Response

json

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "orderno": "ORD-2024-001",
    "status": "processing",
    "items": [
      {
        "itemid": "507f1f77bcf86cd799439011",
        "title": "Premium Widget",
        "quantity": 2,
        "rate": 1999.99,
        "total": 3999.98
      },
      {
        "itemid": "507f1f77bcf86cd799439012",
        "title": "Standard Widget",
        "quantity": 1,
        "rate": 999.99,
        "total": 999.99
      }
    ],
    "subtotal": 4999.97,
    "total": 4999.97,
    "customeremail": "[email protected]",
    "paymentlink": {
      "_id": "507f1f77bcf86cd799439021",
      "shorturl": "https://pay.cashfin.africa/abc123",
      "rawurl": "https://accounts.cashfin.africa/pay/ord_507f1f77bcf86cd799439020"
    },
    "qrcode": "https://api.cashfin.africa/qr/order-507f1f77bcf86cd799439020.png",
    "createdat": "2024-01-15T10:30:00.000Z"
  }
}

List Orders

Retrieve a paginated list of orders for your business.

http

GET /business/order/list

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	10	Results per page (max: 100)
`search`	string	-	Search by order number, customer email, or title
`status`	string	-	Filter by status: `processing`, `paid`, `shipped`, `completed`, `cancelled`

Example Request

cURLJavaScriptPython

bash

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

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/order/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/order/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10, 'status': 'processing'}
)

Success Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439020",
      "orderno": "ORD-2024-001",
      "title": "Order for Premium Widget",
      "status": "processing",
      "balance": 4999.97,
      "customeremail": "[email protected]",
      "createdat": "2024-01-15T10:30:00.000Z",
      "updatedat": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}

Get Order Details

Retrieve full details of a specific order.

http

GET /business/order/details/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Order ID (MongoDB ObjectID)

Example Request

cURLJavaScriptPython

bash

curl -X GET "https://api.cashfin.africa/business/order/details/507f1f77bcf86cd799439020" \
  -H "Authorization: cs_your_client_secret"

javascript

const orderId = "507f1f77bcf86cd799439020";

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

python

import requests

order_id = '507f1f77bcf86cd799439020'

response = requests.get(
    f'https://api.cashfin.africa/business/order/details/{order_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "orderno": "ORD-2024-001",
    "title": "Order for Premium Widget",
    "status": "processing",
    "balance": 4999.97,
    "customeremail": "[email protected]",
    "items": [
      {
        "itemid": "507f1f77bcf86cd799439011",
        "name": "Premium Widget",
        "quantity": 2,
        "rate": 1999.99
      }
    ],
    "paymentlinks": ["507f1f77bcf86cd799439021"],
    "sourceorigin": "api",
    "createdat": "2024-01-15T10:30:00.000Z",
    "updatedat": "2024-01-15T10:30:00.000Z"
  }
}

Order Workflow

Create Checkout → Order created with processing status
Customer Pays → Payment link sent or QR code scanned
Payment Confirmed → Order moves to paid status
Fulfillment → Order fulfilled and completed

Order Statuses

Status	Description
`processing`	Order created, awaiting payment
`paid`	Payment received
`shipped`	Order shipped
`completed`	Order fulfilled
`cancelled`	Order cancelled

Payment Options

When an order is created, a payment link is automatically generated. Customers can pay via:

Payment Link - Direct URL to payment page
QR Code - Scannable QR code for mobile payments

Using the Payment Link

The response includes a payment link that customers can use:

javascript

const { data } = await createOrder(orderData);

// Redirect customer to payment
window.location.href = data.paymentlink.shorturl;

// Or display QR code
document.getElementById("qr-code").src = data.qrcode;

Error Responses

Validation Errors

json

{
  "success": false,
  "error": "Items are required"
}

Invalid Product

json

{
  "success": false,
  "error": "Product not found: 507f1f77bcf86cd799439011"
}

Order Object Reference

Field	Type	Description
`_id`	string	Unique order identifier
`orderno`	string	Human-readable order number
`status`	string	Order status
`items`	array	Order line items
`subtotal`	number	Sum of item totals
`total`	number	Final order amount
`customeremail`	string	Customer email
`customerid`	string	Associated customer ID
`shippingaddress`	object	Shipping details
`billingaddress`	object	Billing details
`paymentlink`	object	Payment link details
`active`	boolean	Whether order is active
`sourceorigin`	string	Origin (`api`, `dashboard`, `storefront`)
`createdat`	string	ISO 8601 creation timestamp
`updatedat`	string	ISO 8601 last update timestamp

Use Cases

E-commerce Checkout Integration

javascript

async function processCheckout(cart, customer) {
  // Convert cart to order items
  const items = cart.items.map((item) => ({
    itemid: item.productId,
    quantity: item.quantity,
    rate: item.price,
    title: item.name,
  }));

  // Create order
  const response = await fetch(
    "https://api.cashfin.africa/business/order/checkout",
    {
      method: "POST",
      headers: {
        Authorization: API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customeremail: customer.email,
        items: items,
        shippingaddress: customer.shippingAddress,
      }),
    }
  );

  const { data } = await response.json();

  // Return payment link for customer
  return {
    orderId: data._id,
    orderNumber: data.orderno,
    paymentUrl: data.paymentlink.shorturl,
    total: data.total,
  };
}

Order with Webhook Handling

javascript

// 1. Create order
const order = await processCheckout(cart, customer);

// 2. Redirect to payment
window.location.href = order.paymentUrl;

// 3. Handle webhook when payment completes
app.post("/webhooks/cashfin", (req, res) => {
  const event = req.body;

  if (event.type === "payment.completed") {
    const orderId = event.data.reference;
    fulfillOrder(orderId);
  }

  res.status(200).json({ received: true });
});

Bulk Order Import

javascript

async function importOrders(externalOrders) {
  const results = [];

  for (const order of externalOrders) {
    try {
      const response = await fetch(
        "https://api.cashfin.africa/business/order/checkout",
        {
          method: "POST",
          headers: {
            Authorization: API_KEY,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            customeremail: order.customerEmail,
            items: order.items.map((item) => ({
              itemid: item.productId,
              quantity: item.qty,
              rate: item.unitPrice,
            })),
          }),
        }
      );

      const data = await response.json();
      results.push({ success: true, orderId: data.data._id });
    } catch (error) {
      results.push({ success: false, error: error.message });
    }
  }

  return results;
}

Orders API ​

Endpoints ​

Create Order Checkout ​

Request Body ​

Item Object ​

Address Object ​

Example Request ​

Example Response ​

List Orders ​

Query Parameters ​

Example Request ​

Success Response ​

Get Order Details ​

Path Parameters ​

Example Request ​

Success Response ​

Order Workflow ​

Order Statuses ​

Payment Options ​

Using the Payment Link ​

Error Responses ​

Validation Errors ​

Invalid Product ​

Order Object Reference ​

Use Cases ​

E-commerce Checkout Integration ​

Order with Webhook Handling ​

Bulk Order Import ​

Orders API

Endpoints

Create Order Checkout

Request Body

Item Object

Address Object

Example Request

Example Response

List Orders

Query Parameters

Example Request

Success Response

Get Order Details

Path Parameters

Example Request

Success Response

Order Workflow

Order Statuses

Payment Options

Using the Payment Link

Error Responses

Validation Errors

Invalid Product

Order Object Reference

Use Cases

E-commerce Checkout Integration

Order with Webhook Handling

Bulk Order Import