# 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](/plug-ins-and-sdks/javascript-js/rocketfuel-sdk-nodejs.md)

## 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

```js
 await payouts.admin.invitePayee({
    firstName: 'Jane',
    lastName: 'Doe',
    extra: {
      email: 'jane@example.com',
      refId: 'internal-ref-id',
    },
  });
```

### 3.2 Register Payee with Payouts

```js
await payouts.fiat.createPayeeUserExternal({
      payeeId,
      fName: 'Jane',
      lName: 'Doe',
      email: 'jane@example.com',
      country: 'USA',
    });
```

### **3.3 Su**bmit Payee KYC

<pre class="language-javascript"><code class="lang-javascript"><strong> await payouts.admin.submitPayeeKyc({
</strong>    referenceId: 'PAYEE_REFERENCE_ID',
    type: 'payee',
    kycData: {},
  });
</code></pre>

***

### 3.4 Get Merchant Balance

```js
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.

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

***

### 4.2 Save Bank Details

Save payee bank and personal information.

```js
 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

```json
{
  "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.

```js
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.

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

#### Example Response

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

### 4.5 Get Transfer Status

Retrieve payout status using order ID and payee ID.

```js
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

```js
payouts.crypto.getCurrencies(payeeId);
```

### 5.2 Validate Wallet Address

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

### 5.3 Execute Crypto Transfer

```js
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.

```js
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`.

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

***

##


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rocketfuel.inc/plug-ins-and-sdks/javascript-js/rocketfuel-sdk-nodejs/payouts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.