Process Refund

Process refund for a deposit (API Key Auth).

Refunds are settlement-aware:

Unsettled deposits: Refunded from holding_balance

Settled deposits: Refunded from available_balance

Request Body:

original_transaction_id (required): ID of the original deposit transaction to refund

refund_amount (required): Amount to refund (must be ≤ original deposit amount minus previous refunds)

currency_code (required): Currency code (must match original deposit currency)

reason (required): Reason for the refund (e.g., "Customer requested refund")

notes (optional): Additional notes about the refund

Validations:

Refund amount must be ≤ original deposit amount (minus previous refunds)

Currency must match original deposit currency (no cross-currency refunds)

Sufficient balance required (either holding or available, depending on settlement status)

Original transaction must be a completed deposit

Returns:

refund_transaction_id: ID of the created refund transaction

original_transaction_id: ID of the original deposit

refund_amount: Amount refunded

balance_source: Which balance was debited ('holding_balance' or 'available_balance')

original_settlement_status: Settlement status of the original deposit ('unsettled' or 'settled')

holding_balance: Updated holding balance

available_balance: Updated available balance

balance: Total balance (holding + available)

refunded_at: Timestamp when refund was processed

Example:

Original deposit: $100 (unsettled, in holding_balance)

Refund request: $30

Result: $30 debited from holding_balance, refund transaction created

Supports partial refunds: You can refund multiple times until the original amount is exhausted.

API Key authentication required

curl --location --request POST '/api/v1/merchants/wallet/refund' \ --header 'x-api-key: <api-key>' \ --header 'Content-Type: application/json' \ --data-raw '{ "currency_code": "USD", "notes": "Refund approved by support team", "original_transaction_id": "550e8400-e29b-41d4-a716-446655440000", "reason": "Customer requested refund", "refund_amount": 50 }'

Request

Responses