API Reference

get

Query parameters

currencystringRequired

transaction_typestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Responses

200

Payment providers retrieved successfully.

application/json

codenumberRequired

HTTP Status code

Example: 200

statusstring · enumRequired

The status of the response

Example: successPossible values:

messagestringRequired

The message of the response

Example: Request completed successfully

dataobjectRequired

Response data

Example:

{"payment_providers":[{"provider_name":"MTN Mobile Money Uganda","provider_code":"mtn_momo_ug","transaction_method":"MOBILE_MONEY","transaction_method_name":"Mobile Money","transaction_type":"Collection","transaction_currency":"UGX","min_amount":3000,"max_amount":5000000,"max_daily_amount":7000000,"is_active":true,"option_prefixes":["77","78","76","39","79"]},{"provider_name":"Airtel Money Uganda","provider_code":"airtel_money_ug","transaction_method":"MOBILE_MONEY","transaction_method_name":"Mobile Money","transaction_type":"Collection","transaction_currency":"UGX","min_amount":3000,"max_amount":5000000,"max_daily_amount":7000000,"is_active":true,"option_prefixes":["74","75","70","20"]}]}

get/data/payment-providers

GET /data/payment-providers?currency=text&transaction_type=text HTTP/1.1
public-key: text
x-api-version: 1
Accept: */*

200

Payment providers retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "payment_providers": [
      {
        "provider_name": "MTN Mobile Money Uganda",
        "provider_code": "mtn_momo_ug",
        "transaction_method": "MOBILE_MONEY",
        "transaction_method_name": "Mobile Money",
        "transaction_type": "Collection",
        "transaction_currency": "UGX",
        "min_amount": 3000,
        "max_amount": 5000000,
        "max_daily_amount": 7000000,
        "is_active": true,
        "option_prefixes": [
          "77",
          "78",
          "76",
          "39",
          "79"
        ]
      },
      {
        "provider_name": "Airtel Money Uganda",
        "provider_code": "airtel_money_ug",
        "transaction_method": "MOBILE_MONEY",
        "transaction_method_name": "Mobile Money",
        "transaction_type": "Collection",
        "transaction_currency": "UGX",
        "min_amount": 3000,
        "max_amount": 5000000,
        "max_daily_amount": 7000000,
        "is_active": true,
        "option_prefixes": [
          "74",
          "75",
          "70",
          "20"
        ]
      }
    ]
  }
}

get

Query parameters

currencystringOptional

Header parameters

public-keystringRequired

x-api-versionnumberRequired

secret-keystringRequired

Responses

200

Wallet balances retrieved successfully.

application/json

codenumberRequired

HTTP Status code

Example: 200

statusstring · enumRequired

The status of the response

Example: successPossible values:

messagestringRequired

The message of the response

Example: Request completed successfully

dataobjectRequired

Response data

Example:

{"merchant_wallets":[{"available_balance":40000,"actual_balance":40000,"currency":"UGX","uncleared_balance":40000,"reserve_balance":0,"wallet_type":"MERCHANT_COLLECTION"},{"available_balance":0,"actual_balance":0,"currency":"UGX","uncleared_balance":0,"reserve_balance":0,"wallet_type":"MERCHANT_PAYOUT"}]}

get/data/wallet-balances

GET /data/wallet-balances HTTP/1.1
public-key: text
x-api-version: 1
secret-key: text
Accept: */*

200

Wallet balances retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "merchant_wallets": [
      {
        "available_balance": 40000,
        "actual_balance": 40000,
        "currency": "UGX",
        "uncleared_balance": 40000,
        "reserve_balance": 0,
        "wallet_type": "MERCHANT_COLLECTION"
      },
      {
        "available_balance": 0,
        "actual_balance": 0,
        "currency": "UGX",
        "uncleared_balance": 0,
        "reserve_balance": 0,
        "wallet_type": "MERCHANT_PAYOUT"
      }
    ]
  }
}

get

Path parameters

merchant_referencestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Responses

200

Transaction retrieved successfully.

application/json

codenumberRequired

HTTP Status code

Example: 200

statusstring · enumRequired

The status of the response

Example: successPossible values:

messagestringRequired

The message of the response

Example: Request completed successfully

dataobjectRequired

Response data

Example:

{"id":20760,"merchant_reference":"MCTREFT2WMNWZ23SBN6Y","internal_reference":"ELPREFRMGRXNNYBWATKJ","transaction_type":"COLLECTION","request_currency":"UGX","transaction_amount":100000,"transaction_currency":"UGX","transaction_charge":3000,"transaction_account":"256787008803","charge_customer":false,"total_credit":97000,"provider_code":"mtn_momo_ug","request_amount":100000,"customer_name":"JOHN DOE","transaction_status":"COMPLETED","status_message":"Transaction Completed Successfully"}

get/data/transaction/verify/{merchant_reference}

GET /data/transaction/verify/{merchant_reference} HTTP/1.1
public-key: text
x-api-version: 1
Accept: */*

200

Transaction retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "id": 20760,
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
    "internal_reference": "ELPREFRMGRXNNYBWATKJ",
    "transaction_type": "COLLECTION",
    "request_currency": "UGX",
    "transaction_amount": 100000,
    "transaction_currency": "UGX",
    "transaction_charge": 3000,
    "transaction_account": "256787008803",
    "charge_customer": false,
    "total_credit": 97000,
    "provider_code": "mtn_momo_ug",
    "request_amount": 100000,
    "customer_name": "JOHN DOE",
    "transaction_status": "COMPLETED",
    "status_message": "Transaction Completed Successfully"
  }
}

post

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Body

transaction_methodstring · enumRequired

The transaction method to be used.

Example: MOBILE_MONEYPossible values:

provider_codestringRequired

The provider code as obtained from the payment options

Example: mtn_momo_ug

merchant_referencestring · min: 8 · max: 36Required

The unique reference for this request. It must be at least 8 characters long. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API

Example: MCTREF123456

msisdnstringOptional

The mobile money number of the customer. Mandatory for Mobile Money.

Example: 256787701800

mobile_money_hppbooleanOptional

Should be sent with the value true in order for the API to handle the mobile money payment via hosted page

Default: false

currencystringRequired

The 3-character ISO currency code for the request currency

amountnumberRequired

The amount being requested

descriptionstring · min: 10 · max: 30Required

The description/narration for the transaction. Between 10-30 characters

customer_namestringOptional

The name of the customer

customer_emailstringOptional

The email of the customer

redirect_urlstringOptional

The HTTPs redirect URL to which the API will redirect when the payment is successful/failed

card_cipherstringOptional

charge_customerbooleanOptional

Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge

Default: false

allow_final_status_changebooleanOptional

Whether or not the final transaction status can be altered as described in the document

Default: true

Responses

202

Collection initiated successfully.

application/json

codenumberRequired

HTTP Status code

Example: 202

statusstring · enumRequired

The status of the response

Example: acceptedPossible values:

messagestringRequired

Response messae

Example: Request Accepted

dataobjectRequired

Response data

Example: {"internal_reference":"ELPREFRMGRXNNYBWATKJ","merchant_reference":"MCTREFT2WMNWZ23SBN6Y"}

400

The request is invalid

application/json

401

Unauthorized

application/json

422

Unprocessable Entity

application/json

500

An error occurred while processing the request

application/json

post/collections/initialize

POST /collections/initialize HTTP/1.1
public-key: text
x-api-version: 1
Content-Type: application/json
Accept: */*
Content-Length: 349

{
  "transaction_method": "MOBILE_MONEY",
  "provider_code": "mtn_momo_ug",
  "merchant_reference": "MCTREF123456",
  "msisdn": "256787701800",
  "mobile_money_hpp": false,
  "currency": "text",
  "amount": 1,
  "description": "text",
  "customer_name": "text",
  "customer_email": "text",
  "redirect_url": "text",
  "card_cipher": "text",
  "charge_customer": false,
  "allow_final_status_change": true
}

{
  "code": 202,
  "status": "accepted",
  "message": "Request Accepted",
  "data": {
    "internal_reference": "ELPREFRMGRXNNYBWATKJ",
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
  }
}

get

Query parameters

provider_codestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Responses

200

Payout bank codes retrieved successfully.

application/json

codenumberRequired

HTTP Status code

Example: 200

statusstring · enumRequired

The status of the response

Example: successPossible values:

messagestringRequired

The message of the response

Example: Request completed successfully

dataobjectRequired

Response data

Example:

{"payout_banks":[{"bank_name":"Stanbic Bank Uganda","bank_code":"stanbic_bank_ug","is_active":true},{"bank_name":"Guaranty Trust Bank","bank_code":"gtbank_ug","is_active":true}]}

get/data/payout-bank-codes

GET /data/payout-bank-codes?provider_code=text HTTP/1.1
public-key: text
x-api-version: 1
Accept: */*

200

Payout bank codes retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "payout_banks": [
      {
        "bank_name": "Stanbic Bank Uganda",
        "bank_code": "stanbic_bank_ug",
        "is_active": true
      },
      {
        "bank_name": "Guaranty Trust Bank",
        "bank_code": "gtbank_ug",
        "is_active": true
      }
    ]
  }
}

post

Header parameters

public-keystringRequired

x-api-versionnumberRequired

secret-keystringRequired

Body

merchant_referencestring · min: 8 · max: 36Required

The unique reference for this request. It must be at least 8 characters long.

Example: MCTREF123456

transaction_methodstring · enumRequired

The transaction method to be used.

Example: MOBILE_MONEYPossible values:

currencystring · min: 3Required

The 3-character ISO currency code for the request currency.

Example: UGX

amountnumberRequired

The amount being requested

Example: 5000

provider_codestringRequired

The provider code as obtained from the payment options

Example: mtn_momo_ug

account_numberstringRequired

The bank account or mobile money number of the recipient.

Example: 17100000034

customer_namestringRequired

The name of the customer.

Example: John Doe

descriptionstring · min: 10 · max: 30Required

The description/narration for the transaction. Between 10-30 characters

Responses

202

Payout initiated successfully.

application/json

codenumberRequired

HTTP Status code

Example: 202

statusstring · enumRequired

The status of the response

Example: acceptedPossible values:

messagestringRequired

The message of the response

Example: Request Accepted

dataobjectRequired

Response data

Example: {"internal_reference":"ELPREFRMGRXNNYBWATKJ","merchant_reference":"MCTREFT2WMNWZ23SBN6Y"}

400

The request is invalid

application/json

401

Unauthorized

application/json

422

Unprocessable Entity

application/json

500

An error occurred while processing the request

application/json

post/payout/send-funds

POST /payout/send-funds HTTP/1.1
public-key: text
x-api-version: 1
secret-key: text
Content-Type: application/json
Accept: */*
Content-Length: 249

{
  "merchant_reference": "MCTREF123456",
  "transaction_method": "MOBILE_MONEY",
  "currency": "UGX",
  "amount": 5000,
  "provider_code": "mtn_momo_ug",
  "account_number": "17100000034",
  "customer_name": "John Doe",
  "description": "text",
  "extra_params": {
    "bank_code": "text"
  }
}

{
  "code": 202,
  "status": "accepted",
  "message": "Request Accepted",
  "data": {
    "internal_reference": "ELPREFRMGRXNNYBWATKJ",
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
  }
}

PreviousRSA Signature Verification NextAvailing Payout Funds

Last updated 2 months ago