Skip to main content
POST
/
v1
/
mpesa
/
charge
Create M‑Pesa C2B charge (STK Push)
curl --request POST \
  --url https://api.fingopay.io/v1/mpesa/charge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "+254712345678",
  "amount": 10000,
  "narration": "Invoice #1234",
  "merchantTransactionId": "mtx_123",
  "webhookUrl": "https://example.com/webhooks/fingo",
  "metadata": {}
}'
{
  "status": "success",
  "message": "Transaction initiated successfully",
  "data": {
    "merchantTransactionId": "mtx_123",
    "transactionId": "txn_01j7b6f9p5y9h"
  }
}
Accepts the request and returns 202 Accepted. The final result is delivered via webhook (transaction.succeeded or transaction.failed).

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string<uuid>

Unique key to safely retry POST without duplicates.

Body

application/json
​
phoneNumber
string
required
Example:

"+254712345678"

​
amount
integer
required

Smallest currency unit (e.g., 100=KES 1.00)

Example:

10000

​
merchantTransactionId
string
required
Example:

"mtx_123"

​
narration
string
Maximum length: 140
Example:

"Invoice #1234"

​
webhookUrl
string<uri>
Example:

"https://example.com/webhooks/fingo"

​
metadata
object

Response

Accepted — final result will be delivered via webhook.

​
status
string
Example:

"success"

​
message
string
Example:

"Transaction initiated successfully"

​
data
object
⌘I