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

---

Create Order Checkout

Create a new order with items and customer information.

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

cURL

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

{
  "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"
  }
}

---

Order Workflow

1. Create Checkout → Order created with processing status
2. Customer Pays → Payment link sent or QR code scanned
3. Payment Confirmed → Order moves to paid status
4. 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:

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

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

Invalid Product

{
  "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

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

// 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

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;
}