Create M-Pesa B2B transfer

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantTransactionId: 'b2b_4521',
    amount: 2500000,
    accountNumber: '1234567',
    accountNumberType: 'paybill',
    beneficiary: 'INV-12345',
    narration: 'Restock float'
  })
};

fetch('https://api.fingopay.io/v1/mpesa/b2b', 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"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

POST

mpesa

b2b

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantTransactionId: 'b2b_4521',
    amount: 2500000,
    accountNumber: '1234567',
    accountNumberType: 'paybill',
    beneficiary: 'INV-12345',
    narration: 'Restock float'
  })
};

fetch('https://api.fingopay.io/v1/mpesa/b2b', 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"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "param": "<string>",
    "requestId": "<string>"
  }
}

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

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

Example:

"b2b_4521"

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:

2500000

accountNumber

string

required

Destination till or paybill number.

Example:

"1234567"

accountNumberType

enum<string>

required

Destination M-Pesa account type.

Available options:

till,

paybill

Example:

"paybill"

beneficiary

string

Account reference required when accountNumberType is paybill. Can be blank for till transfers.

Example:

"INV-12345"

narration

string

Optional narration displayed to the beneficiary. Maximum 140 characters.

Maximum string length: 140

Example:

"Restock float"

webhookUrl

string<uri>

Override webhook destination for this transfer.

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.

Hide child attributes

metadata.{key}

Maximum string length: 500

shortcode

string

[Enterprise] Optional shortcode to use for this B2B 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

Hide child attributes

data.merchantTransactionId

string

required

Example:

"mtx_123"

data.transactionId

string

required

Example:

"txn_01j7b6f9p5y9h"

Create M-Pesa B2C disbursement

Initiate local bank transfer

⌘I

Overview

Payments

Payouts

Verification

Accounts

Transactions

Models

Create M-Pesa B2B transfer

Authorizations

Headers

Body

Response