Search Documentation
Introduction
Accept Payments
Bill Payment Services
SDKs
Plugins
Testing
Accepting Payments
Merchant Invoice API
This API enables merchants to collect payments via digital invoices. So invoices are created through which payments can be received. Invoices can be open or specific. If an invoice is open, the payers can pay any amount. But if it is specific, the payers are constrained to pay the amount specified. It is crucial to specify the account number at the time of invoice creation. This merchant supplied account number is associated with every payment the through the invoice. The account number could be a phone number or a bank account number depending on the destination of the payment.
Step 1
Merchant initiates HTTP POST expressPay Dynamic Invoice API with the appropriate request parameters:
Copied to Clipboard
https://sandbox.expresspaygh.com/api/dynamic-invoice-api.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
amount
STRING
max-length: 32
Total amount to be charged (eg. 20.99) If set, all invoices will have this as a fixed amount
accountnumber
STRING
max-length: 3
Payer’s account number. If set, this will appear as a read-only field on the invoice page
merchant-reference
STRING
max-length: 64
Merchant’s reference. If set, this will appear as a read-only field on the invoice page
description
STRING
max-length: 64
Invoice description
email-field
STRING
max-length: 64
Configuration for email field. Possible options are
-
OFF email field will not appear on invoice page
-
OPTIONAL email field will appear as an optional field
-
REQUIRED email field will be required on invoice page
account-number-field
STRING
max-length: 64
Configuration for account number field. Possible options are
-
OFF account reference field will not appear on invoice page
-
OPTIONAL account number field will appear as an optional field
-
REQUIRED account reference field will be required on invoice page
payer-reference-field
STRING
max-length: 15
Configuration for account number field. Possible options are
-
OFF Payer reference field will not appear on invoice page
-
OPTIONAL payer number field will appear as an optional field
-
REQUIRED payer reference field will be required on invoice page
valid-until
STRING
max-length: 15
Expiry date/time in the format YYYY-MM-DD HH:mm:ss (eg. 2021-03-06)
redirect-url
STRING
max-length: 15
A secure URL (https) on the merchant’s server that expressPay will redirect the customer to after payment is complete.
post-url
STRING
max-length: 256
A secure URL (https) on the 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 2 for request format), the merchant is required to do a Query (see STEP 3 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
url
INT
Invoice URL that can be shared to collect payment
SAMPLE
1curl --location --request POST 'http://sandbox.expresspaygh.com/expresspay/api/dynamic-invoice.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=1c30d79ab3f854fe48e8995d1edfa4dd' \
4--data-urlencode 'merchant-id=the-merchant-id' \
5--data-urlencode 'api-key=your-api-key' \
6--data-urlencode 'amount=33.00' \
7--data-urlencode 'accountnumber=0243123456' \
8--data-urlencode 'merchant-reference=Merchant Reference' \
9--data-urlencode 'description=This is the description' \
10--data-urlencode 'email-field=OPTIONAL' \
11--data-urlencode 'account-number-field=Account number Field' \
12--data-urlencode 'payer-reference-field=OPTIONAL' \
13--data-urlencode 'valid-until=14/09/2023' \
14--data-urlencode 'redirect-url=https://google.com' \
15--data-urlencode 'post-url=https://google.com'Response
1{
2 "status": 1,
3 "message": "Dynamic invoice successfully created",
4 "url": "http://sandbox.expresspaygh.com/inv/340"
5}
Step 2
On completion of any payment against the invoice, expressPay will invoke the post-url provided by the merchant in STEP 1 with the following request parameters. Note that invoking the post-url does not necessarily imply success; the merchant is required to do a Query (see STEP 3 for Query request/response format) to check the transaction status, update their local state, and return immediately with (OK).
PARAMETERS
Request Parameters
Description
token
STRING
max-length: 1024
Unique token for this transaction
dynamic-invoice-id
STRING
max-length: 256
ID of the invoice for which the payment was made
Step 3
Merchant initiates HTTP POST request to expressPay Query API to check status of a transaction.
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: 32
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
Order ID generated by the Dynamic Invoice API
auth-code
STRING
max-length: 64
Auth code
token
STRING
max-length: 64
Order ID generated by the Dynamic Invoice API
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
dynamic-invoice-id
STRING
max-length: 256
ID of the invoice for which the payment was made
first-name
STRING
max-length: 64
Customer first name
last-name
STRING
max-length: 64
Customer last name
phone-number
STRING
max-length: 64
Payer’s phone number
STRING
max-length: 64
Payer’s email
account-number
STRING
max-length: 64
Payer’s account number
payer-reference
STRING
max-length: 64
Payer's reference
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": "Success",
4 "order-id": "inv.5262621e2df549a018.75350242621e2",
5 "token": "5223621e2df54e4861.14091822621e2df54e48c1.522507882020621e2df54e",
6 "currency": "GHS",
7 "amount": "2000.00",
8 "dynamic-invoice-id": "356",
9 "first-name": "James",
10 "last-name": "Bond",
11 "email": "bond@mi6.co.uk",
12 "phone-number": "0240000059",
13 "account-number": "1234567890",
14 "payer-reference": "007",
15 "auth-code": "8cfsdsdxe2d2",
16 "transaction-id": "2fac9af4uecc0",
17 "date-processed": "2022-03-01 14:28:59"
18}