PulseKango - Documentation - Unified Mobile Money Gateway

Authentication

Every API request requires an API key supplied through the x-api-key HTTP header.

Header
x-api-key: YOUR_API_KEY

curl -X POST "{ENDPOINT}/v1/payment/init" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security: Keep your API key private. Do not expose it in browser-side JavaScript, mobile applications, public repositories, or logs.

API Conventions

Item	Convention
Base URL	{ENDPOINT}/v1
Content-Type	application/json for POST requests
Authentication	x-api-key header
Partner transaction ID	ftxn_id must be unique for the partner
Customer number	Provided in the transactor field

Payment APIs

Pulse Kango exposes a common payment initiation endpoint for the supported Mobile Money operators. The operator is selected using the operator field.

OMBF — Orange Money BF

TELBF — Telecel Money BF

MOOVBF — Moov Money BF

Prepare

Create a unique partner transaction ID.

OTP

Customer provides OTP where required.

Initiate

Send payment request to Pulse Kango.

Verify

Use the transaction status endpoint when needed.

Orange Money BF

Initiate Payment

POST {ENDPOINT}/v1/payment/init

Use operator: OMBF for Orange Money BF.

Request Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Request Body

Field	Type	Required	Description
amount	number	Required	Payment amount.
otp	string	Required	Customer OTP.
ftxn_id	string	Required	Unique partner transaction ID.
operator	string	Required	Fixed value: OMBF.
transactor	string	Required	Customer phone number.
remarks	string	Optional	Transaction remarks.
customer_firstname	string	Optional	Customer first name.
customer_lastname	string	Optional	Customer last name.
customer_email	string	Optional	Customer email address.

Example

{
  "amount": 100,
  "otp": "410664",
  "ftxn_id": "CL.OMBF-202606251202",
  "operator": "OMBF",
  "transactor": "76000000",
  "remarks": "",
  "customer_firstname": "",
  "customer_lastname": "",
  "customer_email": ""
}

Telecel Money BF

Initiate Payment

POST {ENDPOINT}/v1/payment/init

Use operator: TELBF for Telecel Money BF.

Request Body

Field	Type	Required	Description
amount	number	Required	Payment amount.
otp	string	Required	Customer OTP.
ftxn_id	string	Required	Unique partner transaction ID.
operator	string	Required	Fixed value: TELBF.
transactor	string	Required	Customer phone number.
remarks	string	Optional	Transaction remarks.
customer_firstname	string	Optional	Customer first name.
customer_lastname	string	Optional	Customer last name.
customer_email	string	Optional	Customer email address.

Example

{
  "amount": 100,
  "otp": "410664",
  "ftxn_id": "CL.TELBF-202606251212",
  "operator": "TELBF",
  "transactor": "5834XXXX",
  "remarks": "",
  "customer_firstname": "",
  "customer_lastname": "",
  "customer_email": ""
}

Moov Money BF

Moov Money BF uses a two-step payment process: first generate an OTP, then submit the payment using the external_id returned by the OTP generation request.

1. Generate OTP

POST {ENDPOINT}/v1/payment/otp-generate

Request Body

{
  "amount": 100,
  "operator": "MOOVBF",
  "transactor": "62000000"
}

Field	Type	Required	Description
amount	number	Required	Payment amount.
operator	string	Required	Fixed value: MOOVBF.
transactor	string	Required	Customer phone number.

The Postman collection supplied for this documentation does not contain a sample response for the OTP generation endpoint. The exact response fields should therefore be confirmed from the API implementation before publishing a response example.

2. Initiate Payment

POST {ENDPOINT}/v1/payment/init

The external_id must be the value obtained from the previous Moov OTP generation request.

Request Body

Field	Type	Required	Description
amount	number	Required	Payment amount.
otp	string	Required	Customer OTP.
ftxn_id	string	Required	Unique partner transaction ID.
operator	string	Required	Fixed value: MOOVBF.
transactor	string	Required	Customer phone number.
external_id	string	Required	Identifier returned by the Generate OTP API.
remarks	string	Optional	Transaction remarks.
customer_firstname	string	Optional	Customer first name.
customer_lastname	string	Optional	Customer last name.
customer_email	string	Optional	Customer email address.

Example

{
  "amount": 100,
  "otp": "410664",
  "ftxn_id": "CL.MOOVBF-202606251230",
  "operator": "MOOVBF",
  "transactor": "62000000",
  "external_id": "DER20DXFZG",
  "remarks": "",
  "customer_firstname": "",
  "customer_lastname": "",
  "customer_email": ""
}

Payment Status

Use this endpoint to retrieve the current transaction information using the partner's ftxn_id.

POST {ENDPOINT}/v1/payment/status

Request Body

{
  "ftxn_id": "CL.OMBF-202606251202"
}

Field	Type	Required	Description
ftxn_id	string	Required	Partner's unique transaction ID.

Recommended usage: Store the ftxn_id returned/used for each payment and use it whenever you need to enquire about that transaction.

Wallet Balance

Retrieve the balances of the project wallets and their associated Mobile Money accounts.

GET {ENDPOINT}/v1/wallet/balance

Request

GET {ENDPOINT}/v1/wallet/balance
x-api-key: YOUR_API_KEY

Successful Response

{
  "code": 200,
  "status": "success",
  "data": {
    "message": "balance fetched successfully!",
    "data": [
      {
        "account_id": "PRJ-20260506-111111-XXXXXX",
        "type": "MOOV MONEY BF",
        "balance": "1632.00",
        "last_transfer_ref": "CL.MVBF-20260715-020125-XTW",
        "last_transfer_on": "2026-07-15 02:01:26",
        "last_transfer_type": "COLLECT_MOOVBF",
        "previous_balance": "0.00",
        "balance_credit": "1632.00",
        "balance_debit": "0.00",
        "is_barred_sender": "active",
        "is_barred_receiver": "active",
        "created_at": "2026-05-06T12:20:39.000000Z",
        "updated_at": "2026-07-15T02:01:26.000000Z"
      },
      {
        "account_id": "PRJ-20260506-111111-XXXXXX",
        "type": "ORANGE MONEY BF",
        "balance": "764.00",
        "last_transfer_ref": "CL.OMBF-20260729-184532-OKU",
        "last_transfer_on": "2026-07-29 18:45:35",
        "last_transfer_type": "COLLECT_OMBF",
        "previous_balance": "0.00",
        "balance_credit": "764.00",
        "balance_debit": "0.00",
        "is_barred_sender": "active",
        "is_barred_receiver": "active",
        "created_at": "2026-05-06T12:20:39.000000Z",
        "updated_at": "2026-07-29T18:45:35.000000Z"
      },
      {
        "account_id": "PRJ-20260506-111111-XXXXXX",
        "type": "TELECEL MONEY BF",
        "balance": "1600.00",
        "last_transfer_ref": "CL.TELBF-20260715-020704-VGV",
        "last_transfer_on": "2026-07-15 02:07:05",
        "last_transfer_type": "COLLECT_TELBF",
        "previous_balance": "0.00",
        "balance_credit": "1600.00",
        "balance_debit": "0.00",
        "is_barred_sender": "active",
        "is_barred_receiver": "active",
        "created_at": "2026-05-06T12:20:39.000000Z",
        "updated_at": "2026-07-15T02:07:05.000000Z"
      }
    ]
  }
}

Response Format

API responses use a wrapper containing a top-level HTTP/application code, a status, and a data object.

Successful Payment

{
  "code": 200,
  "status": "success",
  "data": {
    "message": "Transaction processed successfully",
    "data": {
      "created_at": "2026-08-17T10:39:27.000000Z",
      "ref": "CL.OMBF-20260817-103927-VEI",
      "ftxn_id": "PY-20260817-103927-LHLIXU",
      "type": "COLLECT",
      "sub_type": "COLLECT_OMBF",
      "status": "TS",
      "nominal_amount": "290.00",
      "total_amount": "300.00",
      "fees": "9.00",
      "taxes": "1.00",
      "attr1_name": "OTP",
      "attr1_value": "851428",
      "attr2_name": "OPERATOR",
      "attr2_value": "OMBF",
      "attr3_name": "CUSTOMER_FIRST_NAME",
      "attr3_value": null,
      "attr4_name": "CUSTOMER_LAST_NAME",
      "attr4_value": null,
      "attr5_name": "CUSTOMER_EMAIL",
      "attr5_value": null,
      "transactor": "5608XXXX",
      "external_trans_id": "OM260817.1039.22222222",
      "external_payment_date": "2026-08-17 10:39:29",
      "external_status": "200",
      "external_error_code": null,
      "external_message": "online OTP MerchPay transaction of FCFA 300 has been successfully completed between the sender: 5608XXXX and receiver: 5576XXXX. Txn ID: OM260817.1039.22222222"
    }
  }
}

Transaction Fields

Field	Description
ref	Pulse Kango transaction reference.
ftxn_id	Partner transaction identifier.
type	Transaction type. Payment examples use COLLECT.
sub_type	Operator-specific transaction subtype, e.g. COLLECT_OMBF.
status	Transaction status. The supplied examples show TS for successful and TF for failed transactions and TP for pending transactions.
nominal_amount	Transaction nominal amount.
total_amount	Total amount including applicable fees/taxes.
fees	Transaction fees.
taxes	Applicable taxes.
transactor	Customer phone number.
external_trans_id	Operator transaction identifier when available.
external_payment_date	Operator payment date/time when available.
external_status	Operator response/status code when available.
external_error_code	Operator error code when a failure occurs.
external_message	Operator response message.

Errors & Failed Transactions

Validation Error

A validation error can occur before the transaction is processed. For example, the supplied ftxn_id is already registered.

{
  "code": 400,
  "status": "error",
  "data": {
    "message": "Validations error",
    "data": {
      "ftxn_id": [
        "The ftxn id has already been taken."
      ]
    }
  }
}

Failed Payment

A transaction can also be created and returned with a failed transaction status. In the supplied example, the transaction status is TF and the operator returns error code 990417.

{
  "code": 400,
  "status": "failed",
  "data": {
    "message": "Transaction failed",
    "data": {
      "created_at": "2026-09-17T10:19:09.000000Z",
      "ref": "CL.OMBF-20260917-101909-YYR",
      "ftxn_id": "CL.OMBF-202602020292",
      "type": "COLLECT",
      "sub_type": "COLLECT_OMBF",
      "status": "TF",
      "nominal_amount": "97.00",
      "total_amount": "100.00",
      "fees": "3.00",
      "taxes": "0.00",
      "attr1_name": "OTP",
      "attr1_value": "418336",
      "attr2_name": "OPERATOR",
      "attr2_value": "OMBF",
      "attr3_name": "CUSTOMER_FIRST_NAME",
      "attr3_value": null,
      "attr4_name": "CUSTOMER_LAST_NAME",
      "attr4_value": null,
      "attr5_name": "CUSTOMER_EMAIL",
      "attr5_value": null,
      "transactor": "76260200",
      "external_trans_id": null,
      "external_payment_date": null,
      "external_status": null,
      "external_error_code": "990417",
      "external_message": "OTP does not exist"
    }
  }
}

Status Interpretation

Response status	Transaction status	Meaning
success	TS	Transaction processed successfully in the supplied example.
failed	TF	Transaction failed in the supplied example.
pending	TP	Transaction pending in the supplied example.
error	—	Request validation error; the supplied duplicate ftxn_id example is rejected before normal transaction processing.

Integration Checklist

Store your Pulse Kango API key securely.
Generate a unique ftxn_id for every payment request.
Use the correct operator value: OMBF, TELBF, or MOOVBF.
For Moov Money BF, generate the OTP first and pass the returned external_id to the payment request.
Persist the Pulse Kango ref and ftxn_id for transaction tracking.
Use /v1/payment/status for transaction enquiry using the partner ftxn_id.