Skip to content

Initiate Payment

Description

Initiates a payment transaction. Supports three transaction types (C2B, B2C, B2B) across five payment methods (mpesa, airtel, tkash, bank, card). Which fields are required depends on the combination of transaction_type and payment_method — see the parameter table and tabbed examples below.

Auth

Bearer token required.

Endpoint & Method

POST /payments/initiate/

Parameters

Parameter Type Required Notes
merchant_id string Yes Your merchant account number
transaction_type string Yes One of C2B, B2C, B2B
payment_method string Yes One of mpesa, airtel, tkash, bank, card
bank_code string Conditional Required only when payment_method = bank
currency_code string Yes e.g. KES
amount number Yes Transaction amount
account_number string Yes Payer/payee account (e.g. phone number for mobile money)
reference string Yes Merchant's unique transaction reference
account_reference string Conditional Required only when transaction_type = B2B
description string Yes Transaction narrative
result_url string (URL) Yes Webhook callback URL for async result — see Webhooks
email string Conditional Required only when payment_method = card
account_type string Conditional TILL or PAYBILL, required only when transaction_type = B2B

Example Request

Request bodies vary by transaction_type × payment_method. Use the tab matching your integration.

curl -X POST "https://api.cloudpay365.com/api/v1/payments/initiate/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "transaction_type": "C2B",
    "payment_method": "mpesa",
    "currency_code": "KES",
    "amount": 10,
    "account_number": "2547XXXXXXXX",
    "reference": "<YOUR_UNIQUE_REFERENCE>",
    "description": "Test Payout",
    "result_url": "<YOUR_WEBHOOK_URL>"
  }'

curl -X POST "https://api.cloudpay365.com/api/v1/payments/initiate/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "transaction_type": "B2C",
    "payment_method": "mpesa",
    "currency_code": "KES",
    "amount": 10,
    "account_number": "2547XXXXXXXX",
    "reference": "<YOUR_UNIQUE_REFERENCE>",
    "description": "Test Payout",
    "result_url": "<YOUR_WEBHOOK_URL>"
  }'

curl -X POST "https://api.cloudpay365.com/api/v1/payments/initiate/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "transaction_type": "B2B",
    "payment_method": "bank",
    "bank_code": "01",
    "currency_code": "KES",
    "amount": 10,
    "account_number": "<RECIPIENT_ACCOUNT_NUMBER>",
    "reference": "<YOUR_UNIQUE_REFERENCE>",
    "account_reference": "<RECIPIENT_BUSINESS_REFERENCE>",
    "description": "Test Payout",
    "result_url": "<YOUR_WEBHOOK_URL>",
    "account_type": "PAYBILL"
  }'

curl -X POST "https://api.cloudpay365.com/api/v1/payments/initiate/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "transaction_type": "C2B",
    "payment_method": "card",
    "currency_code": "KES",
    "amount": 10,
    "account_number": "<PAYER_ACCOUNT_REFERENCE>",
    "reference": "<YOUR_UNIQUE_REFERENCE>",
    "description": "Test Payout",
    "result_url": "<YOUR_WEBHOOK_URL>",
    "email": "<PAYER_EMAIL>"
  }'

Example Response

A successful call returns 202 Accepted — the transaction is queued for processing, not yet final. Use Transaction Status Query or the webhook callback to find out how it resolves.

{
  "success": true,
  "message": "Request accepted for processing",
  "data": {
    "charges": 0,
    "payment_method": "mpesa",
    "transaction_id": "<TRANSACTION_ID>",
    "merchant_reference": "<YOUR_UNIQUE_REFERENCE>"
  }
}

Example error response

{
  "success": false,
  "message": "Authentication credentials were not provided."
}

Returned as 401 Unauthorized when the Bearer token is missing, invalid, or expired.

Notes / Gotchas

  • Always send a unique reference per transaction — it's the key you'll use to query status and reconcile statements.
  • result_url is per-transaction and may interact with the per-application webhook_url; see Webhooks for the unconfirmed precedence question.
  • Field requirements are conditional on both transaction_type and payment_method together — double-check the combination in the parameter table before going live with a new payment method.
  • 202 Accepted only confirms Hivemind Payments queued the request — it is not proof of payment. Treat the transaction as pending until status-query or the webhook reports a final state.