Search Documentation
Introduction
Accept Payments
Bill Payment Services
SDKs
Plugins
Testing
ACCEPTING PAYMENTS
Merchant API
This API enables merchants to accept payments from their customers through our payments system. The actual payment takes place on the expressPay payment page. But before a customer is redirected to that page to complete a payment, the merchant must authenticate (and authorize) the payment by using the endpoint shown in of STEP 1. The token from that response (from the endpoint) is then used in STEP 2 to redirect the user to the expressPay payment page.
Step 1
Merchant initiates HTTP POST request to expressPay Submit API with the appropriate request parameters:
PARAMETERS
HTTP POST “body” Content-type: application/x-www-formurlencoded
Request Parameters
Description
merchant-id
STRING
max-length: 256
Id assigned to merchant by expressPay
api-key
STRING
max-length: 256
Security api-key to authenticate request
firstname
STRING
max-length: 32
Customer first name
lastname
STRING
max-length: 64
Customer last name
STRING
max-length: 64
Customer email. This email MUST be unique for each of the merchant’s customers.
phonenumber
STRING
max-length: 64
Customer phone number
username
STRING
max-length: 64
Customer user name
accountnumber
STRING
max-length: 3
Customer account number
currency
STRING
max-length: 64
Transaction currency. (eg. GHS)
amount
STRING
max-length: 64
Total amount to be charged (e.g. 20.99)
order-id
STRING
max-length: 64
Merchant defined order id.
order-desc
STRING
max-length: 256
Order description
order-img-url
STRING
max-length: 256
Order image url
redirect-url
STRING
max-length: 256
A secure URL (https) on merchant's server that expressPay will redirect customer to after payment is complete. The redirection is handled via the user’s browser
post-url
STRING
max-length: 256
A secure URL (https) on merchant's server for posting the final transaction status of a pending payment. The post-url is required for mobile-money acceptance as payments may be completed anytime from a few seconds to several minutes after the payment is initiated. When the post-url is invoked (see STEP 4b for request format), the merchant is required to do a Query (see STEP 4a for Query request/response format) to check the transaction status, update their local state, and return immediately with HTTP Status 200 (OK).
Required
Optional
Required for mobile-money acceptance
Response Parameters (JSON Encoded)
Description
status
INT
- 1 = Success
- 2 = Invalid Credentials
- 3 = Invalid Request
- 4 = Invalid IP
order-id
STRING
max-length: 256
Merchant defined order-id
token
STRING
max-length: 1024
Unique token assigned for this transaction (if status is 1)
SAMPLE
1curl --location --request POST 'https://sandbox.expresspaygh.com/api/submit.php' \
2 --header 'Content-Type: application/x-www-form-urlencoded' \
3 --header 'Cookie: PHPSESSID=cfhb052j7h83mmlf8jrq92gu3r' \
4 --data-urlencode 'merchant-id=your-merchant-id' \
5 --data-urlencode 'api-key=your-api-key' \
6 --data-urlencode 'firstname=long' \
7 --data-urlencode 'lastname=pass' \
8 --data-urlencode 'email=longpass2020@gmail.com' \
9 --data-urlencode 'phonenumber=0244444444' \
10 --data-urlencode 'username=longpass2020@gmail.com' \
11 --data-urlencode 'accountnumber=36' \
12 --data-urlencode 'currency=GHS' \
13 --data-urlencode 'amount=33.00' \
14 --data-urlencode 'order-id=90bffe561179ed97' \
15 --data-urlencode 'redirect-url=https://google.com'
Response
1{
2 "status": 1,
3 "order-id": "90bffe561179ed97",
4 "guest-checkout": "TRUE",
5 "merchantservice-title": "nn_ventures",
6 "merchantservice-srvrtid": "906962986353",
7 "message": "Success",
8 "token": "316152c48865d04e73.2568619f619f52c4d04ec2.177113153192653f52c4d0",
9 "redirect-url": "https://google.com",
10 "user-key": null,
11 "merchant-title": "NN VENTURES",
12 "merchant-mcc": "5411",
13 "merchant-city": "Accra",
14 "merchant-countrycode": "GH"
15}
Step 2
If STATUS of STEP 1 is a SUCCESS(1), merchant extracts token from response of STEP 1 and redirects customer to the expressPay checkout API
PARAMETERS
HTTP POST “body” Content-type: application/x-www-formurlencoded
Request Parameters
Description
token
STRING
max-length: 1024
Unique token for this transaction
For Redirect Cases Only
https://sandbox.expresspaygh.com/api/checkout.php?token=xxxxx
Step 3
On transaction complete, expressPay will redirect customer to the redirect-url provided by merchant in STEP 1 with the following request parameters.
PARAMETERS
Request Parameters
Description
order-id
STRING
max-length: 256
Merchant defined order-id
token
STRING
max-length: 1024
Unique token-id for this transaction
Example
https://redirect-url?order-id=xxxx&token=xxxxx
Step 4 (A)
Merchant initiates HTTP POST request to expressPay Query API to check status of a transaction. If “payment-tokenize” (checkout the tokenization api for more info) is requested in STEP 1, a tokenized card is returned in the response if transaction is approved.
PARAMETERS
HTTP POST “body” Content-type: application/x-www-formurlencoded
Request Parameters
Description
merchant-id
STRING
max-length: 256
Id assigned to merchant by expressPay
api-key
STRING
max-length: 256
Security api-key to authenticate request
token
STRING
max-length: 1024
Unique token for this transaction
Required
Response Parameters (JSON Encoded)
Description
result
INT
- 1 = Approved
- 2 = Declined
- 3 = Error in transaction data or system error
- 4 = Pending (Final status will be provided via post-url)
result-text
STRING
max-length: 256
Textual response
order-id
STRING
max-length: 64
Merchant defined order-id
token
STRING
max-length: 64
Unique token for this transaction
transaction_id
STRING
max-length: 64
Processing transaction id
currency
STRING
max-length: 64
Transaction currency
amount
STRING
max-length: 64
Total amount charged
date-processed
STRING
max-length: 64
Date Processed
SAMPLE
1curl --location --request POST 'https://sandbox.expresspaygh.com/api/query.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'merchant-id=your-merchant-id' \
5--data-urlencode 'api-key=your-api-key' \
6--data-urlencode 'token=904561a4bfe1bf8034.6464429061a4bfe1bf8098.60770438812561a4bfe1bf'
Response
1{
2 "result": 1,
3 "result-text": "Approved",
4 "order-id": "49039ruuir",
5 "token": "316152c48865d04e73.2568619f619f52c4d04ec2.177113153192653f52c4d0",
6 "transaction-id": "906962986353",
7 "currency": "GHS",
8 "amount": 25,
9 "date-processed": "31st January, 1995"
10}
Step 4 (B)
If the result in STEP 4a is 4 (i.e. Pending) expressPay will invoke the post-url at a future undetermined time when user completes payment. Note that invoking the posturl does not necessarily imply success and the merchant is required to do a Query (see STEP 4a for Query request/response format) to check the transaction status, update their local state, and return immediately with HTTP Status 200 (OK)
PARAMETERS
Request Parameters
Description
order-id
STRING
max-length: 256
Merchant defined order-id
token
STRING
max-length: 64
Unique token for this transaction