On-Device Integration — Intent API

Two ways to integrate

Pick the path that matches where your code runs. Many partners use both — the Intent API on the POS device, the REST SDK from their backend.

Android — paycore SDK

com.payus.paycore wraps the intent handshake in a typed, coroutine-friendly client. Download the paycore (and, for Compose, paycore-compose) AAR from the v1.0.0 release — verify it against the published SHA256SUMS— drop it into your module's libs/, then:

// app/build.gradle.kts
dependencies {
    implementation(files("libs/paycore-1.0.0.aar"))
    implementation(files("libs/paycore-compose-1.0.0.aar")) // only if using Compose
}
// paycore-1.0.0.aar        sha256 26585e8208510049f36422025c358a6d6ab73d3e14cd0fd27736333b4039bef0
// paycore-compose-1.0.0.aar sha256 6200554991e1686d409045408cbc35431f8453f703098a732d6508140ad29516

Maven Central publication (a plain com.payus:paycore:1.0.0 coordinate) is coming; until then the GitHub release above is the authoritative source.

// Kotlin — from any ComponentActivity
val client = PayUsClient.from(this)

val result = client.pay(
    PayUsPayRequest(
        amountMinor = 1250,          // $12.50 in cents (required, > 0)
        currency = "NZD",            // optional → terminal default
        orderId = "ORD-42",          // optional → PayUs auto-generates
        gateway = null,              // null → PayUs shows its picker
    )
)

when (result) {
    is PayUsResult.PaymentDone -> store(result.transactionId, result.referenceId)
    is PayUsResult.Cancelled   -> toast("Cancelled: ${result.reason}")
    is PayUsResult.NotActivated-> promptActivatePayUs()
    is PayUsResult.ApiDisabled -> toast("Enable Intent API in PayUs settings")
    is PayUsResult.NotInstalled-> toast("PayUs is not installed")
    is PayUsResult.Failed      -> toast("${result.errorCode}: ${result.message}")
    else                       -> { /* other actions */ }
}

Other calls: generateQr(), query(referenceId), cancel(referenceId), refund(PayUsRefundRequest(…)), listGateways(), getTerminalInfo(). Java callers use the Callback overloads; non-Activity callers use PayUsClient.forContext(appContext).

Android — paycore-compose (Jetpack Compose)

com.payus.paycore.composewraps paycore in Composable launchers so Compose partners don't juggle rememberLauncherForActivityResult themselves. One remember*Launcherper action — call the returned function to fire. There's also a drop-in PayUsPaymentButton.

// Kotlin — anywhere inside a @Composable
val payLauncher = rememberPayUsPayLauncher { result ->
    when (result) {
        is PayUsResult.PaymentDone  -> store(result.transactionId, result.referenceId)
        is PayUsResult.Cancelled    -> toast("Cancelled: ${result.reason}")
        is PayUsResult.NotActivated -> promptActivatePayUs()
        is PayUsResult.ApiDisabled  -> toast("Enable Intent API in PayUs settings")
        is PayUsResult.NotInstalled -> toast("PayUs is not installed")
        is PayUsResult.Failed       -> toast("${result.errorCode}: ${result.message}")
        else                        -> { /* InvalidRequest / TerminalBusy */ }
    }
}

Button(onClick = {
    payLauncher(PayUsPayRequest(amountMinor = 1250, currency = "NZD", orderId = "ORD-42"))
}) { Text("Pay $12.50") }

Or skip the launcher entirely and drop in the pre-styled button — same result callback, handles its own lifecycle. hideWhenPayUsMissing = truekeeps the button out of your UI on devices that don't have PayUs installed.

PayUsPaymentButton(
    request = PayUsPayRequest(amountMinor = 1250, currency = "NZD"),
    onResult = { result -> /* same when-match as above */ },
    text = "Pay with PayUs",             // optional — defaults to this
    hideWhenPayUsMissing = true,         // optional — hides vs disables
    // colors / shape / contentPadding / icon all override MaterialTheme
)

Flutter — payus_pay plugin

# pubspec.yaml — from the v1.0.0 git tag (pub.dev publication is a follow-up)
dependencies:
  payus_pay:
    git:
      url: https://github.com/vivekkhare/PayUs.git
      ref: v1.0.0
      path: sdk/payus_pay

// One-line button
PayUsButton(
  request: PayUsPayRequest(amountMinor: 1250, currency: 'NZD', orderId: 'ORD-42'),
  onResult: (r) => switch (r) { /* PayUsResult variants */ },
)

// …or programmatic
final client = PayUsClient();
final result = await client.pay(PayUsPayRequest(amountMinor: 1250));

Raw intent (no SDK)

The SDKs are thin wrappers over a plain startActivityForResult. You can build the intent by hand:

val intent = Intent("com.payus.pos.ACTION_PAY").apply {
    setPackage("com.payus.pos")       // the installed PayUs POS app id ("com.payus.pos.dev" for the dev build)
    putExtra("amount", 1250L)         // minor units (cents) — required
    putExtra("currency", "NZD")       // optional
    putExtra("gateway", "wechat")     // optional — omit to show picker
    putExtra("order_id", "ORD-42")    // optional
}
startActivityForResult(intent, REQUEST_CODE)
// onActivityResult: resultCode 0=cancelled 1=failed 2=invalid 3=not-activated

Actions

ACTION_PAY request fields

Only amountis required — everything else falls back to the terminal's configured data.

Itemised basket (line_items)

Optionally send the sale's line items with ACTION_PAY. They are persisted and shown against the transaction, and can be itemised on the printed receipt. Omit the extra entirely for no basket — behaviour is unchanged. Android intent extras can't carry a list of maps, so line_items is a single JSON-encoded string.

putExtra("line_items", JSONArray(listOf(
    mapOf("name" to "Flat White", "quantity" to "2",
          "unitPriceCents" to 550, "lineTotalCents" to 1100,
          "sku" to "COFFEE-FW", "category" to "Beverages"),
    mapOf("name" to "Muffin", "quantity" to "1",
          "unitPriceCents" to 450, "lineTotalCents" to 450, "taxCents" to 59)
).map { JSONObject(it) }).toString())

Per line: name (≤255), quantity (decimal string, weight-capable e.g. "1.25", > 0),unitPriceCents / lineTotalCents(integer cents, lineTotal tax-inclusive & after line discount), optionaltaxCents, sku (≤128),category (≤128). Max 200 lines.

Money format on the Intent surface is integer cents throughout — line amounts and the modifier extras (tip_amount, fee_amount,donation_amount, discount) are alllong cents, matching amount. (On the cloud REST surface — payNow / requestTerminal — those same modifiers are decimal strings. Don't mix the two: the same tip is 250 here and "2.50" there.)

Reconciliation is server-side and strict (±1c): sum oflineTotalCents must equalamount − tip_amount − fee_amount − donation_amount + discount. A basket is merchandise and never contains the tip, so declare the tip when it's in the charge. The PayUs backend is the sole reconciler — the terminal only checks JSON well-formedness, per-line fields and the 200-line cap before sending. A malformed basket is refused pre-send withRESULT_INVALID_REQUEST + INVALID_LINE_ITEMS; a reconciliation failure comes back as RESULT_PAYMENT_FAILED +LINE_ITEM_MISMATCHwith the server's arithmetic inerror_message.

Results per action

Every call returns a PayUsResult. The success-case subtype depends on the action — all actions can also return the shared outcomes Cancelled, Failed, InvalidRequest, NotActivated, TerminalBusy, ApiDisabled, NotInstalled.

cancel() returns the latest TransactionStatus because a late-paid QR can be SUCCESS even after you cancel — trust status over the action name.

PayUsResult.PaymentDone fields

PayUsResult.QrGenerated fields

PayUsResult.TransactionStatus fields

Returned by both query() and cancel(). status is one of PENDING, SUCCESS, FAILED, CANCELLED.

PayUsRefundRequest + RefundDone

Only referenceId is required. Omit refundAmountMinor for a full refund; set it for a partial.

client.refund(
    PayUsRefundRequest(
        referenceId = "ORD-42",
        refundAmountMinor = 500,       // null → full refund
        refundReason = "customer_return",
        refundPassword = null,         // null → terminal's default; "" → opt out
    )
)

Gateways + TerminalInfo

Error codes

Stable error_code values inside PayUsResult.Failed / InvalidRequest.

Prerequisites

See also

• Download the Intent API sample app (.zip)
• REST SDK (server-mediated QR / your own UI)
• REST payment endpoints
• Full intent contract: docs/intent-api-specification.yaml (OpenAPI)