Developer Guide

Build, Scale and Innovate with Afrinet's Fintech Infrastructure.

Explore our guides and examples to integrate Afrinet. Start with three simple endpoints: Charge, Payout and Reversal. All require signed requests with your API key and secret.

Download Postman collection

charge.sh

POST https://api.afrinet.global/api/v1/charges
X-Api-Key: {apiKey}
X-Merchant-Id: {merchantId}
X-Afrinet-Timestamp: 1781787600
X-Afrinet-Nonce: {uuid}
X-Afrinet-Signature: sha256={hmac}

{
  "reference": "INV-001",
  "description": "Demo M-Pesa charge using merchant API key",
  "amount": {
    "currency": "KES",
    "value": 1350.00
  },
  "paymentMethod": {
    "paymentType": "mpesa",
    "details": {
      "type": "c2b",
      "phoneNumber": "254722000000"
    }
  }
}

Getting started

Overview

The Transaction Engine exposes three POST endpoints. Use sandbox for testing, then switch to production.

Sandbox

https://sandbox.afrinet.global

Production

https://api.afrinet.global

Endpoints

POST/api/v1/charges

Create a charge (M-Pesa or Card)

POST/api/v1/payouts

Create an M-Pesa payout

POST/api/v1/reversals

Reverse a transaction

Security

Authentication

Every request requires these headers:

Content-Type: application/json
X-Api-Key: {apiKey}
X-Merchant-Id: {merchantId}
X-Afrinet-Timestamp: {unixSeconds}
X-Afrinet-Nonce: {uuid}
X-Afrinet-Signature: sha256={hmacHex}

Sign each request using your apiSecret:

bodyHash = SHA256(rawRequestBody) as hex
stringToSign = METHOD + "\n" + PATH + "\n" + timestamp + "\n" + nonce + "\n" + bodyHash
signature = HMAC_SHA256(stringToSign, apiSecret) as hex

X-Afrinet-Signature: sha256={signature}

PATH — URL path only (e.g. /api/v1/charges)
timestamp — Unix seconds
nonce — unique per request (UUID recommended)
bodyHash — SHA-256 of the exact raw JSON body

Payments

Create Charge

POST/api/v1/charges

Supports M-Pesa (C2B) and Card (hosted checkout).

POST /api/v1/charges
Content-Type: application/json
X-Api-Key: {apiKey}
X-Merchant-Id: {merchantId}
X-Afrinet-Timestamp: {unixSeconds}
X-Afrinet-Nonce: {uuid}
X-Afrinet-Signature: sha256={hmacHex}

{
  "reference": "INV-API-001",
  "description": "Demo M-Pesa charge using merchant API key",
  "amount": {
    "currency": "KES",
    "value": 10.00
  },
  "paymentMethod": {
    "paymentType": "mpesa",
    "details": {
      "type": "c2b",
      "phoneNumber": "254743219405"
    }
  },
  "transfer": [
    {
      "accountNo": "2200000001",
      "description": "Split settlement",
      "amount": {
        "currency": "KES",
        "value": 2.00
      }
    }
  ],
  "metadata": {
    "accountReference": "INV-TRANSFER-001"
  }
}

Field	M-Pesa	Card
paymentType	`mpesa`	`card`
details.type	`c2b`	—
details.mode	—	`HOSTED_CHECKOUT`
transfer	Optional split settlement	—

Payments

Create Payout

POST/api/v1/payouts

Send funds to an M-Pesa recipient via B2C.

POST /api/v1/payouts
Content-Type: application/json
X-Api-Key: {apiKey}
X-Merchant-Id: {merchantId}
X-Afrinet-Timestamp: {unixSeconds}
X-Afrinet-Nonce: {uuid}
X-Afrinet-Signature: sha256={hmacHex}

{
  "reference": "PO-API-001",
  "description": "Demo M-Pesa payout using merchant API key",
  "recipient": [
    {
      "amount": {
        "currency": "KES",
        "value": 10.00
      },
      "paymentMethod": {
        "paymentType": "mpesa",
        "details": {
          "type": "b2c",
          "phoneNumber": "254743219405",
          "commandId": "BusinessPayment"
        }
      }
    }
  ],
  "metadata": {
    "source": "postman"
  }
}

recipient — array of payout targets
details.type — b2c
commandId — BusinessPayment

Payments

Create Reversal

POST/api/v1/reversals

Reverse a completed transaction by its code.

POST /api/v1/reversals
Content-Type: application/json
X-Api-Key: {apiKey}
X-Merchant-Id: {merchantId}
X-Afrinet-Timestamp: {unixSeconds}
X-Afrinet-Nonce: {uuid}
X-Afrinet-Signature: sha256={hmacHex}

{
  "transactionCode": "04LCM000001",
  "reason": "Customer request via merchant API key"
}

transactionCode — code from the original charge or payout
reason — human-readable reversal reason

Envelope

Response format

All endpoints return a standard wrapper. Success: status: "success". Failure: status: "error" with an error object.

{
  "status": "success",
  "statusCode": 200,
  "message": "Request completed successfully",
  "data": {},
  "error": null,
  "requestId": "0cfe4c02-9d6a-4a4a-a8f5-77148ef0de77",
  "timestamp": "2026-06-18T13:00:00Z"
}

Reference

Common errors

Code	HTTP	Cause
INVALID_API_KEY	400	Missing or invalid `X-Api-Key`
MISSING_MERCHANT_ID	400	`X-Merchant-Id` header not sent
INVALID_SIGNATURE	401	Signature mismatch or expired timestamp

Ready to integrate?

Import the Afrinet Postman collection to test all three endpoints with pre-built signing scripts.

View charge request