ACCEPTING PAYMENTS

Merchant API Direct

Merchants can use this API to accept payments from customers without using the expressPay payment page. The actual payment is handled by the merchant on site. A merchant must be PCI (and DSS) compliant in order to process payments.

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/direct/submit.php

Copied to Clipboard

Submit API URLlive

https://expresspaygh.com/api/direct/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

currency

STRING

max-length: 64

Transaction currency. (eg. GHS)

amount

STRING

max-length: 64

Total amount to be charged (eg. 20.99)

order-id

STRING

max-length: 64

Merchant defined order Id

post-url

STRING

max-length: 64

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 3 for request format), the merchant is required to do a Query (see STEP 4 for Query request/response format) to check the transaction status, update their local state, and return immediately with HTTP STATUS 200 (OK)

Required

Response Parameters (JSON Encoded)

Description

status

INT

  • 1 = Success
  • 2 = Invalid Credentials
  • 3 = Invalid Request
  • 4 = Invalid IP

order-id

STRING

Merchant defined order-id

token

STRING

max-length: 256

Echoed from request

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=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'merchant-id=your-merchant-id' \
5--data-urlencode 'api-key=your-api-key' \
6--data-urlencode 'currency=GHS' \
7--data-urlencode 'amount=33.00' \
8--data-urlencode 'order-id=90bffe561179ed97' \
9--data-urlencode 'post-url=https://google.com'

Response

1{
2	"status": 1,
3	"order-id": "90bffe561179ed97",
4	"token": "787461ded46931a485.1096669161ded46931a5f8.35327262396661ded46931"
5}

Step 2

If status of STEP 1 is a SUCCESS, merchant must directly POST to the checkout url. Information about the funding source for payment must also be provided; for mobile money, mobile-number and corresponding mobile network to be charged, and for a card transaction, the card information is filled in instead.

If the result in response is 4 (i.e. PENDING) expressPay will invoke the post-url at a future undetermined time (see STEP 1) when user completes payment – this is only applicable to mobile money transactions. Card transactions will return the final transaction status. Note that invoking the post-url does not necessarily imply success and the merchant is required to do a Query (see STEP 4 for Query request/response format) to check the transaction status, update their local state, and return immediately with HTTP STATUS 200 (OK).

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

Unique token for this transaction from STEP 1

card-number

STRING

max-length: 256

Card number [Not required for Mobile Money]

card-holder-name

STRING

max-length: 256

Card holder name [Not required for Mobile Money] Format: FirstName LastName

card-expiry

STRING

max-length: 64

Card expiration date [Not required for Mobile Money] Format: MMYY

card-cvv

STRING

max-length: 64

Card security code [Not required for Mobile Money]

card-address

STRING

max-length: 64

Card billing address [Not required for Mobile Money]

card-city

STRING

max-length: 64

Card billing city [Not required for Mobile Money]

card-state

STRING

max-length: 3

Card billing state [Not required for Mobile Money]

card-zipcode

STRING

max-length: 64

Card billing zip code [Not required for Mobile Money]

card-country

STRING

max-length: 64

Card billing country [Not required for Mobile Money]

mobile-number

STRING

max-length: 15

Mobile number to be charged for this transaction [Not required for Card Transaction] Format: 233 XX YYY ZZZZ

mobile-network

STRING

max-length: 15

mobile-number network. set value to one of supported Values below. [Not required for Card Transaction]

Values: “MTN_MM”, “AIRTEL_MM”, “TIGO_CASH”,“VODAFONE_CASH”

mobile-auth-network

STRING

max-length: 15

Payment authorization token. Some mobile money networks require a pre-auth token eg. VODAFONE_CASH [Not required for Card Transaction]

Required

Card Transaction (Card billing address fields optional)

Required for mobile-money acceptance

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

pmt-info

STRING

max-length: 64

  • bin => Issuer bin
  • type => Payment Type
  • name => Issuer Name
  • country => Issuer

Country Example format in JSON:

{
  "bin": "1234",
  "type": "Visa Debit",
  "name": "Ecobank",
  "country": "Ghana"
}

Card Payment only

SAMPLE CARD

1curl --location --request POST 'https://sandbox.expresspaygh.com/api/submit.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'token= 904561a4bfe1bf8034.6464429061a4bfe1bf8098.60770438812561a4bfe1bf' \
5--data-urlencode 'card-number= XXXX XXXX XXXX' \
6--data-urlencode 'card-holder-name= John Kweku Smith' \
7--data-urlencode 'card-expiry= 28/10/22' \
8--data-urlencode 'card-cvv= 565' \
9--data-urlencode 'card-address= Really long address. P. O. Box' \
10--data-urlencode 'card-city= Accra' \
11--data-urlencode 'card-state= Greater Accra' \
12--data-urlencode 'card-zipcode= 0233' \
13--data-urlencode 'card-country= Ghana' \

Response

1{
2	"result": 3,
3	"result-text": "No transaction data available",
4	"order-id": "90bffe561179ed97",
5	"token": "974361defed73d3bc5.4966686961defed73d3c32.32994872485661defed73d",
6	"currency": "GHS",
7	"amount": "33.00",
8	"pmt-info": {
9		"bin": "233244",
10		"type": "mobile_money",
11		"name": "",
12		"country": ""
13	}
14}

SAMPLE MOMO

1curl --location --request POST 'https://sandbox.expresspaygh.com/api/submit.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=mmhsg9usr6ku84icj33lmt74oj' \
4--data-urlencode 'token= 904561a4bfe1bf8034.6464429061a4bfe1bf8098.60770438812561a4bfe1bf' \
5--data-urlencode 'mobile-number= 0203040900' \
6--data-urlencode 'mobile-network= VODAFONE' \
7--data-urlencode 'mobile-auth-token= r90e099r90009res.9e9e09re9u333e.3383hr83rhfd'

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 3

If the result in STEP 2 is 4 (i.e. PENDING) expressPay will invoke the post-url at a future undetermined time when user completes payment with following request parameters. Note that invoking the post-url does not necessarily imply SUCCESS and the merchant is required to do a QUERY (see STEP 4 for Query request/response format) to check the transaction status, update their local state, and return immediately with HTTP STATUS 200 (OK)

PARAMETERS

HTTP POST “body” Content-type: application/xwww-form-urlencoded

Request Parameters

Description

order-id

STRING

max-length: 256

Merchant defined order-id

token

STRING

max-length: 256

Unique token-id for this transaction

Step 4

Merchant initiates HTTP POST request to expressPay Query API to check status of a transaction.

Copied to Clipboard

Submit API URLsandbox

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

Copied to Clipboard

Submit API URLlive

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

PARAMETERS

HTTP POST “body”

Request Parameters

Description

merchant-id

STRING

max-length: 256

Merchant id assigned by expressPay

token

STRING

max-length: 256

Unique token-id for this transaction

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

Unique token for this transaction

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

Date processed

Response

1{
2	"result": 1,
3	"result-text": "Success",
4	"order-id": "2c7bb737-fda8-4f4f-ae9d-b406f17ae48f",
5	"token": "231562067e19a53358.8433682562067e19a53485.04579040878362067e19a5",
6	"currency": "GHS",
7	"amount": "33.00",
8	"auth-code": "66978189xc01c",
9	"transaction-id": "50d63406udd14",
10	"date-processed": "2022-02-11 15:27:21"
11}