> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orafi.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> Withdraw settled funds to a crypto wallet or saved settlement account.

## The payout object

A payout represents a withdrawal of settled funds from your Orafi account to an external wallet address. Payouts are processed on-chain in USDC.

<ResponseField name="id" type="string">
  Unique identifier for the payout.
</ResponseField>

<ResponseField name="amount" type="number">
  Payout amount in the base unit.
</ResponseField>

<ResponseField name="status" type="string" default="INITIALIZED">
  Current payout status. One of `INITIALIZED`, `COMPLETED`, or `FAILED`.
</ResponseField>

<ResponseField name="walletAddress" type="string">
  Destination wallet address the funds are sent to.
</ResponseField>

<ResponseField name="txDigest" type="string">
  On-chain transaction digest, available after the payout is processed.
</ResponseField>

<ResponseField name="method" type="string">
  Payout method. One of `CRYPTO` or `FIAT`.
</ResponseField>

<ResponseField name="transactionId" type="string">
  ID of the parent transaction record.
</ResponseField>

<ResponseField name="cryptoAccountId" type="string">
  ID of the crypto settlement account used, if applicable.
</ResponseField>

<ResponseField name="fiatAccountId" type="string">
  ID of the fiat settlement account used, if applicable.
</ResponseField>

<ResponseExample>
  ```json The payout object theme={null}
  {
    "id": "cmjpayout001",
    "amount": 5.00,
    "status": "COMPLETED",
    "walletAddress": "0x871cf48ff1847e7a...55c2d3",
    "txDigest": "5kRmC7nV...",
    "method": "CRYPTO",
    "transactionId": "cmjfu1cjv0002v8vsabc12345",
    "cryptoAccountId": "854da716-03bf-4bcf-9eba-3302208f8f36",
    "fiatAccountId": null
  }
  ```
</ResponseExample>

### Transaction sub-object

When retrieving a [Transaction](/api-reference/endpoint/transactions) with `type: "PAYOUT"`, the payout appears as a nested `payout` sub-object with these fields:

<ResponseField name="id" type="string">
  Unique identifier for the payout.
</ResponseField>

<ResponseField name="method" type="string">
  Payout method. One of `CRYPTO` or `FIAT`.
</ResponseField>

<ResponseField name="walletAddress" type="string">
  Destination wallet address. Present for crypto payouts.
</ResponseField>

<ResponseField name="txDigest" type="string">
  On-chain transaction digest. Available after payout is processed.
</ResponseField>

<ResponseField name="cryptoAccountId" type="string">
  ID of the crypto settlement account used, if applicable.
</ResponseField>

<ResponseField name="fiatAccountId" type="string">
  ID of the fiat settlement account used, if applicable.
</ResponseField>

<ResponseExample>
  ```json Payout as transaction sub-object theme={null}
  {
    "id": "cmjpayout001",
    "method": "CRYPTO",
    "walletAddress": "0x871cf48ff1847e7a...55c2d3",
    "txDigest": "5kRmC7nV...",
    "cryptoAccountId": "854da716-03bf-4bcf-9eba-3302208f8f36",
    "fiatAccountId": null
  }
  ```
</ResponseExample>

***

## Check available balances

<div className="api-method-box">
  <span className="api-method get">GET</span> `/transactions/payout/balances`
</div>

Returns your available payout balances by token. Use this to check how much you can withdraw before initiating a payout.

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET https://api.orafi.app/transactions/payout/balances \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/transactions/payout/balances", {
    headers: { "x-api-key": "ora_test_your_api_key" }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.orafi.app/transactions/payout/balances",
      headers={"x-api-key": "ora_test_your_api_key"}
  )
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Balances retrieved successfully",
    "data": [
      {
        "coinType": "USDC",
        "balance": 35192
      }
    ]
  }
  ```
</ResponseExample>

***

## Create a crypto payout

<div className="api-method-box">
  <span className="api-method post">POST</span> `/transactions/payout/crypto`
</div>

Initiates a crypto payout. There are **two supported methods**:

<Tabs>
  <Tab title="Settlement account">
    Use a previously saved crypto settlement account. **No wallet signing required.**

    Required fields: `amount`, `cryptoSettlementAccountId`
  </Tab>

  <Tab title="Direct wallet">
    Send funds to any wallet address.

    Required fields: `amount`, `walletAddress`, `network`
    **Get supported networks See [Supported Networks](/api-reference/endpoint/extras/networks)**
  </Tab>
</Tabs>

### Request body

<ParamField body="amount" type="number" required>
  Amount to withdraw.
</ParamField>

<ParamField body="cryptoSettlementAccountId" type="string">
  ID of a saved crypto settlement account. Use this **or** provide a direct wallet address --- not both.
</ParamField>

<ParamField body="walletAddress" type="string">
  Destination wallet address for the payout. Required when not using a settlement account.
</ParamField>

<ParamField body="bytes" type="string">
  Serialized message bytes signed by the wallet owner. Required with `walletAddress`.
</ParamField>

<ParamField body="signature" type="string">
  Cryptographic signature generated by signing `bytes` with the wallet's private key. Required with `walletAddress`.
</ParamField>

<ParamField body="save" type="boolean" default="false">
  When `true`, saves the wallet address as a settlement account for future payouts.
</ParamField>

<ResponseExample>
  ```bash cURL (settlement account) theme={null}
  curl -X POST https://api.orafi.app/transactions/payout/crypto \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "amount": 5000,
      "cryptoSettlementAccountId": "854da716-03bf-4bcf-9eba-3302208f8f36"
    }'
  ```

  ```bash cURL (direct wallet) theme={null}
  curl -X POST https://api.orafi.app/transactions/payout/crypto \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "amount": 5000,
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "bytes": "QWRkIGNyeXB0byBhY2NvdW50...",
      "signature": "AEQCjzWKVlM5Ht4Qbwk/ZpPe..."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/transactions/payout/crypto", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({
      amount: 5000,
      cryptoSettlementAccountId: "854da716-03bf-4bcf-9eba-3302208f8f36"
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.orafi.app/transactions/payout/crypto",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={
          "amount": 5000,
          "cryptoSettlementAccountId": "854da716-03bf-4bcf-9eba-3302208f8f36"
      }
  )
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Payout created successfully",
    "data": {
      "id": "payout_abc123",
      "amount": 5000,
      "status": "INITIALIZED",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    }
  }
  ```

  ```json 400 — Bad Request theme={null}
  {
    "success": false,
    "message": "Insufficient balance"
  }
  ```
</ResponseExample>

***

## Create a fiat payout

<div className="api-method-box">
  <span className="api-method post">POST</span> `/transactions/payout/fiat`
</div>

Initiates a fiat payout to a saved bank account or a new bank account. See [Fiat Settlements](/api-reference/endpoint/fiat-settlements) to manage your saved accounts.

You can use a saved fiat settlement account or provide bank details directly.

***

## Retry a failed payout

<div className="api-method-box">
  <span className="api-method post">POST</span> `/transactions/payout/crypto/retry`
</div>

Retries a payout that previously failed. The payout must be in `FAILED` status.

### Request body

<ParamField body="payoutId" type="string" required>
  The ID of the failed payout to retry.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/transactions/payout/crypto/retry \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "payoutId": "payout_abc123"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/transactions/payout/crypto/retry", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({ payoutId: "payout_abc123" })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.orafi.app/transactions/payout/crypto/retry",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={"payoutId": "payout_abc123"}
  )
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Payout retried successfully",
    "data": {
      "id": "payout_abc123",
      "amount": 5000,
      "status": "INITIALIZED",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    }
  }
  ```
</ResponseExample>