Enterprise Integration Guide

Who this guide is for

Use this guide if you are an aggregator or a high-volume merchant that needs:

Dedicated M-Pesa shortcode routing
Sub-merchant level transaction attribution
Advanced payout routing controls

If you do not need dedicated shortcode routing or sub-merchant attribution, use the standard endpoint payloads and only send required fields.

Integration paths

Path	Best for	Payload style
Standard merchant path	Most merchants	Required fields only
Enterprise path	Aggregators and large merchants	Required + enterprise fields

Enterprise-only fields by endpoint

The table below lists fields marked with the ENTERPRISE badge in the API reference.

Endpoint	Field	Notes
`POST /v1/mpesa/charge`	`shortcode` ENTERPRISE	Route via your dedicated collections shortcode
`POST /v1/mpesa/charge`	`subMerchantId` ENTERPRISE	Auto-created on first use if missing; blocked only when suspended
`POST /v1/mpesa/charge`	`metadata.subMerchantDetails` ENTERPRISE	Optional enrichment details for first-time auto-create
`POST /v1/mpesa/b2c`	`shortcode` ENTERPRISE	Route via your dedicated payouts shortcode
`POST /v1/mpesa/b2c`	`subMerchantId` ENTERPRISE	Auto-created on first use if missing; blocked only when suspended
`POST /v1/mpesa/b2c`	`metadata.subMerchantDetails` ENTERPRISE	Optional enrichment details for first-time auto-create
`POST /v1/mpesa/b2b`	`shortcode` ENTERPRISE	Route via your dedicated payouts shortcode
`POST /v1/mpesa/b2b`	`subMerchantId` ENTERPRISE	Auto-created on first use if missing; blocked only when suspended
`POST /v1/mpesa/b2b`	`metadata.subMerchantDetails` ENTERPRISE	Optional enrichment details for first-time auto-create
`GET /v1/transactions`	`shortcode` ENTERPRISE	Filter results by dedicated shortcode number

Do not send enterprise-only fields unless your integration requires them. Over-specifying optional fields is a common source of integration errors.

End-to-end enterprise setup

Provision dedicated shortcodes

Work with Fingo to provision dedicated shortcode setup for your organization.

Collections traffic is routed through your collections shortcode.
Payout traffic is routed through your payouts shortcode.

Set up sub-merchants (if applicable)

You can pass subMerchantId directly in requests.

If the ID does not exist yet for your organization, Fingo auto-creates it in active state.
If the ID exists and is suspended, the request is rejected.
You can pass metadata.subMerchantDetails to enrich first-time auto-created records.

Use your own internal sub-merchant identifiers consistently in requests.

Start with minimal payloads

Go live first with required fields only, then add enterprise-only fields where you need deterministic routing.

Add enterprise routing fields intentionally

Add shortcode and subMerchantId only on flows that require them.

Apply enterprise fields per transaction type, not globally across all requests.

Verify webhook payloads and reconciliation

Verify webhook signatures, reconcile by merchantTransactionId and transactionId, and monitor failure reasons for optional-field misuse.

Use the shortcode query parameter on GET /v1/transactions to scope transaction queries to a specific dedicated shortcode. This is useful for reconciling traffic per shortcode without client-side filtering.

Request patterns

C2B charge

curl -X POST "https://api.fingopay.io/v1/mpesa/charge" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 8b47872a-4de9-4c13-b73a-19803f55b1e4" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "invoice_48291",
    "amount": 150000,
    "phoneNumber": "+254712345678",
    "narration": "Invoice 48291"
  }'

curl -X POST "https://api.fingopay.io/v1/mpesa/charge" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 90d24f95-7f17-4f65-83fa-7369e555b12a" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "invoice_48291_sm_001",
    "amount": 150000,
    "phoneNumber": "+254712345678",
    "narration": "Invoice 48291",
    "shortcode": "600123",
    "subMerchantId": "SM-NAIROBI-001",
    "metadata": {
      "subMerchantDetails": {
        "name": "Nairobi West Branch",
        "riskLevel": "medium"
      }
    }
  }'

B2C payout

curl -X POST "https://api.fingopay.io/v1/mpesa/b2c" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 2d95d474-2ef8-4446-b9cb-5d8b3401434d" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "payout_97233",
    "amount": 420000,
    "phoneNumber": "+254701234567",
    "narration": "Salary payout"
  }'

curl -X POST "https://api.fingopay.io/v1/mpesa/b2c" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 3a4cab6d-ff57-4b03-b2cd-20f8cad65baa" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "payout_97233_sm_001",
    "amount": 420000,
    "phoneNumber": "+254701234567",
    "narration": "Salary payout",
    "shortcode": "600123",
    "subMerchantId": "SM-NAIROBI-001",
    "metadata": {
      "subMerchantDetails": {
        "name": "Nairobi West Branch",
        "riskLevel": "high"
      }
    }
  }'

B2B transfer

curl -X POST "https://api.fingopay.io/v1/mpesa/b2b" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 5a101014-d59d-4d0b-a9a8-fd3092ab28f3" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "b2b_4521",
    "amount": 2500000,
    "accountNumber": "1234567",
    "accountNumberType": "paybill",
    "beneficiary": "INV-12345",
    "narration": "Restock float"
  }'

curl -X POST "https://api.fingopay.io/v1/mpesa/b2b" \
  -H "Authorization: Bearer $FINGO_API_KEY" \
  -H "Idempotency-Key: 805d1c59-6c47-4ac6-9537-4ddfef438584" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "b2b_4521_sc_600123",
    "amount": 2500000,
    "accountNumber": "1234567",
    "accountNumberType": "paybill",
    "beneficiary": "INV-12345",
    "narration": "Restock float",
    "shortcode": "600123",
    "subMerchantId": "SM-NAIROBI-001",
    "metadata": {
      "subMerchantDetails": {
        "name": "Nairobi West Branch",
        "riskLevel": "low"
      }
    }
  }'

Common mistakes to avoid

Sending dedicated shortcode values that do not belong to your organization
Reusing idempotency keys with different request bodies
Including optional routing fields in all requests by default

Next steps

API Reference

View endpoint-level field details and interactive playground.

Webhooks

Verify signatures and handle webhook events.

​Who this guide is for

​Integration paths

​Enterprise-only fields by endpoint

​End-to-end enterprise setup

​Request patterns

​C2B charge

​B2C payout

​B2B transfer

​Common mistakes to avoid

​Next steps

API Reference

Webhooks

Who this guide is for

Integration paths

Enterprise-only fields by endpoint

End-to-end enterprise setup

Request patterns

C2B charge

B2C payout

B2B transfer

Common mistakes to avoid

Next steps