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.0.5.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>

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,
  "data": {
    // proof of validation
  },
  "refId": "2197af9d-6ded-4c62-bee2-08b32e812b65"
}

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

PreviousRocketfuel SDK nodejsNextOverview

Last updated

Was this helpful?