1. Overview

Welcome to the Eagle Pay API specification. This reference guide provides the technical layout, response models, validation structures, and workflow requirements to integrate payment collections (deposits) and payouts (withdrawals) directly inside your web platform or backend systems.

Eagle Pay connects directly to local wallets and banks, standardizing different regional payment formats into a single, high-reliability JSON protocol.

Supported Methods

Eagle Pay automatically resolves deposits and payouts across three distinct transaction schemas: eWallet (Mobile Money), Voucher (Direct Codes), and Bank Transfers.

Unified Payer Payloads

Depending on the transaction method_type, the parameters inside the payer or recipient object must follow these exact structures:

eWallet Method Schema JSON

{
  "reference_id": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "payer": {
    "method_type": "ewallet",
    "method_id": "1",
    "msisdn": "260978942121",
    "amount": "10"
  },
  "platform": "web",
  "region_name": "zambia"
}

Note: For mtc_maris and paytoday, the payer details must include an intent_token.

Voucher Method Schema JSON

{
  "reference_id": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "payer": {
    "method_type": "voucher",
    "method_id": "1",
    "msisdn": "260978942121",
    "voucher": "00523456782"
  },
  "platform": "web",
  "region_name": "zambia"
}

Bank Method Schema JSON

{
  "reference_id": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  "payer": {
    "method_type": "bank",
    "method_id": "1",
    "msisdn": "260978942121",
    "amount": "10",
    "bank_account": "00523456782",
    "bank_account_holder": "Agripa Chipasha"
  },
  "platform": "web",
  "region_name": "zambia"
}

2. Authentication

Eagle Pay APIs authenticate clients using Basic Authentication headers. You must supply your Merchant API Client ID as the username and your Sandbox or Production Secret Token as the password.

2.1 Common Headers

Every request sent to Eagle Pay must supply the following HTTP headers:

Header Name	Requirement	Description
Authorization	Required	Standard HTTP Basic Auth token structure: `Basic <base64(client_id:api_token)>`
Content-Type	Required	Must be set to `application/json` for all POST requests.
Accept	Required	Must be set to `application/json`.

POST /api/v1/transaction/deposit

3.1 Initiate Deposit

Submit a collection request to prompt the payer for a mobile money wallet transfer, voucher validation, or bank transfer. The request is processed asynchronously and supports instant notification via webhook.

Request Parameters

Field	Type	Requirement	Description
reference_id	string	Required	A unique client-generated UUID to track the transaction and ensure idempotency.
platform	string	Required	The application interface source, e.g. `web`, `android`, `ios`.
region_name	string	Required	The name of the target region, e.g. `zambia`, `congo`, `namibia`.
payer	object	Required	Container object containing nested method parameters. Click toggle below to view.

Field	Type	Requirement	Description
method_type	string	Required	One of `ewallet`, `voucher`, or `bank`.
method_id	string	Required	The database ID of the configured payment method.
msisdn	string	Required	The phone number of the customer initiating the deposit.
amount	string	Conditional	Decimal string representation of the amount (Required for `ewallet` and `bank`).
voucher	string	Conditional	The voucher validation PIN (Required for `voucher`).
bank_account	string	Conditional	The target bank account number (Required for `bank`).
bank_account_holder	string	Conditional	The legal name of the bank account owner (Required for `bank`).
intent_token	string	Conditional	Payment authorization intent token (Required for `mtc_maris` and `paytoday`).

GET /api/v1/transaction/deposit/{reference_id}

3.2 Check Deposit Status

Inspect the current state of a previously submitted deposit request by passing its unique reference_id in the URL path. Use this to poll when callback webhooks fail or drop.

POST /api/v1/transaction/payout

4.1 Initiate Payout

Submit a payout request to disburse funds from your merchant balance to a mobile money wallet, voucher terminal, or bank account. The system validates available balances instantly before accepting.

Request Parameters

Field	Type	Requirement	Description
reference_id	string	Required	A unique client-generated UUID to ensure idempotency and track the payout transaction.
platform	string	Required	The application interface source, e.g. `web`, `android`, `ios`.
region_name	string	Required	The name of the target region, e.g. `zambia`, `congo`, `namibia`.
recipient	object	Required	Container object containing nested recipient parameters. Click toggle below to view.

Field	Type	Requirement	Description
method_type	string	Required	One of `ewallet`, `voucher`, or `bank`.
method_id	string	Required	The database ID of the configured payment method.
msisdn	string	Required	The phone number of the payout recipient.
amount	string	Conditional	Decimal string representation of the amount (Required for `ewallet` and `bank`).
voucher	string	Conditional	The voucher identifier details (Required for `voucher`).
bank_account	string	Conditional	The target bank account number (Required for `bank`).
bank_account_holder	string	Conditional	The name of the destination account owner (Required for `bank`).

GET /api/v1/transaction/payout/{reference_id}

4.2 Check Payout Status

Verify the transfer status of a previously requested payout. Path matches your transaction reference_id.

WEBHOOK POST /your-callback-endpoint

5.1 Deposit Callback

Eagle Pay triggers this notification webhook automatically when a deposit completes successfully or fails. Your server must listen to this payload and respond with a 200 OK.

WEBHOOK POST /your-callback-endpoint

5.2 Payout Callback

Sent when a payout transaction reaches final state (e.g. Complete or Failed).

6. Error Reference

When an API request fails, Eagle Pay returns a structured JSON error response outlining the issue. The response contains standard status flags, HTTP status codes, and descriptive messages.

Common HTTP Status Codes

Code	Type	Description
400	Bad Request	The server cannot process the request due to malformed payload syntax.
401	Unauthorized	Authentication credentials are missing or invalid.
409	Conflict	The transaction reference ID already exists in the system database.
422	Unprocessable Entity	Validation failed on request fields (e.g. invalid MSISDN format, missing amount).
502	Bad Gateway	Telco operator services (e.g. MTN MoMo network) are temporarily unavailable.