Input, field, and event reference

This page is the field-level companion to Feature clients. ! in a GraphQL type means the server requires that field. A server may enforce additional conditional rules after GraphQL validation, as noted below. The backend schema is the source of truth; confirm these inputs against the version deployed at your endpoint.

SDK setup#

Authentication and two-factor authentication#

Login#

const session = await sdk.auth.login({
  email: 'you@example.com',
  password: passwordFromSecureInput,
  twoFactorCode, // omit when 2FA is not enabled
});

2FA operations#

Keep setup secrets and authenticator recovery material private. Use the authenticated user's own ID for ID-based 2FA calls; the backend's ownership guard must reject attempts to operate on another account. Do not log setup responses, one-time codes, or login payloads.

Step-up verification#

Some sensitive operations require a fresh 2FA code even when the user is already signed in. These are the operations the server currently gates:

• sdk.wallet.withdraw and sdk.wallet.transfer
• The bank withdrawal (manualWithdrawalCreate)
• Admin wallet withdrawals

When the server requires a code, it returns an error whose message starts with STEP_UP_REQUIRED. The SDK then calls getStepUpCode(message), retries the request with the X-Step-Up-Code header, and makes up to three attempts in total.

import { MalonlinSDK, StepUpRequiredError } from 'malonlin-sdk';

const sdk = new MalonlinSDK({
  endpoint,
  getAccessToken,
  deviceId: await getOrCreateInstallId(),
  getStepUpCode: async (message) => askUserForAuthenticatorCode(message),
});

try {
  await sdk.wallet.withdraw({ amount, currency: 'ZAR' });
} catch (error) {
  if (error instanceof StepUpRequiredError && error.isNetworkChange) {
    // The network changed. Ask the user to sign in again with a 2FA code.
  }
}

• If getStepUpCode is not set, or it returns null, the SDK throws StepUpRequiredError.
• When isNetworkChange is true, the SDK does not prompt. The server has rejected the session because its network changed, so send the user through a fresh sign-in.
• Retries keep the same idempotency key. The server rejects step-up before it writes anything to the ledger, so a retry is safe.

Cart and checkout#

Authenticated self-service inputs#

sdk.getOrCreateMyCart() and sdk.getMyCart() resolve the signed-in user's cart without accepting a caller-supplied user ID. sdk.myCheckoutReadiness(input) is a preview only; the server recalculates totals and validates ownership at checkout. sdk.checkoutMyCart(input) uses the self-scoped mutation and sends an idempotency key. A successful checkout response is authoritative only when the server says the order is paid.

Product create and update fields#

CreateProductDto and UpdateProductDto accept the following fields. GraphQL requires only name and price when creating a product; the backend additionally enforces conditional rules by productType. On update, every listed field is optional.

Nested input details:

See Product Types and Capabilities for type normalization and fulfillment behavior.

Wallet, payment, and subscription inputs#

Wallet transfer and withdrawal#

The sdk.wallet.myWallet() and sdk.wallet.myTransactions() methods are self-scoped and do not accept a user ID. Prefer them over ID-based wallet queries in user-facing applications.

withdraw, transfer, and bank withdrawals (manualWithdrawalCreate) need a step-up 2FA code. Configure getStepUpCode before calling them; see Step-up verification.

Secure payment verification request#

This creates a multi-party verification request; it is not a card gateway or proof that the payment has completed. Poll paymentVerificationStatus through an authenticated backend flow and act only on a terminal server status. The primary and website API deployments enforce that the request/status belongs to the authenticated user.

Ozow wallet deposit modal#

sdk.wallet.startOzowDepositModal(userId, input) calls the authenticated ozowPayInModalStart operation. The required userId must be the signed-in user's ID. Never calculate the Ozow hash or expose OZOW_PRIVATE_KEY in a client.

The API returns paymentUrl, server-signed postData, transactionReference, and bankReference. Use Ozow's official browser integration (createPaymentModal or createPaymentFrame) to render its hosted payment UX; Malonlin's SDK itself is framework-agnostic and does not inject an iframe or control Ozow's payment page.

const started = await sdk.wallet.startOzowDepositModal(userId, { amount: 250 });

// Load the official Ozow integration script in response to the user's action,
// then hand the server-generated values directly to that provider SDK.
const ozow = new window.Ozow();
ozow.createPaymentModal(started.paymentUrl, started.postData);

// Treat the browser callback as a UX signal only. Reconcile by reference with
// the backend before showing funds as available.
const verification = await sdk.wallet.ozowTransaction(started.transactionReference);

Do not build a custom frame for the payment form, rewrite provider parameters, trust a browser redirect as payment confirmation, or show wallet funds until the Ozow callback/reconciliation confirms completion. A payment frame is cross-origin/provider-controlled; CSP and script-loading policy belong to the consuming application.

Subscription purchase#

Use sdk.subscriptions.plans(), addons(), and the relevant self/store subscription context before purchase. The server checks eligibility and entitlements; a client-side plan display is not authorization.

Customer profile and address inputs#

Prefer myCustomer, myCustomerAddresses, createMyCustomer, and createMyCustomerAddress for the authenticated profile. Prefer myBillingAddresses/myShippingAddresses and their matching createMy*, updateMy*, and removeMy* methods for checkout addresses; these avoid carrying another user's raw ID through the application.

Ratings#

Create and update#

CreateRatingInput fields:

UpdateRatingInput has optional rating, title, comment, pros, cons, mediaUrls, and wouldRecommend fields. A review is not accepted merely because these input fields are present: the server requires a completed eligible fulfillment and enforces one review per source. VoteRatingInput requires ratingId: String!, userId: String!, and isHelpful: Boolean!; the user must be the authenticated voter, and voting is single-use.

Webhook subscriber fields and event schemas#

Subscriber management#

The one-time webhook secret is returned only when the subscription is created. Store it server-side; never send it to a browser or mobile client.

Outbound payment.completed webhook#

The backend delivers only after isPaid: true, retries non-2xx/network failures up to eight times, and does not wait for the subscriber during checkout. See Events and webhooks for signature verification, raw-body handling, and idempotent receiver code.

Local SDK event map#

These are in-process events from sdk.on; they are not backend webhooks or GraphQL subscriptions.

Event handlers run in the SDK process only. Avoid logging auth headers, personal payload data, secrets, or payment details from listeners.

Feature boundary cross-check#

This SDK covers the Malonlin API domains and feature flows that are represented by the deployed GraphQL schema and the website API surface. It does not turn every backend administrative or internal operation into a client feature; staff-only configuration, reconciliation, and maintenance actions remain behind their server authorization boundary.

The current checked-in malonlin-n and website frontend contain no mini-app API or mini-app route contract to expose. Mini-app support is therefore not currently an SDK feature; it should be added only after a backend schema and authorization flow exist. Likewise, browser framework hooks and presentation-only settings are app-specific, not framework-neutral SDK APIs.