Onyx Partner Connect SDK

Server-side access to the Onyx Partner catalogue and eSIM provisioning API.

Do not place a Partner API key in browser code. Mint short-lived embed sessions on your server.

import { createPartnerConnect } from "@onyxmobilenet/partner-connect-sdk";

const onyx = createPartnerConnect({
  environment: "sandbox",
  apiKey: process.env.ONYX_PARTNER_API_KEY!,
});

const catalogue = await onyx.catalogue.list({ country: "TH", limit: 25 });

The established @onyx/connect-sdk identity remains available for existing Onyx application integrations. @onyxmobilenet/partner-connect-sdk is the public, server-side partner API client.

Install

npm install @onyxmobilenet/partner-connect-sdk
npx onyx-partner-connect init

Set server-only environment values:

ONYX_PARTNER_ENVIRONMENT=sandbox
ONYX_PARTNER_API_KEY=onyx_sk_test_...

Run a credential and catalogue check:

npx onyx-partner-connect doctor --live

Hosted catalogue shell

Create the short-lived browser session on your server:

const session = await onyx.embedSessions.create({
  allowedOrigin: "https://nomadz.xyz",
  scopes: ["catalogue:read"],
  customerReference: "customer_123",
});

Return only session.token to the browser. Mount the headless shell:

<div id="onyx-connect"></div>
<script src="https://partner.onyxmobile.net/partner-connect/v1/onyx-connect.js"></script>
<script>
  const connect = OnyxConnect.mount({
    element: "#onyx-connect",
    environment: "sandbox",
    sessionToken,
    onSelect({ package: selectedPackage }) {
      beginCheckout(selectedPackage.packageId);
    },
  });
</script>

The shell is catalogue selection only. Your application owns customer checkout.

Provision after payment

const order = await onyx.orders.create({
  packageId,
  partnerOrderId: checkoutId,
  customerReference: customerId,
  idempotencyKey: `checkout:${checkoutId}`,
});

const deliverySession = await onyx.deliverySessions.create({
  orderId: order.orderId,
  allowedOrigin: "https://nomadz.xyz",
});

Create orders only from the server after your payment system confirms payment.

Webhooks

Read the request body as bytes or text before parsing. Verify that exact body:

import { verifyPartnerConnectWebhook } from "@onyxmobilenet/partner-connect-sdk";

const rawBody = await request.text();
const event = verifyPartnerConnectWebhook({
  body: rawBody,
  signature: request.headers.get("x-onyx-partner-signature")!,
  timestamp: request.headers.get("x-onyx-partner-timestamp")!,
  secret: process.env.ONYX_PARTNER_WEBHOOK_SECRET!,
});

Deduplicate processing by eventId. Return a 2xx response only after durable acceptance.

Environments

• Sandbox uses durable simulated provisioning and test balance.
• Production uses live provider provisioning only after Onyx activates the account.
• Sandbox keys begin onyx_sk_test_; production keys begin onyx_sk_live_.
• Embed tokens begin onyx_embed_, expire quickly, and are bound to one exact origin.

Run npx onyx-partner-connect agent-guide or open the packaged AGENTS.md for the coding-agent contract.