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:

Copied to Clipboard

Submit API URLsandbox

https://sandbox.expresspaygh.com/api/submit.php

Copied to Clipboard

Submit API URLlive

https://expresspaygh.com/api/submit.php

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

email

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

Copied to Clipboard

Submit API URLsandbox

https://sandbox.expresspaygh.com/api/checkout.php

Copied to Clipboard

Submit API URLlive

https://expresspaygh.com/api/checkout.php

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.

Copied to Clipboard

QUERY API URLsandbox

https://sandbox.expresspaygh.com/api/query.php

Copied to Clipboard

QUERY API URLlive

https://expresspaygh.com/api/query.php

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