com.themona:monapay

Java SDK for the MONA Pay API: create checkout links and VietQR codes, manage virtual accounts, webhooks and email notifications, and verify signed webhooks.

Requires Java 11+. No runtime dependencies; HTTP goes through java.net.http.HttpClient.

Install

Maven coordinates (once the package is published):

<dependency>
  <groupId>com.themona</groupId>
  <artifactId>monapay</artifactId>
  <version>0.4.0</version>
</dependency>

Quick start

import com.themona.monapay.MonaPay;
import java.util.Map;

MonaPay client = MonaPay.fromEnv();
Object checkout = client.checkouts().create(MonaPay.object(
    "amount", 250000,
    "order_code", "DH10234",
    "return_url", "https://shop.example/payment/return"));
String url = (String) ((Map<?, ?>) checkout).get("checkout_url");

Usage

Client

// From environment variables (see Configuration)
MonaPay client = MonaPay.fromEnv();

// Or explicitly
MonaPay client = MonaPay.clientCredentials(
        System.getenv("MONAPAY_CLIENT_ID"),
        System.getenv("MONAPAY_CLIENT_SECRET"))
    .baseUrl("https://api.monapay.vn")      // optional
    .timeout(java.time.Duration.ofSeconds(30)) // optional
    .build();

Object profile = client.me();

• Client credentials are the recommended login. MonaPay.builder(username, password) is a legacy fallback and does not work for accounts with 2FA enabled.
• The token is cached until 60 seconds before expires_in. A request that fails with HTTP 401 triggers a new login and is retried once.
• X-Client-Secret is sent on non-GET requests when a client secret is set. A secret returned by keys().generate() is kept by the client if none was set.
• Request bodies are Map<String, Object>; MonaPay.object(k1, v1, k2, v2, ...) builds one inline.
• Methods return the data field of the response. Errors are thrown as MonaPayException with getStatus() and getBody().

Resources

Accessor	Methods
keys()	generate, list, destroy, reveal, rotate
bankAccounts()	list
va()	register, verify, registerNotification, verifyNotification, list
paymentProfile()	get, set, rotateReturnSecret, revealReturnSecret
checkouts()	create, get, list, cancel
qr()	generate, cancel
transactions()	list, iterate, retry
sandbox()	createTransaction
webhooks()	list, create, update, remove, test
webhookLogs()	list, stats
emailConfigs()	list, create, get, update, remove, verify, resendVerification, test
emailLogs()	list, stats
emailSuppressions()	list, remove

Hosted checkout

checkouts().create and checkouts().cancel send an Idempotency-Key header generated by the SDK; use the overload with a key argument to set your own. Fulfil orders from the CHECKOUT_PAID webhook or from checkouts().get(id), not from the browser redirect.

Sandbox

Object tx = client.sandbox().createTransaction(MonaPay.object(
    "virtual_account_number", "MONA123",
    "amount", 10000,
    "description", "Sandbox test"));

Transactions

for (Object transaction : client.transactions().iterate(
        "MONA000001",
        new MonaPay.TransactionOptions().limit(100).sinceId("FT26240001234"))) {
    // Process the transaction; store transaction_code to avoid duplicates.
}

sinceId is handled by the SDK: the iterator stops before the item whose id or transaction_code matches. It is not sent to the API.

Webhooks

Verify the exact raw request bytes. verifyWebhook takes the X-Mona-Timestamp and X-Mona-Signature header values and an optional tolerance in seconds (default 300).

import com.themona.monapay.WebhookVerifier;

WebhookVerifier.Result result = WebhookVerifier.verifyWebhook(rawBody, timestamp, signature, secret);
if (!result.isOk()) {
    // respond with HTTP 401
}
Object payload = result.getPayload();

A Spring Boot controller is in examples/SpringBootWebhookController.java. It is an integration example and is not part of the SDK build.

Configuration

MonaPay.fromEnv() reads:

Variable	Purpose
MONAPAY_CLIENT_ID, MONAPAY_CLIENT_SECRET	API key credentials (recommended)
MONAPAY_USERNAME, MONAPAY_PASSWORD	Legacy password login; does not work for accounts with 2FA enabled
MONAPAY_BASE_URL	API base URL, defaults to https://api.monapay.vn

Documentation: https://monapay.vn/docs

Development

The self-test needs no JUnit or Maven dependencies:

rm -rf build && mkdir build
javac --release 11 -d build $(find src/main/java src/test/java -name '*.java')
java -cp build com.themona.monapay.SelfTest

License

MIT

MONA Pay is part of MONA Cloud by The MONA Group.