​

Crypto refunds — operator runbook

​

When to refund

• The tenant has opened a support ticket with a clear refund reason (wrong-amount transfer, dispute closed in tenant’s favour, accidental top-up, etc.).
• The tenant has provided a destination wallet address. Confirm with the tenant via the same channel as the ticket — never accept an address from a different channel without re-confirmation.
• The destination address is on the same chain as the original payment. Cross-chain refunds will lose the funds; refuse them.
• The tenant is in the same jurisdiction window the operator is comfortable refunding (consult legal / finance for edge cases).
• The original top-up is recent enough that the refund makes sense. Operationally we cap at 90 days from the original transaction — older requests need escalation. This 90-day cap is an operator policy you apply by hand, not a server-side limit: the crypto refund endpoint does not check the transaction age and will not block a refund on an older top-up, so it is on you to check the date before submitting. (This differs from the tenant-facing fiat credit refund, which rejects lots older than 30 days in the API. Because crypto refunds are operator-only, the age judgement — including any approved escalation past 90 days — stays with you.)

​

When to refuse

• The original transaction is older than 90 days (an operator policy — the endpoint will not enforce this for you; verify the date yourself and escalate rather than submit if it is past 90 days).
• There is an active fraud review or chargeback dispute on the org.
• The destination wallet address is suspected of fraud or sanctions exposure (consult the AML SOP).
• The amount requested exceeds the original top-up.
• The tenant insists on a different chain than the original payment.
• The tenant’s spending pattern shows the refunded amount has already been spent on services rendered.

​

Step-by-step

1. Verify the ticket. Open the tenant’s support ticket. Confirm the original transaction id (txn_* / the credit_transactions.id of the finished top-up), the requested refund amount, and the destination wallet address.
2. Confirm the wallet address out-of-band. Reply on the ticket asking the tenant to confirm the destination address. Wait for the tenant to reply with the same address before proceeding — this is the primary defence against ticket compromise.
3. Find the original top-up’s transaction id. There is no admin transactions table with an inline refund button yet, so pull the id from the ledger. The original top-up is the credit_transactions row whose payment_method is crypto_nowpayments:
   SELECT id, organization_id, amount_cents, created_at
     FROM public.credit_transactions
    WHERE organization_id = '<org_id>'
      AND payment_method = 'crypto_nowpayments'
      AND type = 'credit'
    ORDER BY created_at DESC;
   
   The id you pass as transaction_id MUST be the ORIGINAL finished top-up — not a prior refund row. Refunding against a top-up whose payment_method is anything other than crypto_nowpayments is rejected with a 422 invalid_payment_method before NOWPayments is ever called.
4. Submit the refund via the admin API. Call the endpoint with a super-admin session (the admin OTP cookie or a super-admin API key — the same auth the admin dashboard uses). The request body is:
   // POST /api/v1/admin/billing/crypto-refund
   {
     "transaction_id": "<original credit_transactions.id>",
     "destination_address": "<wallet address the tenant confirmed>",
     "amount_cents": 5000,        // USD-equivalent; must be ≤ the original
     "reason": "ZD-12345 — full refund for wrong-amount transfer"
   }
   
   Field rules the endpoint enforces:
   • destination_address — chain-agnostic shape check (26–95 chars, letters and digits only, trimmed). It is not validated against the specific chain; NOWPayments’ payout endpoint rejects a mismatched address with a 4xx that the API surfaces verbatim. Paste exactly what the tenant confirmed.
   • amount_cents — default to the full original top-up. The endpoint accepts a partial amount (1 cent up to the original) and pays out the crypto proportionally, and it lets you issue several partials against one top-up as long as their running total never exceeds the original — it tracks the cumulative refunded-so-far amount and rejects an over-refund (or a refund on an already-fully-refunded top-up) with a 409. But do NOT submit a one-off partial. A lone partial over-reclaims the tenant’s wallet, because the wallet-settlement leg always reclaims the FULL original credit regardless of the amount submitted here — only a set of partials that sums back to the full original nets out correctly. If the tenant needs just part of a top-up returned, use the full-refund-then-fresh-top-up path or a manual USD credit instead. Read “Partial refunds” under Edge cases for the proportional formula, the cumulative state machine, and the wallet-settlement caveat before submitting anything other than the full amount.
   • reason — optional but always set it to the ticket reference; it is recorded on the audit-log entry.
5. Double-check before you send. There is no confirmation dialog to catch a typo, so re-read the request body before submitting: destination_address matches — character for character — what the tenant confirmed, and amount_cents is the full original top-up in cents. This is an irreversible money movement once the network confirms; the request itself is your only checkpoint.
6. Submit. On success the endpoint returns 200 with:
   {
     "data": {
       "refund_ledger_id": "cryrefund_…",
       "payout_id": "…",              // NOWPayments payout id
       "payout_status": "…",
       "amount_cents": 5000,
       "pay_currency": "usdttrc20",
       "destination_address": "…"
     }
   }
   
   Behind that response the system:
   • Records a pending refund row in credit_transactions (type crypto_refund_pending, negative amount_cents, reference = crypto_refund:<transaction_id>, payment_method = crypto_nowpayments) before calling the provider.
   • Calls NOWPayments POST /v1/payout synchronously and stamps the payout_id back onto the pending row.
   • Writes an audit-log entry (admin.crypto_refund_initiated) with the operator user id, ticket reference, address, and amount.
7. Wait for the IPN. NOWPayments fires a refunded IPN when the on-chain payout confirms. The IPN handler:
   • Reclaims the tenant’s wallet credit for the original payment, idempotently keyed on the original payment so a duplicate IPN never double-deducts. The amount reclaimed is the full USD value credited at top-up time (FX-locked) — it exactly undoes the original top-up. This wallet-settlement leg is distinct from the on-chain payout leg: the payout the operator initiates is proportional to the refund amount (see “Partial refunds”), whereas the refunded IPN carries no per-refund amount and always reclaims the full original credit. Read the “Partial refunds” caveat before issuing a single partial refund.
   • Updates the crypto_topup_intents row to refunded.
   • Emits a second audit-log entry (billing.crypto_topup_ipn_refunded, resource crypto_topup_intents).
8. Reply to the ticket. Once the IPN lands and the wallet has been deducted, reply to the ticket with the payout id + on-chain transaction hash (when NOWPayments includes it on the IPN payload).

​

Reconciliation

SELECT id, organization_id, amount_cents, metadata, created_at
  FROM public.credit_transactions
 WHERE type = 'crypto_refund_pending'
    OR metadata->>'source' = 'crypto_nowpayments_refund_pending'
 ORDER BY created_at DESC;

SELECT ct.id AS pending_id,
       ct.amount_cents,
       ct.metadata->>'payout_id' AS payout_id,
       cti.nowpayments_payment_id AS nowpayments_payment_id,
       ct.created_at AS initiated_at,
       refund.id AS settled_id,
       refund.amount_cents AS settled_amount_cents,
       refund.created_at AS settled_at
  FROM public.credit_transactions ct
  -- The original top-up ledger row this refund is issued against.
  -- The admin controller stamps its id as `metadata.parent_transaction_id`
  -- on the pending row.
  JOIN public.credit_transactions topup
    ON topup.id = (ct.metadata->>'parent_transaction_id')
   AND topup.organization_id = ct.organization_id
  -- The NOWPayments intent that minted the original payment id. The
  -- top-up's `finished` IPN writes `metadata.nowpayments_payment_id`,
  -- and the intent table is the canonical home for that id.
  JOIN public.crypto_topup_intents cti
    ON cti.nowpayments_payment_id = (topup.metadata->>'nowpayments_payment_id')
   AND cti.organization_id = ct.organization_id
  -- The settled deduct written by the `refunded` IPN handler via
  -- `deductBalance(…, "nowpayments:refund:<payment_id>", …)`. The
  -- idempotency key is the ORIGINAL NOWPayments payment_id, NOT the
  -- payout_id. Read it from the first-class `idempotency_key` column
  -- (it is also shadowed into `metadata.idempotency_key`).
  LEFT JOIN public.credit_transactions refund
    ON refund.idempotency_key = ('nowpayments:refund:' || cti.nowpayments_payment_id)
   AND refund.type = 'debit'
 WHERE ct.type = 'crypto_refund_pending'
 ORDER BY ct.created_at DESC;

​

Edge cases

payout_crypto = (refund_cents / original_amount_cents) × actually_paid_crypto

• Refund the original in full, then ask the tenant to send a fresh top-up for the amount they want to keep on the wallet, or
• Credit the agreed amount back manually in USD via the bonus credits tool and refuse the on-chain refund.

• 422 pay_currency_missing — the original NOWPayments intent has no pay_currency on file, so the payout coin cannot be derived.
• 422 actually_paid_crypto_missing — the original payment’s crypto amount (actually_paid) is not on file, so the proportional payout cannot be computed.

• 422 “Invalid address” — the destination address is not valid for the pay currency. Re-ask the tenant; this typically means a wrong-chain paste.
• 422 “Amount below minimum” — NOWPayments has per-currency minimum payouts. For tiny refunds the only path is to credit the wallet in USD via the bonus credits tool and refuse the on-chain refund.

​

Audit trail

1. admin.crypto_refund_initiated — written by the admin controller the moment the refund API call is accepted. Contains the operator user id, source IP, ticket reason, destination address, amount, original transaction id, payout id from NOWPayments, and initial payout status.
2. billing.crypto_topup_ipn_refunded — written by the IPN handler when the refunded IPN lands (resource crypto_topup_intents). The action name is templated as billing.crypto_topup_ipn_${status}, so the refunded IPN yields billing.crypto_topup_ipn_refunded. It does NOT carry the on-chain transaction hash or the new wallet balance; it records the NOWPayments payment_id, the payment_status, the actually_paid amount, and the outcome_amount / outcome_currency.