Wave Pay Mini App

Wave Pay Mini App (Wave Money JS SDK v1.8) lets the customer pay inside the WavePay app: your web page runs in the app's webview and calls Wave's JavaScript SDK. Your server covers the three parts that need secrets; the page itself calls makePayment.

Call	What it does	Returns
`miniApp.AccessToken(ctx)`	Get an access token for the page, cached	`string`
`miniApp.Payment(data)`	Sign the `makePayment` payload, no API call	`*MiniAppPayment`
`HandleCallbackFromContext("wave-pay-mini-app", ctx)`	Verify the callback against the URL it was posted to	`*PaymentCallback`
`miniApp.HandleCallback(request, callbackURL)`	Verify the callback against a callback URL you pass	`*PaymentCallback`

miniApp is the *wavepayminiapp.Gateway that paymentsfacades.MyanmarPayments().WavePayMiniApp() returns. Wave Pay Mini App has no status API: the callback is the only payment result.

How it works

The page logs in with a token from your server, then pays with a payload your server signed. Wave posts the result to your callback URL.

Wave Pay Mini App: token, signed payment, result

Configuration

env

WAVE_PAY_MINI_APP_CLIENT_ID=
WAVE_PAY_MINI_APP_CLIENT_SECRET=
WAVE_PAY_MINI_APP_MINI_APP_ID=
WAVE_PAY_MINI_APP_SECRET_KEY=
WAVE_PAY_MINI_APP_BASE_URL=

Variable	Config key	Description
`WAVE_PAY_MINI_APP_CLIENT_ID`	`wave_pay_mini_app.client_id`	Client ID issued by Wave, for the token endpoint
`WAVE_PAY_MINI_APP_CLIENT_SECRET`	`wave_pay_mini_app.client_secret`	Client secret issued by Wave, for the token endpoint
`WAVE_PAY_MINI_APP_MINI_APP_ID`	`wave_pay_mini_app.mini_app_id`	Your mini app ID (`miniAppID`)
`WAVE_PAY_MINI_APP_SECRET_KEY`	`wave_pay_mini_app.secret_key`	Hash secret key for payment and callback hashes
`WAVE_PAY_MINI_APP_BASE_URL`	`wave_pay_mini_app.base_url`	The API base URL. A trailing `/` is dropped

Every setting is required; MYANMAR_PAYMENTS_HTTP_TIMEOUT (30 seconds by default) applies to the token request. See Configuration for the production and UAT base URLs.

Access Token

The page needs an access token for WaveJsSDK.authModule.loginWithAccessToken(token). Return it from a route of your own:

import (
	"github.com/goravel/framework/contracts/http"
	paymentsfacades "github.com/laranex/goravel-myanmar-payments/v4/facades"

	"yourapp/app/facades"
)

facades.Route().Get("/mini-app/token", func(ctx http.Context) http.Response {
	miniApp, err := paymentsfacades.MyanmarPayments().WavePayMiniApp()
	if err != nil {
		return ctx.Response().String(http.StatusInternalServerError, "%s", err)
	}
	token, err := miniApp.AccessToken(ctx)
	if err != nil {
		return ctx.Response().String(http.StatusBadGateway, "token unavailable")
	}

	return ctx.Response().Json(http.StatusOK, http.Json{"accessToken": token})
})

AccessToken() posts client_id, client_secret and grant_type=client_credentials as a form to {base_url}/auth/v1/external-utility/token and returns access_token. The token is kept in your cache store under myanmar-payments.wave-pay-mini-app.token.<sha256(baseURL|clientID)>, the same key in every Laranex SDK, for Wave's expires_in minus 60 seconds (at least 60 seconds; a missing or non-positive value means 3600). Concurrent calls share one token request. miniApp.ForgetToken() drops it, e.g. after rotating the client secret. Never request the token from the browser: it needs the client secret.

Starting a Payment

import (
	"fmt"

	"github.com/goravel/framework/contracts/http"
	myanmarpayments "github.com/laranex/go-myanmar-payments/v4"
	"github.com/laranex/go-myanmar-payments/v4/wavepayminiapp"
	paymentsfacades "github.com/laranex/goravel-myanmar-payments/v4/facades"
)

func (r *CheckoutController) MiniApp(ctx http.Context) http.Response {
	order := findOrder(ctx) // your own order lookup

	miniApp, err := paymentsfacades.MyanmarPayments().WavePayMiniApp()
	if err != nil {
		return ctx.Response().String(http.StatusInternalServerError, "%s", err)
	}
	data := &wavepayminiapp.PaymentData{
		OrderID:     fmt.Sprintf("ORDER_%d", order.ID),
		CallbackURL: "https://shop.test/payments/wave-pay-mini-app/callback",
		Items: []wavepayminiapp.Item{
			{Name: "Ticket", Amount: myanmarpayments.Kyat(3000)},
			{Name: "Snack", Amount: myanmarpayments.Kyat(2000)},
		},
	}

	payment, err := miniApp.Payment(data)
	if err != nil {
		return ctx.Response().String(http.StatusUnprocessableEntity, "%s", err)
	}

	order.WaveReference = data.MerchantReferenceID
	saveOrder(order) // your own persistence

	return ctx.Response().Data(http.StatusOK, "application/json", []byte(payment.JSON()))
}

Payment() sends no request: it signs the payload and returns it.

wavepayminiapp.PaymentData

Field	Type	Required	Rules
`OrderID`	`string`	Yes	Your order ID (`orderID`)
`CallbackURL`	`string`	Yes	Absolute http or https URL that Wave posts the result to (`callBackUrl`). It is signed, so the callback is verified with this same URL; see Handling Callbacks
`Items`	`[]wavepayminiapp.Item`	Yes	At least one item
`Amount`	`myanmarpayments.Amount`	No	Whole kyat, greater than 0 (Wave doesn't accept decimals). Unset charges the exact sum of the items
`MerchantReferenceID`	`string`	No	Your ID for this attempt (`merchantRefID`). Empty means a random 32-character hex ID; one made only of whitespace is rejected

wavepayminiapp.Item has a Name (required) and an Amount in whole kyat, greater than 0. Errors are collected in this order: orderId, callbackUrl, items, merchantReferenceId, each item's items.0.name and items.0.amount, then amount. Without items or Amount, amount reports The amount field is required.; a negative amount reports The amount field must not be negative.; a decimal one reports Wave Pay Mini App does not accept decimal amounts; the amount field must be a whole number.

The makePayment Payload

payment.JSON() is exactly the object Wave's makePayment takes, in this order:

json

{
  "amount": 5000,
  "miniAppID": "MINI456",
  "merchantRefID": "3f9c0d6e5b2a41c8a7e1f0b9d4c3a2e1",
  "orderID": "ORDER_1",
  "callBackUrl": "https://shop.test/payments/wave-pay-mini-app/callback",
  "hashValue": "…",
  "items": [
    { "name": "Ticket", "amount": 3000 },
    { "name": "Snack", "amount": 2000 }
  ]
}

Amounts are JSON integers with every digit. hashValue is the lowercase hex HMAC-SHA256, keyed with the secret key, of amount, orderID, miniAppID, merchantRefID and callBackUrl joined with no separator, e.g. 5000ORDER123MINI456MERCHANT789https://yourdomain.com/callback. ctx.Response().Json(http.StatusOK, payment) also works, but encoding/json escapes <, > and &; Data() with payment.JSON() sends the exact text.

On the Page

Load Wave's SDK as Wave's guide shows, then pass the payload from your server unchanged. Never compute the token or the hash in the browser.

const sdk = new WaveJsSDK({ appName: 'My Shop', appIconUrl: 'https://shop.test/icon.png' })
await sdk.init()

const { accessToken } = await (await fetch('/mini-app/token')).json()
await window.WaveJsSDK.authModule.loginWithAccessToken(accessToken)

const payload = await (await fetch('/mini-app/orders/1/pay', { method: 'POST' })).json()
const result = await window.WaveJsSDK.paymentModule.makePayment(payload)

makePayment's result only tells the page how the payment screen ended; fulfill from the verified callback.

Merchant Reference ID

Give every attempt, including a retry of the same order, a new MerchantReferenceID. Leave it empty to get a fresh random ID, and store it: the callback's merchantRefId tells you which attempt was paid. Payment() takes a pointer and writes the generated ID to data.MerchantReferenceID once the data passes validation.

Handling Callbacks

The callback carries neither the mini app ID nor the callback URL, so it is verified against a callback URL; the mini app ID comes from the configuration. HandleCallbackFromContext uses the URL the callback was posted to (payments.CallbackURLFromContext(ctx): scheme, host and path, no query string), so sign the payment with that route's URL:

import (
	"github.com/goravel/framework/contracts/http"
	payments "github.com/laranex/goravel-myanmar-payments/v4"
	paymentsfacades "github.com/laranex/goravel-myanmar-payments/v4/facades"

	"yourapp/app/facades"
)

facades.Route().Post("/payments/wave-pay-mini-app/callback", func(
	ctx http.Context,
) http.Response {
	callback, err := paymentsfacades.MyanmarPayments().
		HandleCallbackFromContext(payments.GatewayWavePayMiniApp, ctx)
	if err != nil { // *myanmarpayments.SignatureVerificationError, ...
		return ctx.Response().String(http.StatusBadRequest, "invalid")
	}

	if callback.IsSuccessful() {
		// callback.OrderID is your OrderID
		// callback.Raw["merchantRefId"] is the attempt's reference
		// callback.GatewayReference is Wave's transactionId
	}

	return payments.Acknowledge(ctx, callback)
})

CallbackURLFromContext takes the scheme from the connection (https only when it used TLS) and the host from the Host header; X-Forwarded-Proto and X-Forwarded-Host are not read. Behind a proxy that changes either, verify with the public URL instead:

miniApp, err := paymentsfacades.MyanmarPayments().WavePayMiniApp()
request, err := payments.CallbackRequestFromContext(ctx)
callback, err := miniApp.HandleCallback(request, "https://shop.test/payments/wave-pay-mini-app/callback")

manager.HandleCallback("wave-pay-mini-app", request) has no URL to verify against and returns payments.ErrCallbackURLRequired; so does the *payments.WavePayMiniAppCallbackHandler that manager.Gateway("wave-pay-mini-app") returns until you set its CallbackURL.

The expected hashValue is the same HMAC as the payment's, over the callback's amount (its exact JSON text), orderId, your mini app ID, merchantRefId and the callback URL, compared in constant time and ignoring the case of the hex digits. A missing or non-string hashValue, a mismatch, or an object or array in any callback field returns a *myanmarpayments.SignatureVerificationError with Wave Pay Mini App callback hash verification failed.. After the hash matches, orderId and merchantRefId must not be empty and amount must be a whole number; otherwise it returns Wave Pay Mini App callback is malformed..

Statuses

Only successful means the customer paid. transactionStatus is matched trimmed and case-insensitively.

Wave `transactionStatus`	`PaymentStatus`
`successful`	`StatusSuccessful`
`processing`	`StatusPending`
`failed`	`StatusFailed`
anything else	`StatusUnknown`

Responses

What Wave Pay Mini App puts in each field. See Results and PaymentCallback & Status for the full types.

`Payment()` → `*MiniAppPayment`

Field / Method	Wave Pay Mini App value
`Flow()`	`FlowMiniApp`
`OrderID`	Your `OrderID`
`Amount`	The signed total, an `Amount` in whole kyat
`MiniAppID`	The configured `mini_app_id`
`MerchantReferenceID`	Your `MerchantReferenceID`, generated when empty
`CallbackURL`	Your `CallbackURL`
`HashValue`	The payload's hash
`Items`	`[]myanmarpayments.MiniAppItem` (`Name`, `Amount`)
`JSON()` / `MarshalJSON()`	The `makePayment` object: `amount`, `miniAppID`, `merchantRefID`, `orderID`, `callBackUrl`, `hashValue`, `items` (`name`, `amount`), amounts as JSON integers

`HandleCallback()` → `*PaymentCallback`

Field	Wave Pay Mini App value
`OrderID`	Wave `orderId`
`Status`	`transactionStatus` mapped, see Statuses
`GatewayStatus`	Wave `transactionStatus`, trimmed, e.g. `successful`
`GatewayReference`	Wave `transactionId`
`Amount`	Wave `amount`, e.g. `1000`
`Raw`	The verified body: `merchantRefId`, `orderId`, `amount`, `msisdn`, `hashValue`, `transactionId`, `transactionStatus`
`Acknowledgement`	HTTP `200`, empty body, `Content-Type: text/plain`

Errors

Call	Returns	When
`WavePayMiniApp()`	`*ConfigurationError`	A setting is missing or blank, e.g. `myanmarpayments: The wave_pay_mini_app configuration is missing [client_id].`
`Payment()`	`*InvalidPaymentDataError`	A value breaks the rules above. Nothing is signed. Item errors use `items.0.name` and `items.0.amount` keys
`AccessToken()`	`*APIError`	Wave answers with an HTTP error, a body that isn't JSON, or no `access_token`. The message is `Wave Pay Mini App token request failed: [<error>] <error_description>` when Wave sends an `error`, else `Wave Pay Mini App token request failed with HTTP <status>.`; `GatewayCode` is Wave's `error`, `GatewayMessage` its `error_description` (or `message`)
`HandleCallbackFromContext()`, `HandleCallback()`	`*SignatureVerificationError`	`Wave Pay Mini App callback hash verification failed.`: `hashValue` is missing, not a string or doesn't match, or a callback field holds an object or array. `Wave Pay Mini App callback is malformed.`: the hash matches but `orderId` or `merchantRefId` is empty, or `amount` isn't a whole number
`manager.HandleCallback()`	`payments.ErrCallbackURLRequired`	Called with `wave-pay-mini-app`: use `HandleCallbackFromContext` or `WavePayMiniApp().HandleCallback(request, callbackURL)`

Wave Pay Mini App ​

How it works ​

Configuration ​

Access Token ​

Starting a Payment ​

wavepayminiapp.PaymentData ​

The makePayment Payload ​

On the Page ​

Merchant Reference ID ​

Handling Callbacks ​

Statuses ​

Responses ​

Payment() → *MiniAppPayment ​

HandleCallback() → *PaymentCallback ​

Errors ​