QRPH

QR Ph is the Philippines’ national QR code standard, mandated and supervised by the Bangko Sentral ng Pilipinas (BSP). It is designed to provide merchants with a single interoperable QR code that allows them to accept payments from multiple banks and e-wallets.

This guide will walk you through integrating QRPH Wallet via API, covering essential steps like initiating payments, handling user redirection, and checking payment statuses.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

How it works

If the customer is paying via QRPH, a QR is displayed on the screen (web/mobile), which can be scanned by any of the supported e-wallets or banking apps.

Payment Flow

1. The customer chooses QRPH as their payment method at checkout.
2. The merchant requests a QRPH transaction with EBANX.
3. EBANX provides a QR code in the response payload.
4. The merchant uses the response to embedded the code on checkout page .
5. The customer is presented with a dynamic QR code on the checkout screen and must complete payment within 30 minutes.

TIP

QR Ph codes have an expiry period of 30 minutes. After 30 minutes, the QR Ph code will expire and can’t be paid . Expired QR Ph codes may still be scanned, but the User will receive an error on their e-wallet/banking app after attempting to pay. These QR Ph codes are also designed to be one-time use only, so once the QR Ph code is paid, the user will receive an error if they attempt to pay it again.

Technical flow

• Request payment - Call the ws/direct endpoint with the parameters defined below
• Payment instructions - In response to this request, EBANX will return a qr code information, to which the merchant must use to embedd / display on their checkout page .
• Customer completes the payment - Once the qr code is embedded, the customer will have 30 minutes to scan the QR. During this time, the transaction will be set on our platform with the status pending (PE).
• Payment Confirmation - As soon as the customer completes the transaction with QRPH, EBANX will receive the response and immediately change the payment status to confirmed (CO) or cancelled (CA).

When this status change occurs, the merchant will receive a notification from us, informing them of the payment hash and that a change has occurred in the payment. To view the final status, simply query the payment through the ws/query endpoint.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Create a QRPH payment

   Check which wallets are available by selected a country using the /ws/ewallet-availableEWallets endpoint.

   To create a QRPH payment, you need to define the parameters in your request. The following table outlines the required parameters for the payment process.

   Parameter	Requirement	Description
   integration_key	Required	Your secret EBANX integration key
   payment_type_code	Required	Set to qrph
   country	Required	Set to ph for Philippines
   name	Optional	Customer name
   email	Required	Customer email
   phone_number	Optional	Customer phone number
   zipcode	Optional	Customer zipcode
   merchant_payment_code	Required	Unique merchant payment code
   currency_code	Required	Must be php
   amount_total	Required	Total amount to be charged

   Note

   QRPH has a minimum amount limit of 20 PHP and a maximum limit of around 9,999,999.99 PHP (please note the e-wallet and issuing bank limit will be applicable)

3. Send payment request

   Send the following request to initiate a QRPH payment.

   cURL Request (Sandbox Example)

   curl --location 'https://sandbox.ebanx.com/ws/direct'
    --header 'Content-Type: application/json'   --data '{
       "integration_key": "{YOUR_INTEGRATION_KEY}",
       "operation": "request",
       "payment": {
         "email": "john.doe@example.com",
         "country": "ph",
         "name" : "Joe" ,
         "zipcode": "560032",
         "payment_type_code": "qrph",
         "merchant_payment_code": "1234-hhb-097",
         "currency_code": "PHP",
         "amount_total": 30,
         "redirect_url": "https://your-call-back-url.com"
       }
     }'

   • The QR code value will be used to render the QR code, where they can proceed with payment.
   
   

   API Response Example

   A successful request will return the below response

   {
     "payment": {
       "hash": "{payment_hash_generated_by_ebanx}",
       "country": "ph",
       "merchant_payment_code": "QRPH Testing url2",
       "order_number": null,
       "status_code": "PE",
       "status_date": null,
       "open_date": "2025-10-06 10:06:49",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "30.00",
       "amount_ext": "0.00",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "PHP",
       "due_date": "2025-10-06 10:36:49",
       "installments": "1",
       "payment_type_code": "qrph",
       "pre_approved": false,
       "capture_available": null,
       "customer": {
         "email": "john.doe@example.com",
         "name": "John",
         "birth_date": null,
         "single_transaction": {
           "amount_local": "0.00",
           "amount_crossborder": "30.00"
         }
       },
       "qrph": {
         "qr_code_value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAtoAAA...",
         "expiration_date": "2025-10-06 10:36:49"
       },
       "status": "SUCCESS"
     }
   }

4. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   Accessing Payment Information

   • This payment can also be accessed through our EBANX Dashboard.

   Sandbox Testing

   TIP When testing in the sandbox, a simulator environment will be rendered, allowing merchants to accept or decline the payment, without direct communication of payment with QRPH.

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to cancelled (CA).

5. Congratulations!

   You have successfully integrated QRPH.

   For more information, refer to the Direct API reference guide

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.