​
OnePay Production Configuration

canonical term: OnePay hosted checkout
Doc Status: Production-only | House of Legends no longer supports the OnePay sandbox/test environment in active runtime configuration.
House of Legends uses OnePay hosted checkout for real payment processing on houseoflegends.vn. OnePay runtime keys are Cloudflare Worker secret bindings. Credential values must never be committed to git, added to examples, pasted in support tickets, or shown in screenshots.

​
Why This Matters

The booking flow now creates real guest payment attempts. Any sandbox URL or TEST merchant credential would send guests into the wrong payment environment and make payment reconciliation unreliable. The Hono Worker fails closed when OnePay runtime configuration contains known sandbox URL signals such as mtf.onepay.vn. Credential names and values are supplied by Cloudflare Worker secret bindings, not source code.

​
Current Secret Check

Checked against Cloudflare with wrangler secret list on 2026-06-03. Only secret names were inspected; credential values were not read, logged, copied, or committed.
The production hol-hono Worker currently has every OnePay runtime key required by apps/hono/src/lib/onepay/env.ts.
Secret nameRequiredUsed for
ONEPAY_MERCHANT_IDYesvpc_Merchant
ONEPAY_ACCESS_CODEYesvpc_AccessCode
ONEPAY_HASH_CODEYesvpc_SecureHash signing and response verification
ONEPAY_PAYMENT_URLYesHosted checkout URL
ONEPAY_QUERYDR_URLYesQueryDR reconciliation endpoint
ONEPAY_RETURN_URLYesDefault browser return URL
ONEPAY_IPN_URLYesDynamic IPN callback URL / vpc_CallbackURL
ONEPAY_VERSIONYesvpc_Version
ONEPAY_CURRENCYYesvpc_Currency
ONEPAY_VPC_USERYesQueryDR API username
ONEPAY_VPC_PASSWORDYesQueryDR API password
Presence of a secret name does not prove the value is correct. OnePay can still reject checkout if the merchant ID, access code, hash code, currency, payment URL, or QueryDR account values come from different OnePay technical accounts.

​
Raw Folder Findings

The legacy raw OnePay PHP files were checked on 2026-06-03:
FileFinding
ref/raw/ticket-booking/onepay/config.phpReads OnePay values from PHP $_ENV; embedded fallback values are sandbox/test values only
ref/raw/ticket-booking/onepay/config_backup.phpSame pattern as config.php; embedded fallback values are sandbox/test values only
ref/raw/ticket-booking/onepay/create_payment.phpBuilds checkout parameters from the config constants; does not define production credentials
ref/raw/ticket-booking/onepay/helper.phpSigns and verifies OnePay payloads from config constants; does not define production credentials
ref/raw/ticket-booking/onepay/query_dr.phpQueries OnePay from config constants; does not define production credentials
The raw fallback values must not be copied into production. They point at OnePay’s MTF sandbox/test environment and are not valid production credentials.

​
Production Runtime Values

These values are not passwords, but production stores them as Worker secrets because the Hono runtime loads all OnePay payment settings through the same secret binding path.
FieldRuntime keyValue
Payment URLONEPAY_PAYMENT_URLhttps://onepay.vn/paygate/vpcpay.op
QueryDR URLONEPAY_QUERYDR_URLhttps://onepay.vn/msp/api/v1/vpc/invoices/queries
Return URLONEPAY_RETURN_URLhttps://houseoflegends.vn/api/onepay/return
IPN URLONEPAY_IPN_URLProduction IPN URL configured in Cloudflare
VersionONEPAY_VERSION2
CurrencyONEPAY_CURRENCYVND

​
Required Credential Secrets

SecretDescription
ONEPAY_MERCHANT_IDProduction OnePay merchant identifier
ONEPAY_ACCESS_CODEProduction OnePay API access code
ONEPAY_HASH_CODEHMAC-SHA256 secret key for SecureHash signing
ONEPAY_VPC_USERProduction QueryDR API username
ONEPAY_VPC_PASSWORDProduction QueryDR API password
Do not paste production credential values into this repository, documentation, chat, or issue trackers. Set them directly in Cloudflare.

​
Manage Secrets

cd apps/hono

# List configured secret names only. Values are redacted by Cloudflare.
wrangler secret list

# Set production OnePay secrets.
wrangler secret put ONEPAY_PAYMENT_URL
wrangler secret put ONEPAY_QUERYDR_URL
wrangler secret put ONEPAY_RETURN_URL
wrangler secret put ONEPAY_IPN_URL
wrangler secret put ONEPAY_VERSION
wrangler secret put ONEPAY_CURRENCY
wrangler secret put ONEPAY_MERCHANT_ID
wrangler secret put ONEPAY_ACCESS_CODE
wrangler secret put ONEPAY_HASH_CODE
wrangler secret put ONEPAY_VPC_USER
wrangler secret put ONEPAY_VPC_PASSWORD

​
Checkout Request Rules

The hosted checkout start route is POST /api/reservations/{id}/onepay/start. Hono builds the OnePay request; frontend code must not hand-compose OnePay URLs.
OnePay fieldHono valueRule implemented in code
vpc_MerchTxnRefHOL-{reservationId}Maximum 40 characters; no timestamp suffix
vpc_OrderInfoBooking {reservationReference}Maximum 34 characters; mirrors the legacy OnePay invoice format
vpc_TicketNoFirst valid non-loopback IPv4 from Cloudflare/proxy headers; fallback IPv4 only when unavailableOnePay requires this field; production should supply the real customer IP through Cloudflare
vpc_ReturnURL/api/onepay/returnRequired browser return URL; locale is inferred from OnePay’s returned vpc_Locale
vpc_CallbackURLONEPAY_IPN_URLKept enabled for server-to-server IPN
vpc_AmountReservation total multiplied by 100Required by OnePay even for VND
vpc_CardListOptional request body valueUse only OnePay-supported method codes
vpc_SecureHashGenerated by Hono from sorted request parametersUses ONEPAY_HASH_CODE
Supported vpc_CardList values in the local OnePay integration reference include INTERNATIONAL, INTERCARD, DOMESTIC, VIETQR, QR, BNPL, and APPLEPAY. Omit cardList unless the product flow needs to force one payment group.

​
Troubleshooting OnePay Rejections

1

Use a fresh checkout URL

OnePay error URLs are immutable. If code was redeployed, start a new reservation checkout and inspect the new order_info, merch_txn_ref, and create_time query values.
2

Read the OnePay error name

INVALID_INVOICE usually points at invoice/order fields such as vpc_OrderInfo, duplicate invoice references, or merchant-account invoice rules. INVALID PARAMETER is broader and can include URL, currency, access-code, card-list, amount, or ticket-number problems.
3

Confirm account consistency

Ask OnePay to confirm the production merchant ID, access code, hash code, currency, payment URL, QueryDR username, and QueryDR password all belong to the same technical account.
4

Check ticket number input

If OnePay returns INVALID PARAMETER, confirm Cloudflare is forwarding a real customer IPv4 to Hono. vpc_TicketNo is required by OnePay and fallback values are only used to avoid blocking checkout before the redirect.
5

Check Worker logs without leaking secrets

Log parameter names, lengths, and sanitized derived values only. Never log ONEPAY_HASH_CODE, access codes, passwords, or full signed payment URLs in production.

​
Production Verification

Payment-flow signoff requires real production verification after deployment. Localhost, tunnels, mocked callbacks, and hand-built signed URLs are diagnostics only.
1

Confirm Worker configuration

Verify the Hono Worker is deployed with production OnePay URLs and the five production OnePay secrets above.
2

Start a real checkout

Create a controlled reservation and confirm the hosted checkout redirects to https://onepay.vn/paygate/vpcpay.op.
3

Complete payment

Complete a real OnePay transaction using an operator-approved payment method and amount.
4

Verify callbacks and reconciliation

Confirm the return URL, IPN callback, QueryDR audit, payment status transition, reservation state, and receipt behavior in production logs and the dashboard.

​
See Also

  • Payment - How payments work in the booking system
  • Payment step - The booking flow payment step