QR Code Payments

Implement scan-to-pay QR code solutions with EcobankPay

Overview

QR code integration with EcobankPay enables contactless payments through scannable codes. The integration follows these general steps:

1. Generate a QR code through the EcobankPay API
2. Display the QR code to the customer
3. Customer scans the code using their banking or payment app
4. EcobankPay processes the payment and notifies your application
5. Verify the payment status using the status check endpoint

Types of QR Codes

Integration Steps for Dynamic QR

1. Generate Dynamic QR Code

To generate a dynamic QR code, send a POST request to the EcobankPay QR code endpoint:

Required parameters for the request:

Optional parameters:

2. Sample Request

Here's an example of a dynamic QR code generation request:

POST https://pgw.paywithonline.com/v1/qr_payments
Content-Type: application/json

{
  "merchant_key": "abcdef1234-f5d6-4931-8544-58dc97a5",
  "invoice_id": "QR12345",
  "total": 25.00,
  "qr_type": "dynamic",
  "description": "Payment for Order #12345",
  "expiry_time": 15,
  "ipn_url": "https://yourwebsite.com/api/payment-webhook",
  "secure_hash": "d4f321f8fddd0e7cc24e5d9bc321ea5c25c6f05d44401f7fb0b9f2a3cc4c"
}

3. Response Handling

Upon successful submission, you'll receive a JSON response containing the QR code data:

{
  "success": true,
  "qr_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAK...",
  "qr_code_url": "https://pgw.paywithonline.com/qr/7785598425589933",
  "tx_reference": "ECO123456789",
  "expires_in": 900,
  "message": "QR code generated successfully"
}

The key parameters in the response:

• qr_data: Base64-encoded image data for the QR code
• qr_code_url: URL to view the QR code (can be embedded in iframe)
• tx_reference: EcobankPay's unique transaction reference
• expires_in: Time in seconds until the QR code expires

4. Display the QR Code

You can display the QR code to your customer in several ways:

• Embed the base64 image data directly in an <img> tag
• Use the QR code URL in an iframe
• Redirect the customer to the QR code URL

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAK..." alt="Scan to pay" />

5. Payment Notification Handling

When a customer scans the QR code and completes payment, EcobankPay will send a notification to your ipn_url (if provided) with payment details.

6. Verify Payment Status

To verify the payment status, make a GET request to the transaction status endpoint:

The response will include the current transaction status:

{
  "status": "paid",
  "status_reason": "",
  "invoice_id": "QR12345",
  "amount": 25.00,
  "as_at": "2023-03-28T14:22:30Z",
  "narration": "Payment for Order #12345"
}

Static QR Code Integration

To generate a static QR code that can be reused for multiple transactions:

Required parameters:

Optional parameters:

POST https://pgw.paywithonline.com/v1/qr_payments
Content-Type: application/json

{
  "merchant_key": "abcdef1234-f5d6-4931-8544-58dc97a5",
  "qr_type": "static",
  "qr_identifier": "store-checkout-1",
  "description": "Main store checkout",
  "ipn_url": "https://yourwebsite.com/api/payment-webhook",
  "secure_hash": "9a8fdcb234e5d6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7"
}

The response will include the static QR code that you can print and display at your physical location:

{
  "success": true,
  "qr_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAK...",
  "qr_code_url": "https://pgw.paywithonline.com/static-qr/store-checkout-1",
  "qr_identifier": "store-checkout-1",
  "message": "Static QR code generated successfully"
}

QR Payment Flow

The payment process using QR codes follows this flow:

1. Merchant generates and displays QR code (dynamic or static)
2. Customer opens their mobile banking or payment app with QR scanning capability
3. Customer scans the QR code
4. For static QR codes, customer enters payment amount; for dynamic, amount is pre-filled
5. Customer confirms payment
6. EcobankPay processes the transaction
7. EcobankPay sends notification to merchant's system
8. Merchant confirms payment status via the status check endpoint

Error Handling

Common errors in QR code integration:

Best Practices

• For dynamic QR codes, set an appropriate expiry time based on your business needs
• Display clear instructions next to QR codes explaining how to scan and pay
• For static QR codes, implement a system to reconcile payments by polling the status endpoint
• Include your merchant name and logo on QR code displays to build customer trust
• Test both dynamic and static QR codes thoroughly in the sandbox environment
• For physical displays, ensure QR codes are printed with sufficient size and contrast