Search Documentation
Introduction
Accept Payments
Bill Payment Services
SDKs
Plugins
Testing
ACCEPTING PAYMENTS
Merchant API Tokenize
With this feature, merchants are able to tokenize payments. A token is generated and associated to a customer's payment on their first payment so that the token can be used to handle future payments of that customer. In effect, the generated token maps to that particular customer's payment. Therefore, the token can be used to authenticate (and authorize) these payments instead of the customer entering their payment details again.
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: 256
Customer account number at merchant
currency
STRING
max-length: 256
Transaction currency. (eg. GHS)
amount
STRING
max-length: 256
Total amount to be charged (eg. 20.99)
order-id
STRING
max-length: 15
Merchant defined order Id
order-desc
STRING
max-length: 15
Order description
order-img-desc
STRING
max-length: 15
URL to an image of order
payment-tokenize
STRING
max-length: 15
Tokenize user payment method. TRUE or FALSE
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: 64
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 (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)
guest-checkout
STRING
max-length: 256
merchant-city
STRING
max-length: 256
Merchant defined city
merchant-countrycode
STRING
max-length: 256
Merchant defined country code.
merchant-mcc
STRING
max-length: 6
Merchant mcc
merchant-service-name
STRING
max-length: 256
Merchant service short name.
merchantservice-srvtid
STRING
max-length: 256
Merchant srvrtid
message
STRING
max-length: 256
- 1 = Success
- 2 = Invalid API Credentials
- 3 = Invalid Request
- 4 = Invalid API Credentials
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
user-key
STRING
max-length: 256
Merchant API user key
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 'payment-tokenize=TRUE' \
14 --data-urlencode 'amount=33.00' \
15 --data-urlencode 'order-id=90bffe561179ed97' \
16 --data-urlencode 'redirect-url=https://google.com'Response
1{
2 "status": 1,
3 "order-id": "b57c01dd-8322-4b05-93fa-6ac4948d7fd4",
4 "guest-checkout": "TRUE",
5 "merchantservice-name": "nn_ventures",
6 "merchantservice-srvrtid": "906948373709",
7 "message": "Success",
8 "token": "996662068692c05931.4763323962068692c05981.12431661976162068692c0",
9 "redirect-url": "https://google.com",
10 "user-key": null,
11 "merchant-name": "NN VENTURES",
12 "merchant-mcc": "5411",
13 "merchant-city": "Accra",
14 "merchant-countrycode": "GH"
15}
Step 2
Skip to Step 2A if charging a tokenized card
If status of STEP 1 is SUCCESS, Merchant extracts token from response of STEP 1 and redirects customer to the expressPay checkout API. Continue to Step 3.
PARAMETERS
HTTP POST “body” Content-type: application/x-www-formurlencoded
Request Parameters
Description
token
STRING
max-length: 64
Unique token for this transaction
Example
https://sandbox.expresspaygh.com/api/checkout.php?token=xxxxx
Step 2 (A)
If status of STEP 1 is SUCCESS and merchant intends to charge a tokenized card, merchant must directly POST the token obtained from STEP 1 and the cctoken (for details on how to get cctoken, see STEP 4a) obtained from prior successful payment to the checkout url. If the result in response is 4 (i.e. PENDING) expressPay will invoke the post-url at a future undetermined time when user completes payment. Note that invoking the post-url 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
HTTP POST “body” Content-type: application/x-www-formurlencoded
Request Parameters
Description
token
STRING
max-length: 256
Unique token for this transaction
cctoken
STRING
max-length: 256
Card to be charged for this transaction
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
date-processed
STRING
max-length: 64
Date processed
auth-code
STRING
max-length: 64
Auth code
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 'token= your-api-key,' \
5--data-urlencode 'cctoken= e24re89fhuduhd-894urihe8uhf8ui9hh-N5Gz5p7mmj6mAP5pG2xn-WGaapXVU0JKQ1mRDUDJ'Response
1{
2 "result": 1,
3 "result-text": "Success",
4 "order-id": 12394,
5 "token": "316152c48865d04e73.2568619f619f52c4d04ec2.177113153192653f52c4d0",
6 "currency": "GHS",
7 "amount": 121,
8 "auth-code": "d6c40466x6add",
9 "transaction-id": "7b198d0euewre",
10 "date-processed": "12/8/2022"
11}
Step 3
On transaction complete, expressPay will redirect customer to the redirect-url provided by merchant in STEP 1 with the following request parameters. Proceed to STEP 4a
PARAMETERS
Request Parameters
Description
order-id
STRING
max-length: 256
Merchant defined order-id
token
STRING
max-length: 256
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 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: 32
Unique token for this transaction
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
auth-code
STRING
max-length: 256
The Auth code.
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
card = {cctoken, ccnumber, cctype, ccexp}
STRING
max-length: 64
user’s tokenized info used for this payment. Returned only if tokenization is requested and result is 1 i.e. Approved and user agrees to have their card saved
SAMPLE
1curl --location --request POST 'http://sandbox.expresspaygh.com/expresspay/api/query.php' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'Cookie: PHPSESSID=1c30d79ab3f854fe48e8995d1edfa4dd' \
4--data-urlencode 'merchant-id=your-merchant-id' \
5--data-urlencode 'api-key=your-api-key' \
6--data-urlencode 'token=4251620cd187566a62.40265206620cd187566aa8.503027653934620cd18756'Response
1{
2 "result": 1,
3 "result-text": "Success",
4 "order-id": 12394,
5 "token": "316152c48865d04e73.2568619f619f52c4d04ec2.177113153192653f52c4d0",
6 "currency": "GHS",
7 "amount": 121,
8 "date-processed": "12/8/2022",
9 "auth-code": "dfcec8ecx5b9a",
10 "card": [
11 {
12 "cctoken": "316152c48865d04e73.2568619sf619f52c4d04ec2.177113153192653f52c4d0",
13 "ccnumber": "XXX XXX XXX",
14 "type": "visa",
15 "ccexp": 923
16 }
17 ]
18}
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 200 (OK)
PARAMETERS
HTTP POST “body” Content-type: application/xwww-form-urlencoded
Request Parameters
Description
cctoken
STRING
max-length: 256
Card to be charged for this transaction
token
STRING
max-length: 256
Unique token for this transaction
Example
https://redirect-url?order-id=xxxx&token=xxxxx