دليل ربط «اشترِ الآن وادفع لاحقاً»
دليل خطوة بخطوة لإضافة أقساط تطبيق كيو إلى صفحة الدفع في متجرك.
هذا الدليل التقني متوفر باللغة الإنجليزية فقط.
Contents
How it works
Buy Now, Pay Later (BNPL) is short-term financing that lets customers make a purchase now and pay for it later, interest-free. You add QPay as a payment method at checkout, and your platform calls five QPay APIs.
- 1List of PlansThe customer chooses QPay at checkout. You show the installment plans.
- 2Generate OTPThe customer picks a plan. QPay sends them a one-time password (OTP).
- 3List of CardsThe customer enters the OTP. You show their cards.
- 4Confirm PlanThe customer picks a card and confirms. QPay creates the loan and charges the card.
Steps 1 to 4 run during checkout, in this order. Customers must already be registered with QPay.
How to use this guide. Read it from top to bottom. Set up once, learn the rules every call follows, then build the four checkout steps. Each step shows the request, the response, and what to keep for the next step.
Before you start
Do these once, before you write any code.
Get these from QPay
- Merchant ID. Send it in the
x-Merchant-IDheader on every call. QPay uses it to find your certificate. - Merchant service ID. Send it as
merchantIdon List of Plans and Confirm Plan, and as the sender on Refund. - A test customer. A mobile number registered with QPay, to test with in UAT. You can also send QPay a mobile number of your own, and QPay adds it for testing.
Create your key and certificate
Create an RSA key pair on the server that will sign your requests. You send QPay the certificate only.
- Key: RSA, 2048 bits or more.
- Certificate: SHA-256, valid for 2 years, with the country, organization and common name filled in.
# 1. Private key: RSA, 2048 bits. Keep this file on your server and never share it.
openssl genrsa -out private.key 2048
# 2. Certificate signing request. OpenSSL asks for your details. Fill in at least
# Country Name, Organization Name and Common Name. Type . to leave a field empty.
openssl req -new -key private.key -out request.csr
# 3. Certificate, valid for 2 years. Send certificate.pem to QPay.
openssl x509 -req -in request.csr -signkey private.key -out certificate.pem -days 730 -sha256
Send QPay certificate.pem. QPay registers it for UAT and production. Never send private.key, and keep it out of source control.
Using Java, or a key in the older format?
The Java sample reads a PKCS#12 keystore. Create it from the same key and certificate:
# Java only: put the key and certificate in the keystore the Java sample reads.
# Enter a password when asked. Pass it as keyStorePassword, and "merchant" as certificateAlias.
openssl pkcs12 -export -inkey private.key -in certificate.pem -name merchant -out keystore.p12
OpenSSL 3 writes the private key in PKCS#8 format, which starts with -----BEGIN PRIVATE KEY-----. The Node.js, Python and Postman samples read it as it is. If your key starts with -----BEGIN RSA PRIVATE KEY-----, convert it:
# Only if private.key starts with -----BEGIN RSA PRIVATE KEY-----
openssl pkcs8 -topk8 -nocrypt -in private.key -out private-pkcs8.key
UAT and production
Build and test your integration here, with the test credentials QPay gives you.
https://bnpl-api.fintec.solutions Download the Postman collection98 KBReal customers and real card payments. Move here when your UAT tests pass and QPay has issued your production credentials.
https://bnpl-api-prod.fintec.solutions Download the Postman collection33 KBBoth environments use the same API paths and the same signing rules. QPay registers your certificate in each one, and issues separate credentials for production. Each Postman collection holds all five requests and signs them for you. See Test in UAT.
How every call works
All five APIs follow the same rules, so you build this part once.
Send a POST request
- Send a
POSTrequest with a JSON body to the host plus the API path. All five paths start with/bnpl/mw. - Allow at least 60 seconds before your HTTP client times out. Confirm Plan runs several checks and a card payment in one call.
- Stay under 30 requests a minute.
Headers
| Header | Requirement | Description |
|---|---|---|
| token | Required | Base64 signature of the request body, made with your private key. See Sign the body. |
| x-Merchant-ID | Required | Your merchant ID. QPay uses it to find the certificate that checks token. |
| Content-Type | Required | application/json |
| Accept | Recommended | application/json |
# body.json must hold the exact bytes you signed.
curl -X POST "https://bnpl-api.fintec.solutions/bnpl/mw/list-plans" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "x-Merchant-ID: {your-merchant-id}" \
-H "token: {base64-signature-of-body}" \
--data-binary @body.json
Sender details
Every request body starts with senderInfo, which says who is making the call.
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo. | integer | Required | Language ID. 1 for English, 3 for Arabic. QPay returns desc in this language. |
| senderInfo. | string | Required | On the four checkout calls: the customer’s mobile number registered with QPay, for example 0096812345678. On Refund: your merchant service ID. |
| senderInfo. | string | Required | M for a customer mobile, on the four checkout calls. C for a merchant service, on Refund only. |
| senderInfo. | string | Required | Unique ID for this call. Generate a new value every time. Reusing one can return reason 46 (Duplicate message ID). |
| senderInfo. | string | Recommended | ID of the device that sent the request. QPay stores it with the transaction, so you can see which device made a call when you debug it. |
| senderInfo. | string | Required on 2 APIs | Hashed OTP. Mandatory on List of Cards and Confirm Plan. Leave it out on the other calls. See Hash the OTP. |
Sign the body
QPay checks a signature on every request, so sign the exact body you send.
- Build the JSON body once, as a string.
- Sign the UTF-8 bytes of that string with your private key, using
SHA256withRSA(RSA PKCS #1 v1.5 with SHA-256). - Encode the signature in Base64, and send it in the
tokenheader. - Send that same string as the body. If anything changes after signing, even spacing or key order, QPay returns reason 49 (Invalid signature).
Sign
import java.io.InputStream;
import java.nio.charset.Charset;
import java.security.Key;
import java.security.KeyStore;
import java.security.PublicKey;
import java.security.Signature;
import java.security.cert.X509Certificate;
import java.security.interfaces.RSAPrivateKey;
import java.util.Base64;
public class Security {
public boolean verifySign(String signature, String value, String algorithm, String encoding,
String keyStorePassword, String certificateAlias) throws Exception {
X509Certificate cert = loadCertificate(keyStorePassword, certificateAlias);
PublicKey publicKey = cert.getPublicKey();
Signature sig = Signature.getInstance(algorithm);
sig.initVerify(publicKey);
sig.update(value.getBytes(Charset.forName(encoding)));
return sig.verify(Base64.getDecoder().decode(signature));
}
public String sign(String value, String algorithm, String encoding,
String keyStorePassword, String certificateAlias) throws Exception {
RSAPrivateKey privateKey = (RSAPrivateKey) loadPrivateKey(keyStorePassword, certificateAlias);
Signature sig = Signature.getInstance(algorithm);
sig.initSign(privateKey);
sig.update(value.getBytes(Charset.forName(encoding)));
return Base64.getEncoder().encodeToString(sig.sign());
}
private X509Certificate loadCertificate(String keyStorePassword, String certificateAlias) throws Exception {
return (X509Certificate) loadKeyStore(keyStorePassword).getCertificate(certificateAlias);
}
private Key loadPrivateKey(String keyStorePassword, String certificateAlias) throws Exception {
return loadKeyStore(keyStorePassword).getKey(certificateAlias, keyStorePassword.toCharArray());
}
private KeyStore loadKeyStore(String keyStorePassword) throws Exception {
ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
try (InputStream stream = classLoader.getResourceAsStream("keystore.p12")) {
KeyStore keystore = KeyStore.getInstance("PKCS12");
keystore.load(stream, keyStorePassword.toCharArray());
return keystore;
}
}
}
const crypto = require('crypto');
// rawBody is the exact JSON string you will send.
function sign(rawBody, privateKeyPem) {
return crypto
.sign('RSA-SHA256', Buffer.from(rawBody, 'utf8'), privateKeyPem)
.toString('base64');
}
function verifySign(rawBody, signature, publicKeyPem) {
return crypto.verify(
'RSA-SHA256',
Buffer.from(rawBody, 'utf8'),
publicKeyPem,
Buffer.from(signature, 'base64'),
);
}
module.exports = { sign, verifySign };
import base64
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
# raw_body is the exact JSON string you will send.
def sign(raw_body, private_key_pem):
key = serialization.load_pem_private_key(private_key_pem, password=None)
signature = key.sign(raw_body.encode("utf-8"), padding.PKCS1v15(), hashes.SHA256())
return base64.b64encode(signature).decode("ascii")
def verify_sign(raw_body, signature, public_key_pem):
key = serialization.load_pem_public_key(public_key_pem)
try:
key.verify(
base64.b64decode(signature),
raw_body.encode("utf-8"),
padding.PKCS1v15(),
hashes.SHA256(),
)
return True
except InvalidSignature:
return False
In Java, call sign with SHA256withRSA and UTF-8, and your own keystore password and alias. To create keystore.p12, see Create your key and certificate.
Send
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendRequest {
public static String send(String baseUrl, String path, String rawBody, String merchantId,
String keyStorePassword, String certificateAlias) throws Exception {
String token = new Security().sign(rawBody, "SHA256withRSA", "UTF-8",
keyStorePassword, certificateAlias);
HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + path))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("x-Merchant-ID", merchantId)
.header("token", token)
.POST(HttpRequest.BodyPublishers.ofString(rawBody))
.build();
return HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString())
.body();
}
}
const { sign } = require('./sign');
// Build the body once, sign that string, and send that same string.
async function send(baseUrl, path, payload, merchantId, privateKeyPem) {
const rawBody = JSON.stringify(payload);
const response = await fetch(baseUrl + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'x-Merchant-ID': merchantId,
token: sign(rawBody, privateKeyPem),
},
body: rawBody,
});
return response.json();
}
module.exports = { send };
import json
import urllib.request
from sign import sign
# Build the body once, sign that string, and send that same string.
def send(base_url, path, payload, merchant_id, private_key_pem):
raw_body = json.dumps(payload, separators=(",", ":"))
request = urllib.request.Request(
base_url + path,
data=raw_body.encode("utf-8"),
method="POST",
headers={
"Content-Type": "application/json",
"Accept": "application/json",
"x-Merchant-ID": merchant_id,
"token": sign(raw_body, private_key_pem),
},
)
with urllib.request.urlopen(request) as response:
return json.load(response)
QPay signs its responses too, in the token response header. To check one, verify the raw response body with QPay’s certificate in the same way.
Check a signature on your own machine
Sign a body with OpenSSL and compare the result with your code. The same body and the same key always give the same signature, so the two token values must match. If QPay returns reason 49 and the values differ, your code is signing different bytes from the ones it sends, or using another key.
# 1. Save the exact body you send, with no line break at the end.
printf '%s' '{"senderInfo":{"lang":1,"sender":"0096812345678","senderType":"M","msgId":"b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1001","deviceId":"web-checkout-01"},"amount":"25.500","merchantId":"MERCHANT01"}' > body.json
# 2. Sign it. The line printed is the value for the token header.
openssl dgst -sha256 -sign private.key -out body.sig body.json
openssl base64 -A -in body.sig; echo
# 3. Check it with your certificate. Expect "Verified OK".
openssl x509 -in certificate.pem -pubkey -noout > public.pem
openssl dgst -sha256 -verify public.pem -signature body.sig body.json
The commands run in a Linux or macOS terminal, or in a Bash shell on Windows.
Never paste your private key into a website or online tool to test a signature. Anyone who has the key can sign requests as you.
Read the response
Every result comes back with HTTP 200, failures included. Read responseInfo before any other field.
| Field | Type | Description |
|---|---|---|
| responseInfo. | string | The result code. 00 means success. Any other value is a reason ID from Error codes, for example 89 for Invalid OTP. |
| responseInfo. | string | Description of the result, in the language set by senderInfo.lang. Success on success. |
| responseInfo. | string | What happened. See the table below. |
| responseInfo. | string | Loan ID. Set by Confirm Plan, and returned again on Refund results. null on the other APIs. |
| responseInfo. | array of string | Extra detail for reason 70, when the loan service gives it. Usually null. |
What to do with each status
| statusCode | Meaning | What to do |
|---|---|---|
| 1 Success | Success | Continue. On Confirm Plan, complete the order. |
| 3 Rejected | Rejected | Stop, and show the customer the reason from desc. Validation errors also return 3. |
| 4 Pending | Pending | Refund only. The refund is not final, so do not send it again. Ask QPay for the final result. |
| 5 Failed | Failed | Confirm Plan only. The card payment did not go through, so do not complete the order. |
A failed call looks like this:
{
"responseInfo": {
"errorCd": "49",
"desc": "Invalid Credentials",
"statusCode": "3",
"loanId": null,
"failureReasons": null
}
}
Here desc says Invalid Credentials, and the reason is 49 (Invalid signature). QPay manages the desc texts, and they follow the language you send, so compare on errorCd. Every reason ID is in Error codes.
HTTP 400 with no responseInfo body means the request format is wrong: a required field is missing, a JSON type is wrong, or senderType is not M or C. Fix the request before you try again.
Responses can contain other fields that are empty. Ignore any field this guide does not list.
List of Plans
Returns the installment plans available for a purchase amount and a merchant. Call this when the customer chooses QPay at checkout.
- Sender
- Customer mobile
- Sender type
M- OTP
- Not used
Request
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo | object | Required | The customer’s mobile number, with senderType M. See Sender details. |
| amount | string | Required | Purchase amount as a decimal string, for example 25.500. |
| merchantId | string | Required | Your merchant service ID, issued by QPay. |
{
"senderInfo": {
"lang": 1,
"sender": "0096812345678",
"senderType": "M",
"msgId": "b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1001",
"deviceId": "web-checkout-01"
},
"amount": "1.000",
"merchantId": "MERCHANT01"
}
Response
| Field | Type | Description |
|---|---|---|
| principalId | integer | Plan principal ID. Send this value as planInfo.principleId on Confirm Plan. It can be negative, so store it as a signed integer and send it back unchanged. |
| plans[] | array | Installment options. When none are available, QPay returns reason 319 (No plans available) and plans is null, so check statusCode before you read it. |
| plans[]. | string | Name of the installment option. |
| plans[]. | string | Description of the installment option. Can be null. |
| plans[]. | array of string | Penalty texts. Currently always ["No Penalties"]. |
| plans[]. | integer | Number of installments. |
| plans[]. | string | Plan type name. |
| plans[]. | integer | Installment plan ID. Send this value as planInfo.planId on Confirm Plan. |
| plans[]. | array | Installment schedule. |
| plans[]. | string | Due date, as yyyy-MM-dd. |
| plans[]. | number | Installment amount. |
| plans[]. | integer | Installment number in the schedule. |
| plans[]. | number | Remaining loan balance after this installment. |
{
"responseInfo": {
"errorCd": "00",
"desc": "Success",
"statusCode": "1",
"loanId": null,
"failureReasons": null
},
"plans": [
{
"name": "QPAY BNPL",
"description": null,
"penalties": [
"No Penalties"
],
"numberOfRepayments": 4,
"type": "MONTHLY",
"id": 1,
"installments": [
{
"dueDate": "2026-06-23",
"amount": 0.25,
"period": 1,
"loanBalanceAfterPayment": 0.75
},
{
"dueDate": "2026-07-23",
"amount": 0.25,
"period": 2,
"loanBalanceAfterPayment": 0.5
},
{
"dueDate": "2026-08-23",
"amount": 0.25,
"period": 3,
"loanBalanceAfterPayment": 0.25
},
{
"dueDate": "2026-09-23",
"amount": 0.25,
"period": 4,
"loanBalanceAfterPayment": 0
}
]
}
],
"principalId": -208453800
}
Keep for later. Keep principalId, and the id of the plan the customer picks. You send both on Confirm Plan.
Results to handle
- 3 Rejected319No plans available.
plansandprincipalIdarenull. - 3 Rejected241Invalid merchant service ID.
merchantIddoes not match a merchant service. - 3 Rejected49Invalid signature. The
tokenheader does not match the body.
Every result this call can return is in Error codes.
Generate OTP
Creates a one-time password and sends it to the customer’s mobile number by notification. Call this after the customer selects a plan.
- Sender
- Customer mobile
- Sender type
M- OTP
- Sends the OTP
- The sender is always the customer, because the customer receives the OTP. Send the customer’s mobile number in
senderwithsenderTypeM. - The OTP is never returned in the response. Show a screen where the customer enters it, then hash it for List of Cards and Confirm Plan.
- Calling this API resets the OTP retry count for the mobile number.
Request
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo | object | Required | The customer’s mobile number, with senderType M. QPay sends the OTP to this number. See Sender details. |
| storeInformation | object | Recommended | Details of your store. Send the object with a name, or leave it out. Do not send it as null. |
| storeInformation. | string | Recommended | Your store name. QPay includes it in the OTP message the customer receives. |
{
"senderInfo": {
"lang": 1,
"sender": "0096812345678",
"senderType": "M",
"msgId": "b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1002",
"deviceId": "web-checkout-01"
},
"storeInformation": {
"name": "Your Store"
}
}
Response
The response has responseInfo only. See Read the response.
{
"responseInfo": {
"errorCd": "00",
"desc": "Success",
"statusCode": "1",
"loanId": null,
"failureReasons": null
}
}
Results to handle
- 3 Rejected4Mobile not registered. The mobile number is not registered with QPay.
- 3 Rejected46Duplicate message ID.
msgIdwas already used.
Every result this call can return is in Error codes.
List of Cards
Returns the cards registered on the customer’s mobile number. QPay checks the hashed OTP before it returns any cards. Call this after the customer enters the OTP.
- Sender
- Customer mobile
- Sender type
M- OTP
- Mandatory
Before you call: hash the OTP
Hash the OTP the customer typed, and send the hash in senderInfo.otp. The OTP is mandatory on List of Cards and Confirm Plan, and you send the same hash on both.
- Take the OTP exactly as the customer typed it, as UTF-8 text.
- Hash it with SHA-256, and encode the hash bytes in Base64.
- Check your code:
123456must givejZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI=.
import java.nio.charset.Charset;
import java.security.MessageDigest;
import java.util.Base64;
public class OtpHash {
public static String hash(String value) throws Exception {
String encoding = "UTF-8";
String hashingAlgorithm = "SHA-256";
MessageDigest msgDig = MessageDigest.getInstance(hashingAlgorithm);
msgDig.reset();
msgDig.update(value.getBytes(Charset.forName(encoding)));
return new String(Base64.getEncoder().encode(msgDig.digest()));
}
}
const crypto = require('crypto');
function hashOtp(otp) {
return crypto.createHash('sha256').update(otp, 'utf8').digest('base64');
}
module.exports = { hashOtp };
import base64
import hashlib
def hash_otp(otp):
digest = hashlib.sha256(otp.encode("utf-8")).digest()
return base64.b64encode(digest).decode("ascii")
Check a hash from the command line
OpenSSL gives the same result as the code above:
# 123456 must print jZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI=
printf '%s' '123456' | openssl dgst -sha256 -binary | openssl base64 -A; echo
Never send the plain OTP. Do not add anything to the value, such as a customer ID, and do not hash it a second time.
OTP limits
- A wrong or empty OTP returns reason 89 (Invalid OTP). An expired one returns reason 88 (Expired OTP). Both count as a failed attempt.
- QPay sets how long an OTP stays valid and how many failed attempts are allowed. The attempt that reaches the limit still returns 89 or 88, and blocks the mobile number.
- After the block, List of Cards returns reason 72 (Customer mobile blocked), and Confirm Plan returns reason 207 (Maximum OTP attempts reached).
- Calling Generate OTP sends a new OTP and resets the attempt count.
This request has no merchantId and no amount.
Request
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo | object | Required | The customer’s mobile number, with senderType M, and the hashed OTP. See Sender details. |
| senderInfo. | string | Required | Hashed OTP. Mandatory on this API. See OTP hashing. An empty value returns reason 89 (Invalid OTP). |
{
"senderInfo": {
"lang": 1,
"sender": "0096812345678",
"senderType": "M",
"msgId": "b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1003",
"deviceId": "web-checkout-01",
"otp": "Base64Sha256OfTheOtp"
}
}
Response
| Field | Type | Description |
|---|---|---|
| cards[] | array | Cards on the customer’s mobile number. |
| cards[]. | string | Card account reference, such as BNPL001. Send this value unchanged as planInfo.account on Confirm Plan. |
| cards[]. | string | Card number, masked except for the last four digits, for example xxxx-xxxx-xxxx-1234. Always show it masked. |
| cards[]. | string | Card expiry date as MM/yyyy, for example 12/2030. Can be null. |
| cards[]. | string | Cardholder name. Can be null, so do not rely on it to identify the card. |
{
"responseInfo": {
"errorCd": "00",
"desc": "Success",
"statusCode": "1",
"loanId": null,
"failureReasons": null
},
"cards": [
{
"account": "BNPL002",
"cardNumber": "xxxx-xxxx-xxxx-8785",
"expiryDate": "12/2030",
"cardHolderName": null
},
{
"account": "BNPL001",
"cardNumber": "xxxx-xxxx-xxxx-1111",
"expiryDate": null,
"cardHolderName": null
}
]
}
Keep for later. Keep the hashed OTP, and the account of the card the customer picks. You send both on Confirm Plan.
Results to handle
- 3 Rejected89Invalid OTP. The OTP hash does not match. This counts as a failed attempt.
- 3 Rejected88Expired OTP. The OTP was right but has expired. Call Generate OTP again.
- 3 Rejected72Mobile blocked. Too many failed OTP attempts blocked the mobile number.
Every result this call can return is in Error codes.
Confirm Plan
Confirms the selected plan, creates the loan, and charges the selected card for the purchase amount. Call this when the customer confirms the plan and pays.
- Sender
- Customer mobile
- Sender type
M- OTP
- Mandatory
What this call does
- Credit checkQPay also verifies the hashed OTP here, then clears it. The OTP is not checked again in the later steps.
- Customer verificationQPay confirms the customer can go ahead with this purchase.
- Plan confirmation and card paymentQPay creates the loan and charges the selected card.
One call runs all three steps. Any of them can end the request, and you do not call them separately.
Request
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo | object | Required | The customer’s mobile number, with senderType M, and the hashed OTP. See Sender details. |
| senderInfo. | string | Required | Hashed OTP. Mandatory on this API. Send the same hash you sent to List of Cards. See OTP hashing. |
| planInfo | object | Required | The selected plan and card. |
| planInfo. | integer | Required | The id of the selected plan from List of Plans. |
| planInfo. | integer | Required | The principalId from List of Plans. Note the spelling: principleId in this request, principalId in the List of Plans response. |
| planInfo. | string | Required | Your merchant service ID. Use the same merchant as on List of Plans. |
| planInfo. | string | Required | The account of the selected card from List of Cards, unchanged. |
| amount | string | Required | Purchase amount as a decimal string, for example 25.500. This field sits beside planInfo, not inside it. |
{
"senderInfo": {
"lang": 1,
"sender": "0096812345678",
"senderType": "M",
"msgId": "b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1004",
"deviceId": "web-checkout-01",
"otp": "Base64Sha256OfTheOtp"
},
"planInfo": {
"planId": 1,
"principleId": -208453800,
"merchantId": "MERCHANT01",
"account": "BNPL002"
},
"amount": "1.000"
}
Response
| Field | Type | Description |
|---|---|---|
| responseInfo. | string | Loan ID, inside responseInfo. Set when the loan is created, and stays set if the card payment is then rejected or fails. Send this value as refundInfo.loanId. |
| transactionId | string | Card-payment transaction ID, set when the payment call returns a result. Used for status inquiries. |
| token | string | Saved card token, unrelated to the token request header. Set only when the payment is accepted. |
- Any
errorCdother than00is not a successful payment. - Some failed responses also return
planIdandprincipalIdbesideresponseInfo. You can ignore them.
{
"responseInfo": {
"errorCd": "00",
"desc": "Success",
"statusCode": "1",
"loanId": "100245",
"failureReasons": null
},
"transactionId": "tp-9f2c1",
"token": "saved-card-token"
}
Keep for later. Keep responseInfo.loanId from every response, even when the payment is rejected or fails, and keep transactionId when it is set. You send loanId unchanged on Refund.
Results to handle
- 3 Rejected59Rejected. The bank declined the card payment, for example for insufficient funds.
- 5 Failed36Failed. The card payment did not go through. Do not complete the order.
- 3 Rejected70Invalid plan.
planIdorprincipleIdis missing or invalid. - 3 Rejected89Invalid OTP. Nothing was charged. This counts as a failed OTP attempt.
- 3 Rejected2System error. Try again later with a new
msgId.
Every result this call can return is in Error codes.
Refund
Refunds an amount on an active loan for your merchant service. Call this after the sale, when you need to return money to the customer.
- Sender
- Your merchant service
- Sender type
C- OTP
- Not used
- No OTP is needed. The sender is your merchant service, not the customer.
- Partial refunds are allowed until the refunded total would exceed the original transaction amount.
- A refund is accepted only within the refund period after the original transaction, and only while the loan is active.
Request
| Field | Type | Requirement | Description |
|---|---|---|---|
| senderInfo | object | Required | Your merchant service ID, with senderType C. This is the service key issued by QPay, not a display name. No OTP. See Sender details. |
| refundInfo | object | Required | The loan and the amount to refund. |
| refundInfo. | string | Required | Loan ID from responseInfo.loanId on Confirm Plan, sent unchanged. |
| refundInfo. | string | Required | Refund amount as a decimal string, for example 0.500. |
{
"senderInfo": {
"lang": 1,
"sender": "MERCHANT01",
"senderType": "C",
"msgId": "b7c1e0a0-6c2a-4d1e-9f10-2a6c0e1b1005",
"deviceId": "web-checkout-01"
},
"refundInfo": {
"loanId": "100245",
"amount": "0.500"
}
}
Response
The response has responseInfo only. See Read the response.
- Refund results return the loan ID you sent in
responseInfo.loanId. - A gateway rejection and a gateway failure both return
statusCode4. UseerrorCdto tell them apart.
{
"responseInfo": {
"errorCd": "00",
"desc": "Success",
"statusCode": "1",
"loanId": "100245",
"failureReasons": null
}
}
Results to handle
- 4 Pending59 or 36Gateway rejected or failed. QPay records the refund as pending.
- 3 Rejected58Amount not allowed. The amount is more than what is left to refund.
- 3 Rejected201Already refunded. This transaction was already refunded.
- 3 Rejected34Transaction not found. Check
loanIdand the merchant service.
Every result this call can return is in Error codes.
Test and go live
Test in UAT
Run the whole journey in UAT before you go live. The quickest way is QPay’s Postman collection. It holds all five requests, signs each one and hashes the OTP for you. Download it from UAT and production.
- Import the collection into Postman with File, then Import.
- Open the collection’s Variables tab. Fill in your private key, merchant ID, merchant service ID, the customer’s mobile number, the amount, your device ID and your store name.
- Send the requests in call order. Before List of Cards, enter the OTP the customer received in the OTP variable.
- In Confirm Plan, replace
planIdandprincipleIdwith the values List of Plans returned. Wrong values return reason 70.
Postman stores collection variables in your workspace. Use a test key, never your production key, in a shared workspace.
Checklist before you go live
- Keep your private key on your server, and sign and call QPay from your backend only.
- Generate a new
msgIdfor every call. - Send
deviceIdon every call, so a request can be traced to the device that sent it. - Hash the OTP once with SHA-256 and Base64, and reuse the same hash for List of Cards and Confirm Plan.
- Sign the exact bytes of the JSON body you send, and send the signature in the
tokenheader. - Send
amountas a decimal string, such as"1.000", on List of Plans, Confirm Plan and Refund. - Keep
responseInfo.loanIdfrom every Confirm Plan response, even when the payment is rejected or fails, and send it unchanged on Refund. - Complete an order only on
statusCode1. Treat4as pending, not as a final rejection. - Check
statusCodeanderrorCdbefore you read any other field. Failures also come back with HTTP200. - Allow at least 60 seconds before your HTTP client times out, and stay under 30 requests a minute.
When every item is done, switch to the production host and your production credentials.
Error codes
Every result QPay can return, by call. errorCd carries the reason ID, and statusCode tells you what to do.
Start with Any call, which applies to all five APIs. The four checkout calls also run the customer checks. Success is always errorCd 00 with statusCode 1.
Any call
All five APIs can return these.
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| 49 | Invalid signature | 3 Rejected | token does not verify against the raw request body, or it cannot be verified. |
| 79 | Language not supported | 3 Rejected | senderInfo.lang is not a supported language. |
| 46 | Duplicate message ID | 3 Rejected | msgId has already been used. |
| 38 | Service currently unavailable | 3 Rejected | The requested operation is currently unavailable. Contact QPay if this continues. |
| 70 | Service integration failure | 3 Rejected | The loan service could not complete the request. On Confirm Plan, this also happens when planInfo.planId or planInfo.principleId is missing or invalid. The response may include more detail in failureReasons. |
| 2 | Internal system error | 3 Rejected | An unexpected error at QPay stopped the request. Try again later with a new msgId, and contact QPay if it continues. |
Customer checks
List of Plans, Generate OTP, List of Cards and Confirm Plan check the customer’s mobile number first.
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| 4 | Customer mobile not registered | 3 Rejected | The mobile number is missing or is not registered with QPay. |
| 188 | Customer mobile dormant | 3 Rejected | The mobile number is dormant. |
| 8 | Customer mobile not active | 3 Rejected | The mobile number is inactive. |
| 72 | Customer mobile blocked | 3 Rejected | The mobile number is blocked. This can follow too many failed OTP attempts. See OTP limits. |
| 7 | Customer not active | 3 Rejected | The customer exists but is inactive. |
| 92 | Customer account not found | 3 Rejected | The customer’s mobile account is missing. |
| 94 | Customer account not active | 3 Rejected | The customer’s mobile account is inactive. |
List of Plans
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| 241 | Invalid merchant service ID | 3 Rejected | No merchant service exists for merchantId. |
| 319 | No plans available | 3 Rejected | No installment plans are available for this purchase. plans and principalId are null. |
| 311 | Credit score unavailable | 3 Rejected | The customer’s credit score could not be found, so no plans can be offered. |
| 173 | Credit limit exceeded | 3 Rejected | amount is above the customer’s available credit limit. |
| Varies | Loan service reason | 3 Rejected | The loan service could not return plans. errorCd and desc carry the reason from the loan service. |
Generate OTP
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| 3 | Request not allowed | 3 Rejected | The sender’s profile does not allow this request type. |
List of Cards
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| 207 | Maximum OTP attempts reached | 3 Rejected | The customer has already used all allowed OTP attempts. QPay checks this before the OTP value. |
| 89 | Invalid OTP | 3 Rejected | otp is empty, or the hash does not match. This counts as a failed attempt and blocks the mobile number when the attempts run out. |
| 88 | Expired OTP | 3 Rejected | The OTP matches, but its validity period has passed. This counts as a failed attempt in the same way as reason 89. |
Confirm Plan
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| OTP checks | |||
| 207 | Maximum OTP attempts reached | 3 Rejected | The customer has already used all allowed OTP attempts. QPay checks this before the OTP value. |
| 89 | Invalid OTP | 3 Rejected | otp is empty, or the hash does not match. This counts as a failed attempt and blocks the mobile number when the attempts run out. |
| 88 | Expired OTP | 3 Rejected | The OTP matches, but its validity period has passed. This counts as a failed attempt in the same way as reason 89. |
| Credit check | |||
| 311 | Credit score unavailable | 3 Rejected | The customer’s credit score could not be retrieved in time. |
| Customer verification | |||
| 318 | Credit check not passed | 3 Rejected | The customer’s credit assessment was rejected. |
| 315 | Customer verification rejected | 3 Rejected | The customer did not pass verification. |
| 317 | Customer verification needs review | 3 Rejected | The customer needs further review before this purchase can go ahead. |
| 19 | Request timed out | 3 Rejected | The verification step timed out. |
| 36 | Bank connection failure | 3 Rejected | The verification step failed because of a connection problem. |
| Plan confirmation | |||
| 27 | Merchant service not registered | 3 Rejected | No merchant service exists for planInfo.merchantId. |
| 191 | Merchant service dormant | 3 Rejected | The merchant service is dormant. |
| 23 | Merchant service not active | 3 Rejected | The merchant service is inactive. |
| 274 | Merchant service blocked | 3 Rejected | The merchant service is blocked. |
| 241 | Invalid merchant service ID | 3 Rejected | The merchant’s service details are incomplete. |
| 349 | Customer has a pending loan | 3 Rejected | The customer already has a loan in pending status. |
| 311 | Credit score unavailable | 3 Rejected | The customer’s credit category or remaining loan balance is missing. |
| 318 | Credit check not passed | 3 Rejected | The customer’s credit category is not allowed for this purchase. |
| 173 | Credit limit exceeded | 3 Rejected | amount plus the customer’s remaining balance is above their credit limit. |
| 345 | Merchant not included in plan | 3 Rejected | The selected plan does not include this merchant. |
| Varies | Loan service reason | 3 Rejected | The loan service rejected the plan before a loan ID was returned. errorCd and desc carry the reason from the loan service. |
| 348 | Pending transaction exists | 3 Rejected | A debit transaction for this loan already exists. loanId is already set. |
| Card payment | |||
| 59 | Bank rejected the payment | 3 Rejected | The bank did not accept the card payment, for example because of insufficient funds. The loan and its pending transactions are rejected. loanId is set. |
| 36 | Bank connection failure | 5 Failed | The card payment did not go through: it returned no result, or the payment call failed. loanId is set. Do not complete the order. |
Refund
| Reason ID | Result | statusCode | When it happens |
|---|---|---|---|
| Request checks | |||
| 3 | Request not allowed | 3 Rejected | The sender’s profile does not allow this request type. |
| Merchant service checks | |||
| 39 | Merchant service not registered | 3 Rejected | The merchant service is missing. |
| 190 | Merchant service dormant | 3 Rejected | The merchant service is dormant. |
| 25 | Merchant service not active | 3 Rejected | The merchant service is inactive. |
| 204 | Merchant service blocked | 3 Rejected | The merchant service is blocked. |
| 26 | Merchant not active | 3 Rejected | The merchant is inactive. |
| 92 | Merchant account not found | 3 Rejected | The merchant service account is missing. |
| 94 | Merchant account not active | 3 Rejected | The merchant service account is inactive. |
| Refund checks | |||
| 34 | Transaction not found | 3 Rejected | No confirmed original transaction exists for this loan and merchant service. |
| 201 | Transaction already refunded | 3 Rejected | The original transaction is already marked as refunded. |
| 58 | Refund amount not allowed | 3 Rejected | amount is greater than the original amount minus earlier refunds. |
| 299 | Loan not active | 3 Rejected | The loan is not active. |
| 305 | Refund period expired | 3 Rejected | The refund period for the original transaction has ended. |
| 348 | Pending transaction exists | 3 Rejected | A pending transaction already exists for this loan. |
| Varies | Loan service reason | 3 Rejected | The loan service rejected the refund. errorCd and desc carry the reason from the loan service. |
| 59 | Bank rejected the refund | 4 Pending | The card gateway did not complete the refund. QPay records this as pending, so statusCode is 4. |
| 36 | Bank connection failure | 4 Pending | The card gateway returned no result, or the gateway call failed. |