iQR - Acquiring APIs
This allows an entity (Acquirers - PTSP, Banks, Agent network) to initiate payments with an iQR.
How Receiving Payments with iQR works
- Customer present iQR to the Merchant/Agent
- Merchant/ Agent scans the customers iQR using their POS / Mobile app
- The POS/Mobile App backend make an API call (Request payment) to the iQR endpoint. This creates a payment
- The customer authorizes the transaction by dialing the _723_99# to authorize the transaction.
iQR Acquiring Api
Test Parameters
For Integration tests, use the following parameter for the test acquirer
aggregatorID:"MX164667"
cqrId: "230757021194666585"
mobileNumber: "2348069752675"
Request Payment
The request payment API allows you to request intiate a payment with an iQR.
Url
POST https://isw-psb-test-sc-cqr-transaction-service.azuremicroservices.io/api/v1/pay/request
Headers
An access token must be provided for all requests
Authorization <Bearer Token>
Request Body
Below is a sample request to request a payment with iQR
Sample Request Body
{
"aggregatorID": "MX164667",
"transactionRef": "pedo22",
"payment": {
"cqrId": "230757021194666585",
"amount": 10300,
"description":"test",
"transactionType":"PAYMENT",
"channel": "API",
"currencyCode": "566"
},
"payee": {
"payeeID" :"1324232323",
"firstName":"Test",
"lastName":"John",
"businessName":"John Co",
"businessAddress":"test business address"
},
"riskControlData": "test risk control data",
"ipAddress": "127.0.01",
"mobileNumber": "2349061443623"
}
Field descriptions
| Field | Description | Additional Information |
|---|---|---|
| aggregatorID | Your Merchant Code (MX***) | Mandatory |
| transactionRef | A unique reference no generated by your system. | Mandatory |
| qrId | The iQR id contained in the QR Code | Mandatory |
| amount | Amount to be debited. This is in minor demonination | Mandatory |
| description | Description of the payment | Mandatory |
| transactionType | Options are CASHOUT, PAYMENT, TRANSFER, PURCHASE | Mandatory |
| channel | API, WEB, USSD | Mandatory |
| currencyCode | 566 | Mandatory |
| payeeID | Agent or merchant ID | |
| firstName | Agent or merchant First name | Optional |
| lastName | Agent or merchant Last name | Optional |
| payeeID | Agent ID or Merchant ID | Optional |
| businessName | business name | Optional |
| businessAddress | address of the business | Optional |
| operatorId | ||
| longitude | longitude of current location | |
| latitude | latitude of current location | |
| ipAddress | current IP address |
Response Body
Below is a response sample for
Sample response body
{
"txId": "18",
"code": "00",
"message": "Successful",
"data": {
"transactionRef": "pedo22",
"paymentID": "18",
"status": "Successful",
"description": "Successful",
"payValidityMinutes": 5
},
"error": []
}
Response field description
| Field | Description |
|---|---|
| txId | This is a unique id generated by the iQR platform. This information needs to be stored to query transaction. |
| code | This is the response code of the payment request |
| message | A description of the code field |
| transactionRef | This is the transaction reference you passed in the request body |
| paymentID | This is a unique id generated by the iQR platform. This information needs to be stored to query transaction. Same as txId. |
| status | A description of the code field |
| description | A description of the code field |
| payValidityMinutes | The time for how long the payment is valid, the user needs to |
| error | Any error msg |
Response Code
| 00 | Successful |
|---|---|
| 01 | Payment is pending |
| 02 | Payment was rejected |
| 03 | Payment was cancelled |
| 04 | Payment timed out |
| 05 | No record was found |
| 06 | Invalid data supplied e.g iQR - Invalid IQR |
| 07 | Already exist |
| 91 | We were unable to establish connection with the required service |
| 92 | Request processing date has expired |
Query Payment
This allow you to query the status of a iQR payment you requested initially.
An access token must be provided for all requests
Url
GET https://isw-psb-test-sc-cqr-transaction-service.azuremicroservices.io/api/v1/pay/query?paymentId=1
Headers
Authorization <Bearer Token>
Response Body
{
"cqrId": "260174378964208605",
"aggregatorId": "MX*****",
"customerId": "2348154249743",
"transactionReference": "15574f60-d62a-4019-9262-5fb0ae4bd358",
"consumerMobile": "2348154249743",
"currencyCode": "566",
"amount": 20000,
"channel": "WEB",
"paymentType": "CASHOUT",
"description": "try again",
"paymentStatus": "EXPIRED",
"createdBy": "MX164667",
"id": 1,
"responseCode": "92",
"responseMessage": "Request processing date has expired",
"createdOn": "2023-11-08T10:21:57",
"updatedOn": "2023-11-08T10:45:23"
}
Field description
| Possible | |
|---|---|
| Payment status | PENDING, REJECT, CANCEL, TIMEOUT, AUTHORIZE, COMPLETED, EXPIRED |
| responseCode | See below for response descriptions |
| responseMessage | The actual description for the failure |
Response Code
| Response Code | Description |
|---|---|
| 00 | Successful |
| 01 | Payment is pending |
| 02 | Payment was rejected |
| 03 | Payment was cancelled |
| 04 | Payment timed out |
| 05 | No record was found |
| 06 | Invalid data supplied e.g iQR - Invalid IQR |
| 07 | Already exist |
| 91 | We were unable to establish connection with the required service |
| 92 | Request processing date has expired |
| 99 | We are unable to process your request! |
Updated 4 months ago