Skip to main content
POST
/
v1
/
mpesa
/
charge
JavaScript
import FingoPay from '@fingoafrica/fingo-pay';

const client = new FingoPay({
  apiKey: process.env['FINGO_PAY_API_KEY'], // This is the default and can be omitted
});

const acceptedResponse = await client.mpesa.createCharge({
  amount: 150000,
  merchantTransactionId: 'invoice_48291',
  phoneNumber: '+254712345678',
});

console.log(acceptedResponse.data);
{
  "status": "success",
  "message": "Transaction initiated successfully",
  "data": {
    "merchantTransactionId": "mtx_123",
    "transactionId": "txn_01j7b6f9p5y9h"
  }
}

Authorizations

​
Authorization
string
header
required

Use your API key as a Bearer token. Example: Authorization: Bearer sk_live_...

Headers

​
Idempotency-Key
string<uuid>

Unique key to safely retry POST without duplicates. Required in live environment.

Body

application/json
​
merchantTransactionId
string
required

Merchant-side reference used for reconciliation. Accepts 1-64 characters (letters, numbers, dot, underscore, or hyphen).

Required string length: 1 - 64
Example:

"invoice_48291"

​
amount
integer
required

Amount in smallest currency unit (cents). Must be whole KES (divisible by 100). Range 100-25,000,000 (KES 1.00-250,000.00).

Required range: 100 <= x <= 25000000
Example:

150000

​
phoneNumber
string
required

Customer MSISDN in Kenyan format (+2547/2547/07 or +2541/2541/01 followed by eight digits).

Example:

"+254712345678"

​
narration
string

Optional customer-facing narration. Maximum 140 characters.

Maximum string length: 140
Example:

"Invoice 48291"

​
webhookUrl
string<uri>

Override webhook destination for this charge.

Example:

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

​
metadata
object

Custom metadata key-value pairs. Up to 20 entries. Keys 1-64 characters (letters, numbers, dot, underscore, or hyphen). Values up to 500 characters.

​
shortcode
string

Optional collections shortcode to override the default paybill or till.

Example:

"123456"

​
targetAccountNo
string

Optional customer account or ticket reference required by certain billers.

Example:

"ACC-88923"

​
customDisplayName
string

Optional custom display name shown to customer (alphanumeric and spaces only, max 40 chars).

Maximum string length: 40
Example:

"ACME Store"

Response

Accepted — final result will be delivered via webhook.

​
status
string
required
Example:

"success"

​
message
string
required
Example:

"Transaction initiated successfully"

​
data
object
required