Skip to main content

​
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.
​
id
string
Unique identifier for the refund.
​
amount
number
Refund amount in NGN.
​
status
string
Refund status. One of COMPLETED or FAILED.
​
reason
string
Reason for the refund, if provided.
​
walletAddress
string
Destination address where the refund was sent.
​
txDigest
string
On-chain transaction hash for the refund.
​
executionTime
number
Time taken to execute the refund (in milliseconds).
​
gasFee
number
Network gas fee for the transaction.
​
amountSent
number
Actual USDC amount sent to the customer.
​
originalTxId
string
ID of the original transaction that was refunded.
​
transactionId
string
ID of the refund’s own transaction record.
{
  "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"
}

​
Transaction sub-object

When retrieving a Transaction with type: "REFUND", the refund appears as a nested refund sub-object with these fields:
​
id
string
Unique identifier for the refund.
​
reason
string
Reason for the refund, if provided.
​
walletAddress
string
Destination wallet address the refund was sent to.
​
originalTxId
string
ID of the original transaction being refunded.
​
txDigest
string
On-chain transaction hash for the refund.
{
  "id": "cmjr6ixla0005v84wlfust2mn",
  "reason": "Customer not satisfied",
  "walletAddress": "0xc9f89b41c8e9...1ad9",
  "originalTxId": "cmjlzeq0j0001v83g2cuplnbg",
  "txDigest": "3xYmB9kT..."
}

​
Create a refund

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

​
Request body

​
originalTxId
string
required
Unique identifier of the original transaction to refund.
​
to
string
required
Destination wallet address for the refund. Must be a valid 66-character blockchain address.
​
reason
string
Optional note explaining the reason for the refund.
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"
  }'

​
Retry a failed refund

POST /transactions/refund/retry
Retries a previously failed refund.

​
Request body

​
refundId
string
required
Unique identifier of the failed refund to retry.
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"
  }'