Refund Flows

Learn about the Terminal's recommended refund flow as part of the integration.

This document provides best practices and clear guidelines for merchants using Inabit Terminal to manage the refund process. It explains how to structure refunds in a self-custody environment, ensuring compliance, transparency, and operational efficiency. Merchants remain in full control of their funds while following standardized steps to reduce risk and improve customer trust.

1. Core Principles

• Self-Custody by Default: Merchants maintain full control of assets via API wallets; Inabit does not take custody, but provides orchestration (refund logic, rebalancing, swaps).

• Separation of Flows: Refunds are logically separated from deposits to avoid operational confusion and improve auditability.

• Security First: Every refund requires strict address verification and transaction simulation before execution.

• Predictability: Fees and balances must always be simulated and validated prior to committing a refund transaction.

2. Standard Refund Workflow

Step 1 – Refund Request

• The End-Customer requests a refund through the Merchant’s platform.

• The request includes: end-customer wallet address, amount, and asset.

Step 2 – Address Verification

• Merchant verifies the provided address:

• Confirm valid blockchain format:

query IsValidAddress($where: WalletAddressValidateWhereInput!) {
    isValidAddress(where: $where)
}

Variables (Body):

{
    "where": {
        "address": "0x..."
        "blockchainId": "clefn7d3k04ellc6rb2sdbowp",
        "financialAssetId": "clefn78hd013rlc6rmjqa0k9t"
    }
}

Step 3 – Refund Logic & Fee Simulation

• Merchant platform simulates the refund:

• Check fee cost vs. refund amount.

query ValidateTransactionFee($where: ValidateTransactionFeeInput!) {
    validateTransactionFee(where: $where) {
        isValid
        priorities {
            noPriority
            verySlow
            slow
            medium
            fast
            veryFast
        }
    }
}

Variables (Body):

{
    "where": {
        "amount": 0,
        "organization:" {
            "id": "currencyOrgId"
        },
        "wallet": {
            "id": "clvxlyl7k00008o013v2q879r"
        },
        "financialAsset": {
            "id": "clvxlyl7k00008o013v2q879r"
        },
        "blockchain": {
            "id": "clvxlyl7k00008o013v2q879r"
        }
    }
} 

• Apply refund logic (min amount, full refund, partial refund).

Step 4 – Balance Validation

• If refund wallet (API wallet) has sufficient balance → create withdrawal request directly.

• If insufficient balance → trigger one of two:

  • Master Wallet Refill – request funds from Inabit Master Wallet.

  • Swap – convert another asset into the required refund asset.

Step 5 – Withdrawal Execution

• Refund API wallet executes withdrawal to the End-Customer’s wallet.

• Transaction details logged for audit.

3. Best Practices for Merchants

A. Address Handling

• Always verify the refund address before submission.

• Maintain KYT/AML screening at refund step (not just deposit step).

• Encourage refunds to original funding address unless policy explicitly allows otherwise.

B. Balances & Liquidity

• Maintain a daily rebalancing schedule between Master Wallet and Refund API Wallet to ensure refund capacity.

• Monitor minimum thresholds (e.g., ensure refund wallet has ≥ X daily refund volume).

• Use Inabit’s swap service only when master wallet transfer cannot fulfill the request quickly.

C. Fees & Costs

• Always simulate gas/fee costs prior to refund.

• If fees exceed a set % of refund value, apply business logic (e.g., absorb fee vs. deduct from refund).

• Document your fee-handling policy clearly for customers.

D. Security & Controls

• Implement multi-sig policies on Master Wallet withdrawals.

• Enforce withdrawal velocity limits (e.g., max N refunds per hour).

• Keep strict audit logs: refund request ID, linked deposit ID, blockchain TX ID, timestamps.

E. Customer Transparency

• Provide end-customers with refund confirmation including TX hash.

• Communicate expected blockchain settlement time.

4. Operational Recommendations

• Automation: Use Inabit APIs to automate refund initiation, balance checks, and KYT checks.

• Exception Handling: Create fallback logic if refund wallet + master wallet + swaps cannot fulfill request (manual review).

• Testing: Simulate refund flows regularly in sandbox before enabling for production.

• Monitoring: Integrate refund activity into merchant dashboards with real-time alerts (e.g., failed withdrawals, low refund balance).

5. Example Flow Summary (Aligned with Diagram)

1. End-Customer requests refund → Merchant verifies & simulates.

2. If refund wallet balance sufficient → direct withdrawal.

3. If insufficient → Merchant triggers master wallet transfer or asset swap.

4. Refund API wallet executes withdrawal.

5. End-Customer receives refund → TX hash returned.