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

# Refunds

> Return funds to customers for completed transactions.

## The refund object

A refund returns funds from a completed payment back to the customer's wallet. Refunds are free — no platform fee is deducted.

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

<ResponseField name="amount" type="number">
  Refund amount in NGN.
</ResponseField>

<ResponseField name="status" type="string">
  Refund status. One of `COMPLETED` or `FAILED`.
</ResponseField>

<ResponseField name="reason" type="string">
  Reason for the refund, if provided.
</ResponseField>

<ResponseField name="walletAddress" type="string">
  Destination address where the refund was sent.
</ResponseField>

<ResponseField name="txDigest" type="string">
  On-chain transaction hash for the refund.
</ResponseField>

<ResponseField name="executionTime" type="number">
  Time taken to execute the refund (in milliseconds).
</ResponseField>

<ResponseField name="gasFee" type="number">
  Network gas fee for the transaction.
</ResponseField>

<ResponseField name="amountSent" type="number">
  Actual USDC amount sent to the customer.
</ResponseField>

<ResponseField name="originalTxId" type="string">
  ID of the original transaction that was refunded.
</ResponseField>

<ResponseField name="transactionId" type="string">
  ID of the refund's own transaction record.
</ResponseField>

<ResponseExample>
  ```json The refund object theme={null}
  {
    "id": "cmjfu1cjv0007v8vrefund01",
    "amount": 4000,
    "status": "COMPLETED",
    "reason": "Customer requested",
    "walletAddress": "0x871cf48ff1847e7a...55c2d3",
    "txDigest": "3xYmB9kT...",
    "executionTime": 1234,
    "gasFee": 0.001,
    "amountSent": 2.53,
    "originalTxId": "cmjlzeq0j0001v83g2cuplnbg",
    "transactionId": "cmjr6iwo60004v84wdnwm7qub"
  }
  ```
</ResponseExample>

### Transaction sub-object

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

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

<ResponseField name="reason" type="string">
  Reason for the refund, if provided.
</ResponseField>

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

<ResponseField name="originalTxId" type="string">
  ID of the original transaction being refunded.
</ResponseField>

<ResponseField name="txDigest" type="string">
  On-chain transaction hash for the refund.
</ResponseField>

<ResponseExample>
  ```json Refund as transaction sub-object theme={null}
  {
    "id": "cmjr6ixla0005v84wlfust2mn",
    "reason": "Customer not satisfied",
    "walletAddress": "0xc9f89b41c8e9...1ad9",
    "originalTxId": "cmjlzeq0j0001v83g2cuplnbg",
    "txDigest": "3xYmB9kT..."
  }
  ```
</ResponseExample>

***

## Create a refund

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

Initiates a refund for a previously completed transaction. The full amount is returned to the specified wallet address.

### Request body

<ParamField body="originalTxId" type="string" required>
  Unique identifier of the original transaction to refund.
</ParamField>

<ParamField body="to" type="string" required>
  Destination wallet address for the refund. Must be a valid 66-character blockchain address.
</ParamField>

<ParamField body="reason" type="string">
  Optional note explaining the reason for the refund.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/v1/transactions/refund \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "originalTxId": "cmjlzeq0j0001v83g2cuplnbg",
      "to": "0xc9f89b41c8e9a4f1d1cf16477500cc303fe9720f5c3b55211d4694a5ebcd1ad9",
      "reason": "Customer not satisfied"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/v1/transactions/refund", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({
      originalTxId: "cmjlzeq0j0001v83g2cuplnbg",
      to: "0xc9f89b41c8e9a4f1d1cf16477500cc303fe9720f5c3b55211d4694a5ebcd1ad9",
      reason: "Customer not satisfied"
    })
  });
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Refund initiated successfully",
    "data": {
      "status": "COMPLETED",
      "amount": 200,
      "txDigest": "2MHzMhPt...9ttY",
      "executionTime": 2101,
      "gasFee": 0.0001,
      "platformFee": null,
      "amountSent": 0.18
    }
  }
  ```
</ResponseExample>

***

## Retry a failed refund

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

Retries a previously failed refund.

### Request body

<ParamField body="refundId" type="string" required>
  Unique identifier of the failed refund to retry.
</ParamField>

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

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Refund Payout initiated successfully",
    "data": {
      "status": "COMPLETED",
      "amount": 200,
      "txDigest": "3NKzNiQt...8uuZ",
      "executionTime": 2101,
      "gasFee": 0.0001,
      "platformFee": null,
      "amountSent": 0.18
    }
  }
  ```
</ResponseExample>