API Reference

get

Query parameters

currencystringRequired

transaction_typestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

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 Zambia","provider_code":"mtn_zm","transaction_method":"MOBILE_MONEY","transaction_method_name":"Mobile Money","transaction_type":"Collection","transaction_currency":"ZMW","min_amount":1,"max_amount":10000,"max_daily_amount":100000,"is_active":true,"option_prefixes":["76","96"]},{"provider_name":"Airtel Money Zambia","provider_code":"airtel_zm","transaction_method":"MOBILE_MONEY","transaction_method_name":"Mobile Money","transaction_type":"Collection","transaction_currency":"ZMW","min_amount":1,"max_amount":10000,"max_daily_amount":100000,"is_active":true,"option_prefixes":["57","77","97"]}]}

get

/data/payment-providers

HTTPcURLJavaScriptPython

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

200

Payment providers retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "payment_providers": [
      {
        "provider_name": "MTN Mobile Money Zambia",
        "provider_code": "mtn_zm",
        "transaction_method": "MOBILE_MONEY",
        "transaction_method_name": "Mobile Money",
        "transaction_type": "Collection",
        "transaction_currency": "ZMW",
        "min_amount": 1,
        "max_amount": 10000,
        "max_daily_amount": 100000,
        "is_active": true,
        "option_prefixes": [
          "76",
          "96"
        ]
      },
      {
        "provider_name": "Airtel Money Zambia",
        "provider_code": "airtel_zm",
        "transaction_method": "MOBILE_MONEY",
        "transaction_method_name": "Mobile Money",
        "transaction_type": "Collection",
        "transaction_currency": "ZMW",
        "min_amount": 1,
        "max_amount": 10000,
        "max_daily_amount": 100000,
        "is_active": true,
        "option_prefixes": [
          "57",
          "77",
          "97"
        ]
      }
    ]
  }
}

get

Query parameters

currencystringOptional

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

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":"ZMW","uncleared_balance":40000,"reserve_balance":0,"wallet_type":"MERCHANT_COLLECTION"},{"available_balance":0,"actual_balance":0,"currency":"ZMW","uncleared_balance":0,"reserve_balance":0,"wallet_type":"MERCHANT_PAYOUT"}]}

get

/data/wallet-balances

HTTPcURLJavaScriptPython

GET /data/wallet-balances HTTP/1.1
public-key: text
x-api-version: 1
Accept-Language: en
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": "ZMW",
        "uncleared_balance": 40000,
        "reserve_balance": 0,
        "wallet_type": "MERCHANT_COLLECTION"
      },
      {
        "available_balance": 0,
        "actual_balance": 0,
        "currency": "ZMW",
        "uncleared_balance": 0,
        "reserve_balance": 0,
        "wallet_type": "MERCHANT_PAYOUT"
      }
    ]
  }
}

get

Path parameters

merchant_referencestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

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":"ISTREFRMGRXNNYBWATKJ","transaction_type":"COLLECTION","request_currency":"ZMW","transaction_amount":100000,"transaction_currency":"ZMW","transaction_charge":3000,"transaction_account":"256787008803","charge_customer":false,"total_credit":97000,"provider_code":"mtn_zm","request_amount":100000,"customer_name":"JOHN DOE","transaction_status":"COMPLETED","status_message":"Transaction Completed Successfully"}

get

/data/transaction/verify/{merchant_reference}

HTTPcURLJavaScriptPython

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

200

Transaction retrieved successfully.

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

post

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

Body

application/json

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_zm

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

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

HTTPcURLJavaScriptPython

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

{
  "transaction_method": "MOBILE_MONEY",
  "provider_code": "mtn_zm",
  "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": "ISTREFRMGRXNNYBWATKJ",
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
  }
}

post

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

Body

application/json

internal_referencestringRequired

Internal/gateway transaction reference

Example: ISTREFRMGRXNNYBWATKJ

otpnumber · min: 4Required

OTP Auth

Example: 123456

Responses

202

Authorization request accepted.

application/json

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/authorize

HTTPcURLJavaScriptPython

POST /collections/authorize HTTP/1.1
public-key: text
x-api-version: 1
Accept-Language: en
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "internal_reference": "ISTREFRMGRXNNYBWATKJ",
  "otp": 123456
}

{
  "code": 202,
  "status": "accepted",
  "message": "Request Accepted",
  "data": {
    "internal_reference": "ISTREFRMGRXNNYBWATKJ",
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
    "payment_url": "https://gwpaysdbx.instacompay.com/pay/collection/ISTREFRMGRXNNYBWATKJ"
  }
}

get

Query parameters

provider_codestringRequired

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

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":"Access Bank Nigeria","bank_code":"access_bank_ng","is_active":true},{"bank_name":"Guaranty Trust Bank","bank_code":"gtbank_ng","is_active":true}]}

get

/data/payout-bank-codes

HTTPcURLJavaScriptPython

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

200

Payout bank codes retrieved successfully.

{
  "code": 200,
  "status": "success",
  "message": "Request completed successfully",
  "data": {
    "payout_banks": [
      {
        "bank_name": "Access Bank Nigeria",
        "bank_code": "access_bank_ng",
        "is_active": true
      },
      {
        "bank_name": "Guaranty Trust Bank",
        "bank_code": "gtbank_ng",
        "is_active": true
      }
    ]
  }
}

post

Header parameters

public-keystringRequired

x-api-versionnumberRequired

Accept-Languagestring · enumRequiredDefault: enPossible values:

secret-keystringRequired

Body

application/json

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: ZMW

amountnumberRequired

The amount being requested

Example: 5000

provider_codestringRequired

The provider code as obtained from the payment options

Example: mtn_zm

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

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

HTTPcURLJavaScriptPython

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

{
  "merchant_reference": "MCTREF123456",
  "transaction_method": "MOBILE_MONEY",
  "currency": "ZMW",
  "amount": 5000,
  "provider_code": "mtn_zm",
  "account_number": "17100000034",
  "customer_name": "John Doe",
  "description": "text",
  "extra_params": {
    "bank_code": "access_bank_ng",
    "branch_code": "046"
  }
}

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