@tuago/node

Official Node/TypeScript SDK for Tuago — the WhatsApp-native payment collection gateway. Server-side only (uses your secret key). Money is integer minor units (kobo) as strings.

npm install @tuago/node

Quickstart

import { Tuago } from "@tuago/node";

const tuago = new Tuago({ secretKey: process.env.TUAGO_SECRET_KEY! }); // sk_test_… / sk_live_…

// Collect via bank transfer — returns a dynamic virtual account to show the payer.
const charge = await tuago.charges.create(
  { amount: 1_850_000, reference: orderId, channel: "BANK_TRANSFER" },
  { idempotencyKey: orderId },
);
console.log(charge.virtualAccount); // { bankName, accountNumber, accountName, expiresAt }

Split settlement (platforms)

Route a collection through a subaccount: the vendor's share settles to their bank, your commission to yours — one payment, automatic.

const sub = await tuago.subaccounts.create({
  businessName: "Mama Put Kitchen",
  bankCode: "058", accountNumber: "0123456789",
  splitType: "PERCENTAGE", splitValue: 1000, // you take 10% (bps)
});

await tuago.charges.create({
  amount: 1_850_000, reference: orderId,
  subaccount: sub.id,
  transactionCharge: 100_000, // optional flat commission override (kobo)
});

Headless WhatsApp checkout

Get raw payment instructions + every available method to render directly in chat (no hosted page):

const session = await tuago.checkout.create({
  amount: 1_850_000, customerEmail: "[email protected]",
  mode: "headless", subaccount: sub.id,
});
session.paymentInstructions; // VA to print in WhatsApp
session.paymentMethods;      // [{ method:"bank_transfer", ... }, { method:"ussd", ... }, { method:"card", ... }]

Webhooks

Verify the signature with the raw request body (never re-serialize):

import { constructEvent } from "@tuago/node";

app.post("/tuago-webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = constructEvent(req.body, req.header("x-ollie-signature"), process.env.TUAGO_WEBHOOK_SECRET!);
    if (event.type === "charge.success") {
      // payment landed — confirm the order, reply in WhatsApp
    }
    res.sendStatus(200);
  } catch {
    res.sendStatus(400); // bad signature
  }
});

Refunds

await tuago.refunds.create({ chargeReference: orderId, reason: "customer cancelled" });
// full or partial; unwinds every split leg server-side

Errors

Every failure throws TuagoError with a stable .code (merchant_cap_exceeded, core_unavailable, idempotency_conflict, …) and .httpStatus. Signature failures throw TuagoSignatureError.

Resources

charges · subaccounts · refunds · checkout · balance · settlements · banks