{"title": "Integration", "content": "# Q Payment Gateway Integration Guide\n\n## Overview\nQ Payment Gateway allows businesses to accept payments on their websites and applications. This guide covers everything you need to integrate Q Payment into your platform.\n\n## Getting Started\n\n### 1. Merchant Registration\nWhen you register on Q, a merchant store is automatically created for you with:\n- Default transaction limits (\u20a650,000 daily, \u20a61,000,000 monthly)\n- A unique API key and secret\n- Basic store details\n\nTo increase your limits and go live:\n1. Complete your merchant profile\n2. Add your settlement bank account\n3. Submit required verification documents\n4. Set up your webhook URL (recommended)\n\nYour merchant dashboard will provide:\n- API Key (starts with `q_pk_`)\n- API Secret (starts with `q_sk_`)\n- Webhook Secret (if configured)\n\n### 2. Integration Methods\n\n#### A. Simple Button Integration\nThe easiest way to integrate Q Payment:\n\n```html\n<!-- Include Q Payment SDK -->\n<script src=\"https://api.qsocial.net/static/js/q-pay.min.js\"></script>\n\n<!-- Initialize Q Payment -->\n<script>\n    window.Q_PAY_CONFIG = {\n        publicKey: 'YOUR_PUBLIC_KEY',  // Your q_pk_ key\n        baseUrl: 'https://api.qsocial.net'\n    };\n</script>\n\n<!-- Add Payment Button -->\n<button class=\"q-payment-button\"\n        data-amount=\"5000\"\n        data-reference=\"ORDER123\"\n        data-callback-url=\"https://yoursite.com/verify-payment\"\n        data-customer-email=\"customer@example.com\"\n        data-customer-name=\"John Doe\"\n        data-metadata='{\"order_id\": \"123\"}'>\n    Pay \u20a65,000 with Q\n</button>\n```\n\n#### B. Direct API Integration\nFor more control over the payment flow:\n\n```javascript\nconst qpay = new QPay('YOUR_PUBLIC_KEY');\n\ntry {\n    const response = await qpay.initializePayment({\n        amount: 5000,\n        reference: 'ORDER123',\n        callbackUrl: 'https://yoursite.com/verify-payment',\n        customerEmail: 'customer@example.com',\n        customerName: 'John Doe',\n        metadata: {\n            order_id: '123',\n            custom_field: 'Custom value'\n        }\n    });\n\n    if (response.authorization_url) {\n        window.location.href = response.authorization_url;\n    }\n} catch (error) {\n    console.error('Payment initialization failed:', error);\n}\n```\n\n### 3. Payment Verification\n\n#### A. Callback URL\nAfter payment completion, we redirect to your callback URL with:\n```\nhttps://yoursite.com/verify-payment?reference=ORDER123&status=success&transaction_id=QPY123456\n```\n\nParameters:\n- `reference`: Your order reference\n- `status`: Payment status (`success`, `failed`, `cancelled`)\n- `transaction_id`: Q transaction ID\n\n#### B. Server-side Verification\nYou can verify payments server-side:\n\n```python\nimport requests\n\ndef verify_payment(reference):\n    headers = {\n        'X-API-KEY': 'YOUR_API_KEY'  // Your q_sk_ key\n    }\n\n    response = requests.post(\n        'https://api.qsocial.net/api/gateway/payments/verify/',\n        headers=headers,\n        json={'reference': reference}\n    )\n\n    if response.status_code == 200:\n        payment_data = response.json()\n        if payment_data['status'] == 'completed':\n            # Payment successful, fulfill order\n            pass\n    return response.json()\n```\n\n### 4. Webhook Integration\n\nSet up webhooks to receive real-time payment updates:\n\n```python\nfrom django.http import HttpResponse\nimport hmac\nimport hashlib\n\ndef webhook_handler(request):\n    signature = request.headers.get('X-Q-Signature')\n    payload = request.body\n\n    # Verify webhook signature\n    expected_signature = hmac.new(\n        WEBHOOK_SECRET.encode(),\n        payload,\n        hashlib.sha256\n    ).hexdigest()\n\n    if signature != expected_signature:\n        return HttpResponse(status=400)\n\n    event_data = request.json()\n    event_type = event_data['event']\n\n    if event_type == 'payment.completed':\n        reference = event_data['data']['reference']\n        amount = event_data['data']['amount']\n        # Update order status\n        pass\n\n    return HttpResponse(status=200)\n```\n\nEvents:\n- `payment.completed`: Payment successful\n- `payment.failed`: Payment failed\n- `payment.refunded`: Payment refunded\n- `payment.disputed`: Payment disputed\n\n### 5. Testing\nTest cards:\n- Success: `4242 4242 4242 4242`\n- Failure: `4000 0000 0000 0002`\n- Insufficient Funds: `4000 0000 0000 9995`\n\nTest card details:\n- Expiry: Any future date\n- CVV: Any 3 digits\n- PIN: Any 4 digits\n- OTP: `123456`\n\n### 6. Going Live Checklist\n1. Complete merchant verification\n2. Update API keys to production\n3. Update script source to production URL\n4. Test end-to-end with real cards\n5. Set up webhook handling\n6. Implement proper error handling\n7. Set up monitoring\n8. Configure settlement details\n\n### 7. Security Best Practices\n1. Never expose your API secret (`q_sk_`) in client-side code\n2. Always verify webhook signatures\n3. Implement idempotency for webhook processing\n4. Use HTTPS for all endpoints\n5. Validate payment amounts server-side\n6. Store sensitive data securely\n7. Monitor for suspicious activity\n8. Implement rate limiting\n9. Keep API keys secure\n10. Regular security audits\n\n### 8. Rate Limits\n- API Requests: 100/minute\n- Webhook Retries: 3 attempts (5-minute intervals)\n- Merchant Registration: 3/hour\n\n### 9. Support & Resources\n- Documentation: https://api.qsocial.net/docs\n- Support Email: support@qsocial.net\n- API Status: https://status.qsocial.net\n- Support Hours: 24/7\n"}