Skip to main content
POST
/
v1
/
mpesa
/
b2c
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantTransactionId: 'payout_97233',
    amount: 420000,
    phoneNumber: '+254701234567',
    narration: 'Salary payout'
  })
};

fetch('https://api.fingopay.io/v1/mpesa/b2c', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "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 payout reconciliation. Accepts 1-64 characters (letters, numbers, dot, underscore, or hyphen).

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9._-]{1,64}$
Example:

"payout_97233"

​
amount
integer
required

Amount in smallest currency unit (cents). Range 1-15,000,000 (KES 0.01-150,000.00).

Required range: 1 <= x <= 15000000
Example:

420000

​
phoneNumber
string
required

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

Pattern: ^(?:\+254|254|0)(?:7|1)\d{8}$
Example:

"+254701234567"

​
narration
string

Optional narration displayed to the recipient. Maximum 140 characters.

Maximum string length: 140
Example:

"Salary for Aug 2025"

​
webhookUrl
string<uri>

Override webhook destination for this payout.

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 are strings, except reserved key subMerchantDetails which accepts an object.

​
shortcode
string

[Enterprise] Optional shortcode to use for this B2C transfer.

Example:

"600123"

​
subMerchantId
string

[Enterprise] Optional internal sub-merchant identifier configured under your organization.

Example:

"SM-NAIROBI-001"

Response

Accepted — final result will be delivered via webhook.

​
status
string
required
Example:

"success"

​
message
string
required
Example:

"Transaction initiated successfully"

​
data
object
required