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
- Agreement Signing: Merchant signs agreement and requests integration.
- Documentation: We share this guide and sample certificates.
- Certificate Generation: Merchant generates and shares certificates following our security standards.
- Environment Setup: We register certificates in UAT and Production environments.
- 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:
# 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:
Content-Type: application/json x-Merchant-ID: <your-unique-merchant-identifier> token: <generated-signature>
Header Requirements
x-Merchant-ID
provided after registrationtoken
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>
/** * 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
withOPENSSL_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
- UAT Environment Setup: Configure your system with UAT credentials
- Basic Connectivity: Test authentication and token generation
- API Validation: Verify all endpoints with sample data
- Error Handling: Test with invalid inputs and error conditions
- End-to-End Flow: Complete full transaction lifecycle
- 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