Rocketfuel SDK (Node.js)

A secure and minimal Node.js SDK to interact with Rocketfuel payment APIs. (This SDK is for Node.js server-side usage.)

Installation

npm i @rkfl/transact-server

Documentation

Click here for more detailed Documentation

Usage

Create order

import { Rocketfuel } from '@rocketfuel/plugin';

const client = new Rocketfuel({
  clientId: 'YOUR_ID',
  clientSecret: 'YOUR_SECRET',
  merchantId: 'YOUR_MERCHANT_ID',
  domain: 'production' // or 'sandbox'
});

const orderData = {
  amount: "10",
  currency: "USD",
  cart: [
    {
      id: "iphone_14_pro_max",
      name: "iPhone 14 Pro Max",
      price: "10",
      quantity: 1
    }
  ],
  customerInfo: {
    name: "John Doe",
    email: "[email protected]"
  },
  customParameter: {
    returnMethod: "GET",
    params: [
      {
        name: "submerchant",
        value: "mobilesale"
      }
    ]
  },
  merchant_id: '14ec584d-53af-476d-aacd-2b7f025cf21b'
};

const result = await client.createOrder(orderData);

Transaction Lookup

To check or confirm the transaction status using order id or Rocketfuel provided transaction id

async function checkTransaction(txId) {
  try {
    const result = await client.transactionLookup(txId, 'ORDERID');
    console.log('Transaction Details:', result);
    // Process the transaction details as needed
  } catch (error) {
    console.error('Error fetching transaction details:', error.message);
  }
}
​
// Example call:
checkTransaction('12345ABC');

Webook Verification

Use this function to verify that a webhook is valid and trusted before processing its contents. It prevents spoofed requests, data tampering, and unauthorized events. This function returns true if the signature is valid, otherwise false.

function handleWebhook(req, res) {
  const isValid = client.verifyWebhookSignature(req.body);

  if (!isValid) {
    console.warn('Webhook signature verification failed');
    return res.status(403).send('Invalid signature');
  }

  const payload = JSON.parse(req.body.data.data);
  console.log('Verified Webhook Payload:', payload);

  // Process your payload
  res.status(200).send('Webhook received');
}

Payouts SDK (Fiat, Crypto & Admin)

The payouts SDK lets you invite payees, manage KYC, allocate/administer balances, and send fiat or crypto payouts using a single high-level client.

Payout client setup

import { RocketfuelPayouts } from '@rkfl/transact-server';

const payouts = new RocketfuelPayouts({
  clientId: 'YOUR_ID',
  clientSecret: 'YOUR_SECRET',
  merchantId: 'YOUR_MERCHANT_ID',
  environment: 'sandbox', // 'production' | 'qa' | 'preprod' | 'sandbox'
});

The RocketfuelPayouts client exposes three scoped clients:

• Fiat payouts: payouts.fiat
• Crypto payouts: payouts.crypto
• Admin operations: payouts.admin

Fiat payouts (bank payouts)

// Get bank configuration for a payee (optional destinationRecordId for editing an existing destination)
const bankConfig = await payouts.fiat.getBankConfiguration({
  payeeId: 'payee-id',
  country: 'US',
  currency: 'USD',
});

// Save/update bank details (shape matches SaveBankDetailsPayload — bankDetail, personalDetail, currency, country, …)
await payouts.fiat.saveBankDetails(
  'payee-id',
  {
    currency: 'USD',
    country: 'US',
    bankDetail: {
      bankAccountId: '…',
      bankId: '…',
      // …fields from bank configuration
    },
    personalDetail: {
      firstName: 'Jane',
      lastName: 'Doe',
      address: '…',
      // …as required by the API
    },
  },
  // optional: { oldDestinationRecordId: '…' } when replacing an existing destination
);

// Get transfer fee quote (query supplies routing context; body uses account token from saved bank details)
const feeQuote = await payouts.fiat.getTransferFee(
  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
  {
    currency: 'USD',
    accountToken: 'token-from-bank-flow',
    amount: '100.00',
    // destinationRecordId: '…', // optional
  },
);

// Send a fiat transfer
const transferResult = await payouts.fiat.transfer(
  { payeeId: 'payee-id', country: 'US', currency: 'USD' },
  {
    accountToken: 'token-from-bank-flow',
    amount: '100.00',
    currency: 'USD',
    recordId: 'destination-or-payment-record-id',
    // requireAllocation: true, // optional — creates allocation then transfer when true
    // destinationRecordId: '…',   // optional
  },
);

// Check transfer status (fiat or generic payout)
const status = await payouts.fiat.getTransferStatus('order-id', 'payee-id');

Other fiat helpers on payouts.fiat: getStatus (payout service availability/fees), shouldShowExternalPayeeForm, createPayeeUserExternal, getPublicCountries, getCountries, getCurrencies, deleteBankDetails, listBankDetails, getPaymentMethods, getFiatOptions, getFileUploadUrl, getComplianceStatus.

Crypto payouts

Payload fields follow KnowYourAddressPayload, CryptoTransferFeePayload, CryptoTransferCheckPayload, and CryptoTransferPayload in the SDK (walletAddress, cryptoCurrency, cryptoNetwork, etc.).

// Get payout currencies available for a payee
const currencies = await payouts.crypto.getCurrencies('payee-id');

// Optionally check address risk/compliance
await payouts.crypto.checkAddress({
  walletAddress: '0x…',
  currency: 'ETH',
});

// Get crypto transfer fee quote (amount is a number)
const cryptoFee = await payouts.crypto.getTransferFee('payee-id', {
  amount: 10,
  cryptoCurrency: 'ETH',
  cryptoNetwork: 'ETH',
});

// Prepare/validate transfer
const check = await payouts.crypto.checkTransfer('payee-id', {
  amount: '10',
  currency: 'ETH',
  cryptoCurrency: 'ETH',
  cryptoNetwork: 'ETH',
  walletAddress: '0x…',
});

// Execute crypto transfer
const tx = await payouts.crypto.transfer('payee-id', {
  amount: '10',
  currency: 'ETH',
  cryptoCurrency: 'ETH',
  cryptoNetwork: 'ETH',
  walletAddress: '0x…',
  // requireAllocation: true, // optional
});

// Check transfer status (crypto or generic payout)
const cryptoStatus = await payouts.crypto.getTransferStatus('order-id', 'payee-id');

Payout admin operations

// Invite a new payee (InvitePayeePayload: firstName, lastName, extra.email, extra.refId, …)
const newPayee = await payouts.admin.invitePayee({
  firstName: 'Jane',
  lastName: 'Doe',
  extra: {
    email: '[email protected]',
    refId: 'your-reference-id',
  },
});

// Submit KYC for a payee (PayeeKycPayload: referenceId, type, kycData)
await payouts.admin.submitPayeeKyc({
  referenceId: 'payee-or-flow-reference-id',
  type: 'payee',
  kycData: {
    /* … */
  },
});

// Get a payee's internal balance
const payeeBalance = await payouts.admin.getPayeeBalance('payee-id');

// Get overall payout admin balance and running balance
const adminBalance = await payouts.admin.getBalance();
const runningBalance = await payouts.admin.getRunningBalance();

// Create an allocation transfer (descriptor, label are required)
const allocation = await payouts.admin.createTransferAllocation({
  payeeId: 'payee-id',
  amount: '100.00',
  currency: 'USD',
  descriptor: 'Allocation description',
  label: 'Label',
});

// Allocate / retry a transfer allocation
await payouts.admin.allocateTransfer(allocation.id, {
  retryStatus: false,
  payeeId: 'payee-id',
});

Payout webhook verification & events

Use the payout webhook helper to validate webhook signatures and use typed event names:

import {
  PayoutWebhookVerifier,
  PAYOUT_WEBHOOK_EVENT_TYPE,
  PAYOUT_WEBHOOK_EVENTS,
} from '@rkfl/transact-server';

function handlePayoutWebhook(req, res) {
  const isValid = PayoutWebhookVerifier.verify(req.body);

  if (!isValid) {
    console.warn('Payout webhook signature verification failed');
    return res.status(403).send('Invalid signature');
  }

  // Top-level event metadata
  const { event, notificationType, timestamp } = req.body;

  // Canonical payload string signed by Rocketfuel
  const payload = JSON.parse(req.body.data);

  if (event === PAYOUT_WEBHOOK_EVENTS.PayoutStatusChange) {
    // handle payout status change
  }

  return res.status(200).send('OK');
}

📄 License

MIT License © RocketFuel Blockchain, Inc.