Skip to content

1. Introduction

Welcome to our BNPL integration process. This guide provides comprehensive instructions for merchants to integrate with QPay after signing the agreement.

Important: Before starting, ensure you have received your merchant agreement confirmation email.

2. Integration Process Overview

  1. Agreement Signing: Merchant signs agreement and requests integration.
  2. Documentation: We share this guide and sample certificates.
  3. Certificate Generation: Merchant generates and shares certificates following our security standards.
  4. Environment Setup: We register certificates in UAT and Production environments.
  5. Access Provision: We provide x-merchant-id, verified phone number, service ID, API documentation, Postman collection, and environment URLs.

Note: The entire process typically takes 1-3 business days after certificate submission.

3. Certificate Generation

Generate your security certificates using the following OpenSSL commands:

Terminal
# Step 1: Generate Private Key (2048-bit RSA)
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Step 2: Generate Certificate Signing Request
openssl req -new -key private_key.pem -out request.csr \
  -subj "/C=US/ST=State/L=City/O=YourCompany/CN=yourdomain.com"

# Step 3: Generate Public Certificate (Valid for 2 years)
openssl x509 -req -in request.csr -signkey private_key.pem -out public_cert.pem \
  -days 730 -sha256
    

Security Requirements: Please share private_key.pem and public_cert.pem via Email.

Certificate Requirements

  • 2048-bit RSA minimum
  • SHA-256 hashing algorithm
  • 2-year validity period
  • Proper subject fields (Country, Organization, CN)

Important Notes

  • Keep private key secure
  • Do not regenerate unless compromised
  • Notify us before certificate expiration
  • Test certificates in UAT first

4. API Documentation & Endpoints

Download our comprehensive API documentation:

Download API Docs (PDF)
API Description UAT Production
List Plans Retrieve available payment plans /bnpl/mw/list-plans /bnpl/mw/list-plans
List Cards Get customer's saved payment methods /bnpl/mw/list-card /bnpl/mw/list-card
Generate OTP Initiate OTP for transaction /bnpl/mw/generate-otp /bnpl/mw/generate-otp
Confirm Plan Finalize payment plan selection /bnpl/mw/confirm-plan /bnpl/mw/confirm-plan

Base URLs

UAT Environment:

https://bnpl-api-uat.fintec.solutions

Production Environment:

https://bnpl-api.fintec.solutions

5. Request Headers & Authentication

All API requests must include the following headers:

HTTP Headers
Content-Type: application/json
x-Merchant-ID: <your-unique-merchant-identifier>
token: <generated-signature>
    

Header Requirements

  • x-Merchant-ID provided after registration
  • token must be regenerated for each request
  • All headers are case-sensitive

Request Timing

  • Token valid for 5 minutes
  • Clock skew tolerance: ±2 minutes
  • Rate limit: 30 requests/minute
  • Timeout: 30 seconds

6. Signature Generation

Generate request signatures using your private key with the following exact implementation:

Required Headers

Content-Type: application/json
x-Merchant-ID: <your-merchant-id-from-config>
token: <generated-signature>
PHP Implementation
/**
 * Generates a base64-encoded signature for API requests
 * @param array $value Request payload
 * @return string Base64-encoded signature
 * @throws Exception On signing failure
 */
public function sign(array $value): string {
    try {
        $privateKey = $this->loadMerchantPrivateKey();
        
        // Step 1: Convert JSON string to UTF-8 bytes
        $utf8Bytes = json_encode($value);
        
        // Step 2: Sign using RSA private key with SHA256
        $signature = '';
        $success = openssl_sign(
            $utf8Bytes, 
            $signature, 
            $privateKey, 
            OPENSSL_ALGO_SHA256
        );
        
        if (!$success) {
            $error = openssl_error_string();
            throw new Exception('Failed to sign hash: ' . $error);
        }
        
        openssl_free_key($privateKey);
        
        // Step 3: Encode result into Base64 string
        $base64Signature = base64_encode($signature);
        
        Log::info('QPay Security Service - Data signed successfully', [
            'algorithm' => self::HASHING_ALGORITHM,
            'data_length' => strlen($utf8Bytes),
            'signature_length' => strlen($signature),
            'base64_length' => strlen($base64Signature),
            'private_key_source' => 'merchant-certs'
        ]);
        
        return $base64Signature;
    } catch (Exception $e) {
        Log::error('QPay Security Service - Sign failed', [
            'error' => $e->getMessage(),
            'algorithm' => self::HASHING_ALGORITHM,
            'private_key_path' => $this->MerchantPrivateKeyPath
        ]);
        throw new Exception('Failed to sign data: ' . $e->getMessage());
    }
}

Implementation Notes

  • Exactly matches your provided code sample
  • Uses openssl_sign with OPENSSL_ALGO_SHA256
  • Includes error handling and logging
  • Properly frees key resources
  • Returns base64 encoded signature

Common Issues

  • Incorrect private key format
  • Missing Content-Type header
  • Invalid x-Merchant-ID
  • Clock skew between systems

7. After Certificate Submission

After we receive your certificates, you'll receive the following within 2 business days:

Merchant Credentials

  • x-merchant-id (e.g. "qpay")
  • Verified mobile number for OTP
  • Merchant Service ID

Development Resources

  • Postman Collection
  • Sample Code in 5 languages
  • Mock API endpoints

Environment Setup

  • UAT access confirmation
  • Production onboarding
  • IP whitelisting instructions

Pro Tip: Begin testing in our UAT environment immediately after receiving credentials. Production access requires additional verification.

8. Testing & Go-Live Checklist

Download our comprehensive Postman Collection:

Postman Collection (JSON)

Integration Testing Steps

  1. UAT Environment Setup: Configure your system with UAT credentials
  2. Basic Connectivity: Test authentication and token generation
  3. API Validation: Verify all endpoints with sample data
  4. Error Handling: Test with invalid inputs and error conditions
  5. End-to-End Flow: Complete full transaction lifecycle
  6. Performance Testing: Verify under expected load

Go-Live Requirements

Mandatory Items

  • Successful UAT testing report
  • Production certificates submitted
  • IP addresses whitelisted
  • Fallback mechanism implemented

Recommended Checks

  • Load testing completed
  • Monitoring configured
  • Team training conducted
  • Support contacts verified

9. Support & Contact Information

Technical Support

  • Email Support

    alwarith.s@fintec.solutions

    Response time: 2 business hours

  • Emergency Phone

    +968 95675257

Integration Assistance

  • Office Hours

    Sunday-Thursday, 9AM-5PM GST

    Dedicated integration support

Support Guidelines

  • Always include your x-merchant-id in communications
  • For API issues, provide request/response samples
  • Business inquiries should use separate channels
Scroll Up