Download the PHP package hakhant/myanmar-payments without Composer

Myanmar Payments for Laravel

Laravel Myanmar payment gateway package for KBZPay, WaveMoney (Wave Pay), 2C2P, and AYA Pay with MMQR support. It provides a single gateway-selection flow, typed request and response DTOs, refunds, callbacks, and Laravel container integration.

Supported Providers

Myanmar payment gateway support for Laravel:

• KBZPay
• WaveMoney (Wave Pay)
• 2C2P
• AYA Pay
• MMQR support for supported providers

Myanmar payments, Myanmar payment gateway, KBZPay Laravel, Wave Pay Laravel, WaveMoney payment gateway, 2C2P Laravel, MMQR Laravel.

Features

• Built for Myanmar payment integrations in Laravel apps
• Supports KBZPay, WaveMoney (Wave Pay), 2C2P, and AYA Pay
• Supports MMQR flows for supported providers
• Strict typing with declare(strict_types=1);
• PSR-4 autoloading
• Provider-driven architecture with PaymentManager, GatewayContract, and provider-specific gateway adapters
• Typed DTOs for payments, refunds, MMQR, and callbacks
• Provider capability contracts for refund, callback verification, and MMQR support
• Application use cases for payment creation, MMQR creation, refunds, status queries, and callback verification
• Provider adapter for 2C2P redirect checkout and refund maintenance
• Provider adapter for AYA Pay push payment, QR payment, status query, and refund
• Provider adapter for WaveMoney payment creation, MMQR creation, and callback verification
• Provider adapter for KBZPay payment, refund, callback verification, and MMQR
• Enum-based or string-based provider selection through Provider and PaymentManager::provider()
• Laravel service provider and facade integration
• Tooling: Pint, Rector, PHPStan, Pest

Requirements

• PHP 8.2+
• Laravel 10/11/12

Installation

Publish Configuration

Environment

Usage

Package Flow

1. Configure provider credentials in config/myanmar-payments.php
2. Resolve a gateway through PaymentManager or the MyanmarPayments facade, or use an application use case
3. Use the high-level manager/wrapper methods for most integrations: createPayment(), queryStatus(), createMmqr(), refund(), verifyCallback()
4. Use capability helpers like supportsMmqr() when your UI or flow depends on provider features
5. Drop down to provider() only when you need direct access to a provider gateway
6. Handle typed DTO responses instead of raw provider payloads

Provider Capability Matrix

Provider Selection

PaymentManager::provider() and MyanmarPayments::provider() accept either a provider string or the Provider enum.

Recommended Integration Style

For most applications, prefer the higher-level PaymentManager methods instead of resolving a gateway manually.

Use capability helpers when you need conditional behavior by provider:

Query Payment Status

For 2C2P, transactionId is the returned payment token because the transaction-status endpoint queries by payment token.

Refund

Provider-specific refund metadata:

• AYA: pass reference_number
• KBZPay: optionally pass refund_request_no or refundRequestNo to control the provider refund request identifier; otherwise the package uses <transactionId>-refund
• 2C2P: refund-specific optional fields are configured through package config such as notify_url and idempotency_id

Verify Callback Signature

Prefer verifying callbacks through PaymentManager, the facade, or the VerifyCallback use case instead of calling a gateway's verifyCallback() method directly. The shared entrypoints apply package-level callback protections before provider-specific signature verification:

• timestamp tolerance validation when CallbackPayload::$timestamp is provided
• idempotency locking to reject duplicate callback deliveries within the configured tolerance window

Configure the tolerance with MM_PAYMENT_CALLBACK_TOLERANCE.

2C2P Notes

• The implemented 2C2P provider supports hosted redirect checkout plus refund maintenance requests.
• Use a sufficiently long HS256 secret key. firebase/php-jwt rejects short keys.
• createPayment() requests a payment token and returns the hosted webPaymentUrl.
• queryStatus() uses the transaction-status endpoint and expects the payment token returned by createPayment().
• Callback verification decodes and verifies the signed JWT payload returned by 2C2P.
• refund() uses the payment-maintenance endpoint with XML wrapped in JWE/JWS using your merchant private key and the 2C2P public key.
• Refund support requires PEM-formatted TWOC2P_MERCHANT_PRIVATE_KEY and TWOC2P_PUBLIC_KEY values from the 2C2P key-exchange setup.
• TWOC2P_KEY_ID is optional and can be set when your 2C2P account expects a kid header in the signed JWS.
• Published config now prefers snake_case refund keys such as notify_url and idempotency_id.
• Legacy camelCase config keys such as notifyURL and idempotencyID are still accepted at runtime for backward compatibility.
• Asynchronous refund completion callbacks and refund-status inquiry are not wrapped yet. The current package support covers refund initiation and mapping the immediate maintenance response.

WaveMoney Notes

• createPayment() posts the documented form payload to WaveMoney /payment and returns a redirect paymentUrl using /authenticate?transaction_id=....
• createMmqr() is supported through the same WaveMoney /payment request flow and returns MmqrResponse::qrCode as the generated /authenticate?transaction_id=... URL.
• Request hashing follows the WaveMoney formula: time_to_live_in_seconds + merchant_id + order_id + amount + backend_result_url + merchant_reference_id using HMAC SHA256.
• Callback verification follows the WaveMoney callback formula and treats null values as the literal string null, as required by docs.
• queryStatus() is intentionally unsupported for WaveMoney in this package because the provided docs define callback-driven status updates but no status inquiry endpoint.
• Treat callback status PAYMENT_CONFIRMED as success and verify hash before updating payment state.

AYA Pay Notes

• createPayment() uses AYA push-payment APIs and requires metadata['customer_phone'].
• When AYA_SERVICE_CODE or metadata['service_code'] is set, the gateway uses AYA push payment v2; otherwise it uses the v1 push endpoint.
• queryStatus() calls AYA checkRequestPayment with externalTransactionId.
• createMmqr() calls AYA requestQRPayment and maps qrdata to MmqrResponse::qrCode.
• refund() requires RefundRequest metadata reference_number because AYA needs both externalTransactionId and referenceNumber.
• AYA callback verification is not implemented yet because the provided swagger does not define a signed webhook/callback contract.

Webhook Security Notes

• Whitelist only the callback fields your provider signs. Avoid using full request payloads.
• Keep signature input format consistent with provider docs (raw body vs parsed fields).
• Reject callbacks with missing signature headers.
• Use PaymentManager::verifyCallback(), MyanmarPayments::verifyCallback(), or the VerifyCallback use case so package-level timestamp and idempotency protections are applied consistently.
• When the provider includes a callback timestamp, pass it into CallbackPayload::$timestamp so the package can reject stale callbacks using MM_PAYMENT_CALLBACK_TOLERANCE.
• The package rejects duplicate callback deliveries within the configured tolerance window before provider-specific verification runs.
• Return non-2xx for invalid signatures and do not mutate payment state.
• Log minimal callback metadata and redact sensitive values.

MMQR Usage

Supported MMQR providers in this package are KBZPay, AYA, and WaveMoney.

Notes by provider:

• KBZPay: uses the standard kbz.payment.precreate endpoint for MMQR with trade_type=PAY_BY_QRCODE; MMQR notify_url is sent as a top-level request field, and refunds can use client TLS certificates when KBZ requires them.
• AYA: uses the QR payment endpoint and maps returned qrdata into MmqrResponse::qrCode.
• WaveMoney: uses the same payment creation endpoint as normal checkout and returns the authenticate URL as qr_code.
• 2C2P: MMQR is not implemented in this package because the current provider integration is focused on hosted checkout, status, refund maintenance, and callback verification.

For WaveMoney, qr_code is the Wave authenticate URL (.../authenticate?transaction_id=...) returned from payment initialization.

For AYA, qr_code is the returned qrdata string from requestQRPayment.

For KBZPay, qr_code is the raw EMVCo/MMQR payload returned by KBZ.

Facade Usage

Quality Commands

Notes:

• composer test, composer analyse, and composer refactor run with XDEBUG_MODE=off by default for faster CLI runs and to avoid Herd/Xdebug restart noise.
• Use composer test:coverage when you want coverage output.

Documentation

For custom provider implementation details, see CONTRIBUTION.md.