# 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:**
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`)
{% hint style="warning" %}
**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](https://docs.rocketfuel.inc/plug-ins-and-sdks/javascript-js#domain-whitelisting).
{% endhint %}
## 2. Integration
### a. Installation and import
**React (or Module Bundler) Integration**
```bash
npm install @rkfl/transact-client
```
```javascript
import { RkflPlugin } from '@rkfl/transact-client';
```
\
Or add the SDK at the bottom of your page:
```html
```
*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:
```html
```
### c. Initialize SDK with Plugins
Example initialization to enable **AGE\_VERIFICATION** and **PAYIN** at the same time:
```javascript
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:
```javascript
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.
```javascript
sdk.setUserInfo({
email: 'user@example.com', // Optional: Prefills the user's email
refId: '12345678' // Optional: Your internal reference ID
});
```
```html
```
### 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.
```javascript
sdk.verifyAgeVerification(event.data.auditId).then(res => {
console.log('Age verification response:', res);
})
```
\
**Response:**
```json
{
"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:
```javascript
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:
```javascript
const allowedDomains = [
"https://payments.rocketfuel.inc",
"https://payments-sandbox.rocketfuelblockchain.com",
];
```
2. **Validate message origin**\
Every incoming message is checked against the `allowedDomains` array. Messages from untrusted origins are ignored and logged:
```javascript
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:
```json
{
"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**.
{% hint style="info" %}
Developers can listen for this event, store the `auditId`, and later use it with the `verifyAgeVerification` function to check the user’s verification status.
{% endhint %}
```javascript
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
```json
{
"type": "AUDIT_ID_GENERATED",
"auditId": "",
"refId": ""
}
```
### **Sample Success Response for Payment Confirmation:**
{% hint style="warning" %}
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.
{% endhint %}
```json
{
"type": "rocketfuel_result_ok",
"response": {
"paymentMode": "Wallet",
"status": "completed",
"recievedAmount": null,
"currency": "ETH",
"offerId": "a98afcf0-9d8a-492a-a8b4-5658eafc954f"
},
"paymentCompleted": 1
}
```
{% hint style="info" %}
Every Rocketfuel SDK plugin you use—whether initialized through a `