Rocketfuel SDK Client

1. Introduction

The Rocketfuel SDK enables quick integration of payment and verification features into your web app or site. Use it to display age verification prompts or securely process payments within your flow.

Demo: https://zkp-demo.rocketfuel.inc/

You can use the SDK:

• Via CDN script in traditional HTML/JS projects.

• Via npm package in React, Vue, Angular, or other frontend frameworks.

Features supported:

• Age Verification (AGE_VERIFICATION)

• Payment Collection (PAYIN)

Important: You must whitelist the domain from which you are accessing the SDK in your merchant portal. Without whitelisting, the SDK will not work. For detailed instructions, please see the Domain Whitelisting Guide.

2. Integration

a. Installation and import

React (or Module Bundler) Integration

npm install @rkfl/transact-client

import { RkflPlugin } from '@rkfl/transact-client';

Or add the SDK at the bottom of your page:

<script src="https://sdk.rocketfuel.inc/rkfl-transact-client.min-1.1.0.js" defer></script>

Using defer ensures the script loads after the HTML has been parsed. (Not mandatory).

b. Preparing Container Elements

Create HTML elements with IDs where the SDK will render widgets:

<div id="verification-container"></div> <!-- for age verification -->
<div id="sdk-buttons-payin"></div>       <!-- for payment buttons -->

<!-- or if you want to load both the button in the same container, 
You can use the code below -->

<div id="sdk-buttons-container"></div> 

c. Initialize SDK with Plugins

Example initialization to enable AGE_VERIFICATION and PAYIN at the same time:

const agePlugin = {
  feature: "AGE_VERIFICATION",
  containerId: "verification-container" // (optional) default: sdk-buttons-container
  // inject: false //(option) @default - true 
};

const payinPlugin = {
  feature: "PAYIN",
  containerId: "sdk-buttons-payin" // (optional) default: sdk-buttons-container
  // inject: false //(option) @default - true
};

const sdk = new RkflPlugin({
  clientId: 'YOUR_CLIENT_ID',
  environment: 'sandbox',  // (optional @default - production  'production' or 'sandbox'.
  plugins: [agePlugin, payinPlugin],
  // redirect: false, // Optional redirect flow @default - false
});
await sdk.init(); // async process that returns true/false 
// if the initialization is successful true is returned else, false
/* 
  Using the "Pay In" feature:

  1. Make sure the cart data is already prepared.
  2. Call your backend API to generate a UUID for the transaction.
     - Note: UUIDs should always be generated on the backend 
     for security and consistency.
*/
sdk.prepareOrder(uuid) // this will launch the payment widget for the Pay In feature

/* 
If you pass an inject parameter as false in the age verification/payment plugin options,
The button for age verification/payment will not be injected into your website.
You can use a custom function to trigger the age verification/payment process.
*/
// NOTE: Make sure your RkflPlugin is initialized before using this function
sdk.launchAgeVerificationWidget() // use this to customize the launch of age verification
sdk.launchPaymentWidget(uuid); // use this to customize the launch of payment widget

d. Trigger the age verification/payment modal manually

The launchAgeVerificationWidget The function is used to trigger a modal or iframe-based age verification UI. It is typically called when a user attempts to access age-restricted content or initiate an action that requires age verification, such as connecting a wallet.

The launchPaymentWidget function is used to trigger a modal or iframe-based payment interface. It is typically called when a user initiates a transaction, such as making a purchase, subscribing to a service, or completing a checkout flow. The widget handles secure payment collection.

Note: Make sure your SDK is initialized, and if you don't want to use the injected button, you can pass the inject parameter as false with the plugin object, for example:

const agePlugin = {
  feature: "AGE_VERIFICATION",
  containerId: "verification-container",
  inject: false
};
const payinPlugin = {
  feature: "PAYIN",
  containerId: "sdk-buttons-payin",
  inject: false
};

e. Setting up user info

You can optionally provide user details before launching the widget using the setUserInfo() method. This is useful if you want to prefill user information or associate the verification with a specific refId in your system.

Note:

1. If setUserInfo() is not called, the widget will still launch and return results normally. In this case, the user ref is automatically created and returned at the verification success response.

sdk.setUserInfo({
  email: '[email protected]', // Optional: Prefills the user's email
  refId: '12345678'          // Optional: Your internal reference ID
});

<button onclick="sdk.launchAgeVerificationWidget()">Verify Now</button>

f. Age Verification Status Check

The sdk.verifyAgeVerification function allows the client application (e.g., browser frontend) to check the status of an age verification request by passing the auditId received from the verification flow.

It returns the same verification result object as the server-side function and can be used to unlock restricted UI elements or content.

sdk.verifyAgeVerification(event.data.auditId).then(res => {
              console.log('Age verification response:', res);
})

Response:

{
"id": "d27d3b78-cd99-42f9-87f6-2a17b01f7820",
"status": "status_verified",
"verifiedOn": "2025-09-10T17:59:37.002Z",
"createdAt": "2025-09-10T17:59:21.122Z",
"timezone": "UTC"
}

Field	Type	Description
id	string	Unique identifier of the verification record (audit ID).
status	string	Current verification status (see Status Values below).
verifiedOn	string (ISO datetime)	Timestamp when the user was successfully verified (only available if verified).
createdAt	string (ISO datetime)	Timestamp when the verification request was created.
timezone	string	Timezone used in the verification process.

Status	Description
expired	The verification session expired before completion.
status_initiated	Age verification process has started but not yet completed.
status_verified	User successfully completed age verification.
status_failed	Age verification attempt failed.
widget_started	The verification widget was launched, but final status not yet determined.

3. Window Events

NOTE: This feature is only available when you don't use the redirect mode. i.e, your redirect : true

• Both integrations communicate important state changes (like age verification results or payment completion) via the same standard window event messages.

• You listen to them using the same code:

window.addEventListener('message', (event) => {
  const data = event.data;

  // Age verification result
  if (data.type === "AGE_VERIFICATION") {
    if (data.verified === true) {
      console.log("User is age verified ✅");
      console.log("refId:", data.refId); // Always returned 
      // Save or use refId for future reference
      // if the ref id is passed via setUserInfo, the same will be returned
      // if the ref id was not passed, a new ref id is returned.
    } else {
      console.log("User failed age verification ❌");
    }
  }

  // Payment result (only if payment flow is used)
  if (data.type === "rocketfuel_result_ok" && data.paymentCompleted === 1) {
    console.log("Payment completed successfully 💰");
  }
});

Allowed Domains Validation for PostMessage Events

1. Define allowed domains Only production and sandbox payment domains are allowed:

const allowedDomains = [
  "https://payments.rocketfuel.inc",
  "https://payments-sandbox.rocketfuelblockchain.com",
];

1. Validate message origin Every incoming message is checked against the allowedDomains array. Messages from untrusted origins are ignored and logged:

if (!allowedDomains.includes(event.origin)) {
  console.warn('Message from untrusted origin:', event.origin);
  return;
}

• Security: Prevents scripts from unknown domains from sending messages or executing actions in your app.

• Controlled communication: Ensures only production and sandbox payment environments can interact with your client via postMessage.

Sample Success Response for Age Verification:

{
    "type": "AGE_VERIFICATION",
    "verified": true,
    "auditId": "5eb81fd8-4cf8-46f3-a09a-7d9f68aeb369",
    "refId": "5a3752af-58b8-4a3d-9700-b90afe6e67a6"
}

Sample Event for Audit log ID

When a user initiates the age verification flow, the SDK emits a window event containing the generated audit ID.

Developers can listen for this event, store the auditId, and later use it with the verifyAgeVerification function to check the user’s verification status.

window.addEventListener("message", (event) => {
  if (event.data?.type === "AUDIT_ID_GENERATED") {
    console.log("📌 Audit ID received:", event.data.auditId);
    console.log("User Ref ID:", event.data.refId);

    // Store auditId for later verification checks
    localStorage.setItem("auditId", event.data.auditId);
  }
});

Event data

{
  "type": "AUDIT_ID_GENERATED",
  "auditId": "<audit-id>",
  "refId": "<user-reference-id>"
}

Sample Success Response for Payment Confirmation:

Upon receiving the transaction event via postMessage from the payment widget, you should move the transaction to a pending state. This does not indicate the final status of the transaction. To track the final outcome, you should either perform a transaction lookup using the provided API or configure a server-side webhook to receive real-time updates on the transaction status. For quick integration, you can utilize the server-side SDK in Node.js.

{
  "type": "rocketfuel_result_ok",
  "response": {
    "paymentMode": "Wallet",
    "status": "completed",
    "recievedAmount": null,
    "currency": "ETH",
    "offerId": "a98afcf0-9d8a-492a-a8b4-5658eafc954f"
  },
  "paymentCompleted": 1
}

Every Rocketfuel SDK plugin you use—whether initialized through a <script> tag or imported as a JavaScript module—will send events to the window when a user completes a step (age check, checkout, etc.), using the same event types and payloads. You can write your logic and UI reactions for these events in a single, unified way across your full app.

Additional Integration Tips

• Order Management: Store cart/order details in localStorage or your app state, and use SDKs prepareOrder(uuid) (for PAYIN) with a backend-generated order UUID to track transactions.

• Backend Invoice Generation: Call your backend API to generate an invoice/order UUID, then pass it to sdk.prepareOrder(uuid) to link the frontend SDK with the backend order data.

• Redirect Flow: Optionally enable redirect: true in SDK options for redirect-based flows instead of inline widgets.

• Security:

  • Keep clientId and merchantId secure, do not expose sensitive data publicly.

  • Only accept window messages from trusted origins.

Summary of Important Fields

1. feature : (required) What plugin to load, e.g., "AGE_VERIFICATION", "PAYIN"

2. containerId: (optional) DOM element ID where the widget will be rendered. default: sdk-buttons-container

3. clientId : (required) Your Rocketfuel client ID.

4. merchantId: (required) Merchant ID (required for payments).

5. environment :(optional) 'production', 'sandbox' default: 'production'.

6. redirect: (optional) Optional boolean to enable redirect flows. default: true