QR Ph payment integration
QR Ph payment API for interoperable merchant checkout
Design a QR Ph person-to-merchant flow that displays the right QR, preserves a unique merchant reference and confirms the result on the server. Bifu provides integration consultation; QR Ph is the Philippine national QR standard, not a Bifu-owned payment product.
Payment capabilities
What QR Ph means for a merchant
Use the interoperable standard through a participating route without confusing the standard, the payer app and the integration provider.
A national QR standard
Bangko Sentral ng Pilipinas describes QR Ph as the national QR code standard developed for interoperable digital payments between participating banks and non-bank electronic money issuers, including person-to-merchant payments.
The app is not the QR standard
A payer may scan an eligible QR Ph code with a participating bank or wallet app. Actual app acceptance, transaction limits, fees and availability belong to the participating institutions and the contracted route.
Bifu's independent role
Bifu is not BSP, PPMI, GCash, a QR Ph scheme operator, bank, e-money issuer, acquirer or licensed funds custodian, and does not claim official partnership with them. Bifu can help plan and implement the merchant-side integration around an available provider route.
Static QR versus dynamic QR
Choose the QR model by checkout context, order volume and the reconciliation evidence available from the contracted provider.
Static QR
A reusable merchant QR can suit a physical counter or a simple payment flow. Depending on the provider design, the payer may enter the amount and the merchant may need stronger reference capture and manual exception matching.
Dynamic QR
A per-order QR can carry the amount, merchant reference, expiry or other fields allowed by the applicable specification. It is usually easier to associate with an online order, but the QR content must be generated by the contracted route rather than invented by the merchant.
Decision rule
Prefer a dynamic order-linked flow when automated confirmation and high-volume reconciliation matter. Use a static flow only when its payer instructions, reference rules and matching process are unambiguous for the intended checkout.
Merchant-presented QR Ph flow
The merchant displays the QR and the payer scans it, while server-to-server confirmation remains the source of truth.
1. Prepare the order
Create a unique merchant order, fixed PHP amount and expiry in your system. Request or retrieve the QR artifact exactly as the live provider specification requires, and store every returned route reference.
2. Display and scan
Present a clear, unmodified QR at a usable size with the amount, expiry and payment instructions. The payer scans it in an eligible participating app and reviews the payee and amount before authorizing payment.
3. Confirm the result
Show a waiting state while your server receives a verified callback or queries the original order. A screenshot, QR scan, browser redirect or payer-side success display alone is not merchant confirmation.
QR Ph API integration pattern
Treat QR generation, payment confirmation and recovery as separate parts of one order lifecycle.
QR order creation
Send only the fields defined by the contracted API, using a unique idempotency or merchant-order key when required. Store the returned order reference, QR payload or image reference, amount, currency and expiry.
Callback verification
Validate the documented signature against the raw notification, check its timestamp and match the reference, amount and currency. Apply an atomic, idempotent state update before returning the agreed acknowledgement.
Status-query fallback
Query the same order when the callback is delayed, invalid or missing. Use capped backoff and documented terminal states; never respond to uncertainty by creating a second collection for the same purchase.
Reconciliation and payment exceptions
Make every QR payment traceable from the merchant order to the route record and settlement report.
Daily order matching
Compare merchant and route references, gross amount, currency, final status, payment time and any returned institution or transaction reference. Apply the business-date boundary defined for the route.
Settlement matching
Link confirmed payments to settlement batches and compare fee and net-amount definitions from the applicable commercial terms. Payment success is not by itself proof of settlement.
Exception workflow
Queue amount mismatches, expired QR attempts, unknown or long-pending states, duplicate references and unmatched settlement entries with evidence, an owner and a documented next action.
When to use GCash versus QR Ph
Choose by required acceptance experience and live route capability, not by treating the names as interchangeable.
GCash-specific checkout
Consider a GCash-specific route when the checkout is intentionally designed around the GCash wallet experience and the contracted integration explicitly supports that payment method.
QR Ph checkout
Consider QR Ph when one standards-based merchant QR should be scannable across eligible participating banks and wallets. Confirm the live participant, acceptance and limit details before launch.
Offer both with clear routing
A merchant can present distinct GCash and QR Ph choices when supported, but each order must record the selected route. Do not display duplicate choices that lead to the same flow or imply broader acceptance than is available.
QR Ph go-live checklist
Validate the actual QR artifact and full payment lifecycle before accepting production orders.
Confirm the live QR model
Document whether the route uses static or dynamic QR, the supported payer apps, amount and expiry rules, QR display requirements, production domains, signatures, credentials, limits, fees and settlement terms.
Test payer and notification paths
Cover a valid payment, cancellation, expiry, wrong amount where applicable, duplicate scan, duplicate callback, invalid signature, missing callback, delayed result and status-query recovery.
Run a reconciliation drill
Trace test orders from QR creation through scan, verified confirmation, ledger posting and settlement matching. Assign owners and response times for QR display, payment and accounting exceptions.
FAQ
Common questions
What is QR Ph?
QR Ph is the Philippine national QR code standard for interoperable payments through participating banks and electronic-money issuers. QR Ph person-to-merchant payment is distinct from a proprietary wallet QR.
Is Bifu an official QR Ph, BSP or GCash provider?
No. Bifu is independent and provides integration consultation and implementation support around an available contracted route. It does not claim to operate QR Ph or represent BSP, PPMI, GCash or a participating financial institution.
How can I start a QR Ph consultation?
Use Contact support to speak directly with Bifu about current QR Ph route availability and the technical path for static or dynamic merchant-presented payment.
What is the difference between static and dynamic QR?
A static QR is normally reused, while a dynamic QR is generated for a specific order and can include allowed order details such as an amount or reference. Exact payload fields and expiry rules depend on the contracted provider specification.
Can a customer pay a QR Ph code with GCash?
GCash states that its app can scan QR Ph codes from GCash and other financial institutions. Merchant acceptance still depends on an eligible QR, participating institutions, the live route and any current account or transaction conditions.
Does scanning the QR mean the order is paid?
No. A scan only starts the payer flow. The merchant should confirm the payment through a verified server callback or the documented status-query method before crediting the order.
How should duplicate or delayed QR Ph notifications be handled?
Verify the notification and update the existing order idempotently. Query the original reference when delivery is delayed, and prevent repeated events from posting value more than once.
Is QR Ph also a payout method?
This page covers person-to-merchant collection. Payout is a separate flow with its own route, destination rules, status model and reconciliation requirements.
Related payment resources
Continue with the technical and channel details
GCash payment API
Compare a wallet-specific API flow with QR Ph merchant payments.
Read resourcePhilippines native payments
See GCash, Maya, QR Ph and bank-transfer options in one overview.
Read resourceAPI structure example
Review generic callback, query, idempotency and reconciliation patterns.
Read resourceOfficial references
Product access and final technical specifications come from the relevant provider. These primary sources help verify the public background used on this page.
- Bangko Sentral ng Pilipinas: QR Ph
The BSP overview of the interoperable national QR standard and its P2M use through InstaPay.
- BSP QR Ph P2M FAQ
The official person-to-merchant flow, participant and merchant guidance.
- GCash Help Center: Scan to pay
GCash's official instructions for scanning merchant and QR Ph codes in the app.
Plan a QR Ph merchant payment flow
Discuss static or dynamic QR, order creation, callback and query controls, reconciliation fields and the launch tests needed for an available QR Ph integration route.
Contact support