Payments API Overview

The Payments API allows you to accept payments, manage invoices, and handle recurring subscriptions.

Cashfin's Payments module provides everything you need to monetize your business. Accept mobile money payments via M-Pesa, create professional invoices with automatic payment links, and set up recurring subscriptions for predictable revenue. All payment endpoints support webhooks for real-time notifications.

What You Can Build

• Payment Processing: Accept M-Pesa payments with STK Push integration
• Billing Systems: Generate and track invoices with automatic payment links
• Subscription Services: Create recurring billing with flexible cycles and trials
• Financial Dashboards: Track payments, invoices, and subscription status

Available Endpoints

Method	Endpoint	Description
POST	/business/payments/mobile/request	Initiate M-Pesa payment
POST	/business/invoice/create	Create an invoice
GET	/business/invoice/list	List all invoices
GET	/business/invoice/details/:id	Get invoice details
PATCH	/business/invoice/update/:id	Update an invoice
POST	/business/subscription/create	Create a subscription
GET	/business/subscription/details/:id	Get subscription details

Payment Methods

Cashfin currently supports the following payment methods:

Method	Description	Regions
M-Pesa	Mobile money payment	Kenya

Payment Flow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Your App      │    │   Cashfin Business API   │    │   M-Pesa        │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │
         │  1. Create Payment   │                      │
         │─────────────────────►│                      │
         │                      │  2. STK Push         │
         │                      │─────────────────────►│
         │  3. Checkout ID      │                      │
         │◄─────────────────────│                      │
         │                      │                      │
         │                      │  4. User Confirms    │
         │                      │◄─────────────────────│
         │                      │                      │
         │  5. Webhook          │                      │
         │◄─────────────────────│                      │
         │                      │                      │

1. Your application requests a payment
2. Cashfin sends STK Push to customer's phone
3. Checkout request ID returned immediately
4. Customer enters M-Pesa PIN to confirm
5. Webhook notification sent on completion

Quick Example

Initiate M-Pesa Payment

curl -X POST "https://api.cashfin.africa/business/payments/mobile/request" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "phone": "254712345678",
    "referenceid": "ORDER-001"
  }'

Response

{
  "success": true,
  "message": "Payment created successfully",
  "data": {
    "checkoutrequestid": "ws_CO_123456789",
    "merchantrequestid": "12345-67890",
    "responsecode": "0",
    "responsedescription": "Success. Request accepted for processing"
  }
}

Payment Statuses

Status	Description
pending	Payment initiated, awaiting confirmation
completed	Payment successful
failed	Payment failed or rejected
cancelled	Payment cancelled by user

Webhooks

Set up webhooks to receive real-time payment notifications:

Event	Description
payment.initiated	Payment request sent
payment.completed	Payment confirmed
payment.failed	Payment failed

See Webhooks Guide for setup instructions.

Next Steps

• Invoices - Create and manage invoices with payment links
• Mobile Payments (M-Pesa) - Detailed M-Pesa integration
• Subscriptions - Recurring billing and subscription management