BILL PAYMENT SERVICES

Payment

The Payment API functions are focused on the flow associated with a typical payment. These include:

QUERY

This provides details for account validation (if applicable) and also a list of packages and prices supported by this service. To query account and or specific package details set type in Authentication QUERY to:

PARAMETERS

Timeout: 60 seconds

Request Parameters

Description

username

STRING

max-length: 256

Username assigned to payment provider expressPay

auth-token

STRING

max-length: 256

Auth token assigned to payment provider by expressPay (token is private and must be secured at all times)

type

STRING

max-length: 32

QUERY

service

STRING

max-length: 64

Use “SERVICES” call to determine list of service identifiers that support “QUERY”

account-number

STRING

max-length: 64

Destination account number at service provider

package

STRING

max-length: 64

Optional service-specific named package that is being queried. All packages will be returned if package is not set.

reference-number

STRING

max-length: 64

Unique reference number associated with query request

Response Parameters (JSON Encoded)

Description

status

INT

  • 0 = Success
  • 1 = Invalid Credentials
  • 2 = Invalid Request
  • 3 = Invalid IP
  • 4 = Invalid Account Number
  • 5 = Service Provider Offline
  • 6 = Invalid Package
  • 7 = Restricted Package
  • 8 = Error

status-text

STRING

max-length: 256

Text describing status

reference-number

STRING

max-length: 64

Echoed from request

account-info

STRING

max-length: 256

Customer name and or other info associated with account provided by Service Provider

options [{name, package, amount, currency, due-date, fee-amount, fee-percent}]

STRING

max-length: 64

List of available options (JSON Array) for requested account. Each array entry has an optional name, optional package, amount, currency, and optional due-date, fee- amount and fee-percent.

If the request specifies a package, only options related to the requested package are returned. If no package is specified in the request, all available options for account- number is returned.

If service supports packages, then package specified in option and corresponding amount has to be provided to “PAY” for the package except if amount is 0 in which case an arbitrary amount can still be paid. Lastly, if option does not specify a package then an arbitrary amount can still be paid in lieu of amount.

  • name = name for display (optional)
  • package = package reference (optional and used to identify package in “PAY”)
  • amount = amount
  • currency = currency
  • due-date = due date (optional)
  • fee-amount = additional fee amount (optional)
  • fee-percent = additional fee percent (optional)

SAMPLE

1curl --location --request POST 'https://sandbox.expresspaygh.com/billpay/api.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'username=your-username' \
5--data-urlencode 'auth-token=your-auth-token' \
6--data-urlencode 'type=QUERY' \
7--data-urlencode 'service=MTN_DATA' \
8--data-urlencode 'account-number=233243722297' \
9--data-urlencode 'reference-number=123'

Response

1{
2	"status": 0,
3	"status-text": "Success",
4	"reference-number": 12394,
5	"account-info": "316152c48865d04e73.2568619f619f52c4d04ec2.177113153192653f52c4d0",
6	"options": [
7		{
8			"title": "1.5GB Data Package",
9			"package": "HUGE Dealz",
10			"amount": 20,
11			"currency": "GHS",
12			"due-date": "10/09/2021"
13		}
14	]
15}

PAY

To initiate a payment, set type in Authentication to PAY:

PARAMETERS

Timeout: 60 seconds

Request Parameters

Description

username

STRING

max-length: 256

Username assigned to payment provider expressPay

auth-token

STRING

max-length: 256

Auth token assigned to payment provider by expressPay (token is private and must be secured at all times)

type

STRING

max-length: 32

PAY

service

STRING

max-length: 64

Use “SERVICES” call to determine list of service identifiers that support “QUERY”

account-number

STRING

max-length: 64

Destination account number at service provider

package

STRING

max-length: 64

Optional service-specific named package that is being queried. All packages will be returned if package is not set.

reference-number

STRING

max-length: 64

Unique reference number associated with query request

currency

STRING

max-length: 3

Currency of payment (Accepted currency “GHS”)

amount

STRING

max-length: 64

Amount (format XX.YY). Includes all fees indicated by fee_amount and or fee_percent

payer-name

STRING

max-length: 64

Optional name of person initiating this payment (eg. John Doe. Required for MVISA service)

payer-phonenumber

STRING

max-length: 15

Optional E.164 formatted phone number of person initiating this payment (eg. +233244123123. Required for MVISA service)

Response Parameters (JSON Encoded)

Description

status

INT

  • 0 = Transaction Success
  • 1 = Invalid Credentials
  • 2 = Invalid Request
  • 3 = Invalid IP
  • 4 = Error
  • 5 = Invalid Account Number
  • 6 = Transaction Failed
  • 7 = Transaction Pending
  • 8 = Insufficient Funds
  • 9 = Duplicate Request (Status-text and remaining fields will describe original transaction)
  • 10 = Service Provider Offline
  • 11 = Duplicate Transaction (Different requests identified as duplicate by the Service Provider)
  • 12 = Invalid Amount for Requested Package No further action is required for all PAY response status except for status 7 (Transaction Pending) – in which case final transaction status needs to be confirmed using the STATUS call.

status-text

STRING

max-length: 256

Text describing status

reference-number*

STRING

max-length: 64

Echoed from request

transaction-id

STRING

max-length: 64

expressPay transaction id

receipt-number

STRING

max-length: 64

Receipt number issued by service provider if transaction processed successfully

timestamp

STRING

max-length: 256

Transaction processed timestamp (UTC)

balance

STRING

max-length: 64

Remaining payment provider balance (XX.YY)

currency

STRING

max-length: 3

Remaining payment provider currency ("GHS")

SAMPLE

1curl --location --request POST 'https://sandbox.expresspaygh.com/billpay/api.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=0hactr41v1hmmesjee2vfglhse' \
4--data-urlencode 'username=your-username' \
5--data-urlencode 'auth-token=<auth-token>' \
6--data-urlencode 'type=PAY' \
7--data-urlencode 'service=MTN_DATA' \
8--data-urlencode 'account-number=233243223959' \
9--data-urlencode 'reference-number=a8b153f3-059f-4f6f-89dc-0fd4861a3cbf' \
10--data-urlencode 'package=DAILY_20MB' \
11--data-urlencode 'currency=GHS' \
12--data-urlencode 'amount=0.50' \
13--data-urlencode 'payer-name=Zaraki-Kenpachi'

Response

1{
2	"status": 0,
3	"status-text": "Success",
4	"reference-number": "99526338-1009-40fc-a2d7-3090d308f756",
5	"balance": "4354.64",
6	"currency": "GHS",
7	"transaction-id": "8ff5c326u6cba",
8	"receipt-number": "",
9	"timestamp": "20220112102130"
10}

STATUS

To check the status PAY of a request, set type in Authentication to STATUS. Additional parameters to be specified including authentication parameters are:

PARAMETERS

Timeout: 60 seconds

Request Parameters

Description

username

STRING

max-length: 256

Username assigned to payment provider expressPay

auth-token

STRING

max-length: 256

Auth token assigned to payment provider by expressPay (token is private and must be secured at all times)

type

STRING

max-length: 32

STATUS

reference-number*

STRING

max-length: 64

Reference number associated with previously submitted “PAY” request

transaction-id*

STRING

max-length: 64

expressPay transaction-id associated with previously received “PAY” response

Either reference-number or transaction-id has to be set

Response Parameters (JSON Encoded)

Description

status

INT

  • 0 = Transaction Success
  • 1 = Invalid Credentials
  • 2 = Invalid Request
  • 3 = Invalid IP
  • 4 = Error
  • 5 = Invalid reference number or transaction-id
  • 6 = Transaction Failed
  • 7 = Transaction Pending

status-text

STRING

max-length: 256

Text describing status

timestamp

STRING

max-length: 64

Transaction processed timestamp (UTC)

transaction-id

STRING

max-length: 64

expressPay transaction id

SAMPLE

1curl --location --request POST 'https://sandbox.expresspaygh.com/billpay/api.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'username=your-username' \
5--data-urlencode 'auth-token=<auth-token>' \
6--data-urlencode 'type=STATUS' \
7--data-urlencode 'reference-number=RF34234' \
8--data-urlencode 'transaction-id=DS9043'

Response

1{
2	"status": 0,
3	"status-text": "Success",
4	"reference-number": "bcc6a38a-8328-418b-9317-2c28e2ec2ab0",
5	"transaction-id": "ea073e87u43ff",
6	"timestamp": "2022-01-11 10:46:28"
7}