Payouts

Rocketfuel Payouts provides a secure server-side flow for sending fiat bank transfers and crypto payouts to payees. The SDK includes APIs for payee onboarding, bank account management, payout execution, transfer tracking, KYC handling, balance management, and webhook verification.

The SDK supports both fiat and crypto payout flows while automatically handling authentication and token refresh internally.

Package: @rkfl/transact-server Entry class: RocketfuelPayouts Sub-clients: fiat, crypto, admin Related exports: PayoutWebhookVerifier, PAYOUT_WEBHOOK_EVENT_TYPE, PAYOUT_WEBHOOK_EVENTS

---

1. Install and construct the client

Follow the installation guide from here - Link

2. Function index (quick map)

Namespace	Function	Description
payouts.fiat	getBankConfiguration	Load bank account form configuration for a payee.
payouts.fiat	saveBankDetails	Save or update payee bank details.
payouts.fiat	listBankDetails	List saved bank accounts for a payee.
payouts.fiat	deleteBankDetails	Delete a saved bank account.
payouts.fiat	getTransferFee	Fetch payout fee estimate.
payouts.fiat	transfer	Execute fiat payout transfer.
payouts.fiat	getTransferStatus	Get payout transfer status.
payouts.crypto	getCurrencies	Get supported crypto payout currencies.
payouts.crypto	checkAddress	Validate wallet address risk/compliance.
payouts.crypto	getTransferFee	Fetch crypto payout fee estimate.
payouts.crypto	checkTransfer	Validate crypto payout before execution.
payouts.crypto	transfer	Execute crypto payout transfer.
payouts.admin	invitePayee	Invite and create a new payee.
payouts.admin	submitPayeeKyc	Submit payee KYC details.
payouts.admin	getPayeeBalance	Get payee balance.
payouts.admin	getBalance	Get merchant payout balance.
payouts.admin	createTransferAllocation	Create payout allocation.
PayoutWebhookVerifier.verify	Verify webhook signatures before processing payout events.

3. Admin APIs

Manage payees, balances, KYC, and payout allocations.

3.1 Invite Payee

 await payouts.admin.invitePayee({
    firstName: 'Jane',
    lastName: 'Doe',
    extra: {
      email: '[email protected]',
      refId: 'internal-ref-id',
    },
  });

3.2 Register Payee with Payouts

await payouts.fiat.createPayeeUserExternal({
      payeeId,
      fName: 'Jane',
      lName: 'Doe',
      email: '[email protected]',
      country: 'USA',
    });

3.3 Submit Payee KYC

 await payouts.admin.submitPayeeKyc({
    referenceId: 'PAYEE_REFERENCE_ID',
    type: 'payee',
    kycData: {},
  });

---

3.4 Get Merchant Balance

payouts.admin.getBalance();

---

4. Fiat Payout Flow

Typical flow: discover fields → save bank details → quote fee → transfer → poll status.

Typical payout flow:

1. Load bank configuration

2. Save payee bank details

3. Fetch payout fee

4. Execute transfer

5. Poll payout status

6. Handle webhook events

4.1 Get Bank Configuration

Fetch the required bank account and personal detail schema for a payee.

const form = await payouts.fiat.getBankConfiguration({
    payeeId,
    country: 'US',
    currency: 'USD',
  });

---

4.2 Save Bank Details

Save payee bank and personal information.

 const saved = await payouts.fiat.saveBankDetails(
    payeeId,
    {
      currency: 'USD',
      country: 'US',
      bankDetail: {
        bankAccountId: 'BANK_ACCOUNT_ID',
        bankId: 'BANK_ID',
      },
      personalDetail: {
        firstName: 'Jane',
        lastName: 'Doe',
        address: '123 Main St',
      },
    }
  );

Example Payload

{
  "currency": "USD",
  "country": "US",
  "bankDetail": {
    "bankAccountId": "BANK_ACCOUNT_ID",
    "bankId": "BANK_ID"
  },
  "personalDetail": {
    "firstName": "Jane",
    "lastName": "Doe",
    "address": "123 Main St"
  }
}

---

4.3 Get Transfer Fee

Fetch payout fee estimate before executing transfer.

const fee = await payouts.fiat.getTransferFee(
    {
      payeeId,
      country: 'US',
      currency: 'USD',
    },
    {
      currency: 'USD',
      accountToken,
      amount: '100.00',
    }
);

---

4.4 Execute Fiat Transfer

Execute a fiat bank payout.

const transfer = await payouts.fiat.transfer(
    {
      payeeId,
      country: 'US',
      currency: 'USD',
    },
    {
      accountToken,
      amount: '100.00',
      currency: 'USD',
      recordId,
    }
  )

Example Response

{  "success": true,  "orderId": "payout_order_123456" }

4.5 Get Transfer Status

Retrieve payout status using order ID and payee ID.

await payouts.fiat.getTransferStatus(orderId, payeeId);

Payout Statuses

Status	Description
0	Payout is pending
1	Payout completed successfully
-1	Payout failed

Refer to the webhook section for real-time payout status updates.

---

5. Crypto Payout Flow

Typical crypto payout flow:

1. Fetch supported currencies

2. Validate wallet address

3. Fetch transfer fee

4. Validate transfer

5. Execute payout

6. Poll transfer status

5.1 Get Supported Crypto Currencies

payouts.crypto.getCurrencies(payeeId);

5.2 Validate Wallet Address

await payouts.crypto.checkAddress({
    walletAddress: '0x0000000000000000000000000000000000000000',
    currency: 'ETH',
 });

5.3 Execute Crypto Transfer

return payouts.crypto.transfer(payeeId, {
    amount: '10',
    currency: 'ETH',
    cryptoCurrency: 'ETH',
    cryptoNetwork: 'ETH',
    walletAddress: '0x0000000000000000000000000000000000000000',
 });

---

6. Payout Webhooks

Always verify webhook signatures before processing payout events.

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

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

  if (!isValid) {
    return res.status(403).send('invalid signature');
  }

  const payload = JSON.parse(String(req.body.data));
  const event = req.body.event;

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

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

Supported Webhook Events

Event	Description
PayeeAdded	Triggered when a payee is created
PayeeKycStarted	Triggered when KYC starts
PayeeKycStatusChange	Triggered when KYC status changes
PayeeFundAllocated	Triggered when funds are allocated
PayoutStarted	Triggered when payout processing starts
PayoutStatusChange	Triggered when payout status changes

---

7. Errors

Failed SDK requests throw an Error object with HTTP status information.

Always wrap SDK calls with try/catch.

try {
  const result = await payouts.fiat.transfer(query, payload);
  console.log(result);
} catch (err) {
  console.error(err);
}

---