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!