Refund Flow

📘

API Reference

Endpoint	Method	Description
Create Refund	POST payment/refund	Create payment refund
Get Refund by ID	GET payment/refund/{Id}	Retrieve details of a specific refund by ID
List Refunds	GET merchant/refund	Fetch a list of all merchant refunds

---

Create refund request body parameters

🚧

Important

Use the dryRunquery parameter to validate a refund request without executing it. By default, dryRunis set to false. Set it to trueto perform a validation only, without processing the actual refund.

blockchain and address are required only when type is CRYPTO. All other fields below fromAmount are optional for every refund type.

Name	Type	Required	Description
paymentId	string	✅	Unique identifier of the payment being refunded
type	string (enum)	✅	Type of refund provider. Allowed: ASTERIUM, CRYPTO
fromCurrency	string	✅	Currency the refund is issued from
toCurrency	string	✅	Currency the refund is issued in
fromAmount	string	✅	≥ 0. Refund amount in source currency; must be ≤ sum of the payment items
blockchain	string	✅ (CRYPTO only)	Blockchain network for the refund
address	string	✅ (CRYPTO only)	Destination crypto address for the refund
toAmount	string	❌	≥ 0. Refund amount in target currency; calculated automatically if omitted
invoiceId	string	❌	Unique identifier of the associated invoice
description	string	❌	Additional details or notes about the refund
signedRate	object	❌	Signed rate information, used when the refund involves a currency exchange

---

Example

ASTERIUM CRYPTO (requires blockchain + address)

JSON

{
  "paymentId": "",
  "type": "ASTERIUM",
  "toCurrency": "",
  "fromCurrency": "",
  "fromAmount": ""
}

Full Request Example (with optional fields)

JSON

{
  "paymentId": "a0570107-bba8-447e-b591-980d36c45d34",
  "type": "CRYPTO",
  "fromCurrency": "usdt",
  "toCurrency": "usdt",
  "fromAmount": "50.00",
  "blockchain": "tron",
  "address": "TKM5PxycJq6JpTfsz6PYhQYTThr7FAEqTK",
  "invoiceId": "4fa3a26d-09b4-49be-94ac-b2231528e7f7",
  "description": "Customer requested partial refund"
}

Response (JSON)

JSON

{
  "id": "f3b2c1a0-6e4d-4b8a-9c3e-1a2b3c4d5e6f",
  "paymentId": "a0570107-bba8-447e-b591-980d36c45d34",
  "type": "CRYPTO",
  "status": "INIT",
  "fromAmount": "50.00",
  "fromCurrency": "usdt",
  "toAmount": "50.00",
  "toCurrency": "usdt",
  "invoiceId": "4fa3a26d-09b4-49be-94ac-b2231528e7f7",
  "amountInInvoiceCurrency": "50.00",
  "amountInPaymentCurrency": "50.00",
  "feeAmount": "0.50",
  "feeCurrency": "usdt",
  "description": "Customer requested partial refund",
  "statusDescription": "Refund initialized, awaiting processing",
  "createdDate": "2025-11-12T08:10:22.216Z",
  "lastModifiedDate": "2025-11-12T08:10:22.216Z"
}

👍

Note: the same BaseRefundDto object is returned for dryRun=true (validation only, no funds moved) and dryRun=false (real execution).

---

Refund Statuses

Status	Description	Category
INIT	Refund created but not yet processed.	⏳ Pending
PROCESSING	Refund is being processed.	⏳ Pending
CAPTURED	Funds have been held (captured) for the refund. This is an intermediate status — a further internal operation follows before the refund is complete.	🔄 In Progress
PROCESSED	Final status. Funds have been sent back to the payer.	✅ Final
REJECTED	Refund was rejected due to validation or fraud detection.	❌ Final
REVERSING	Refund reversal is in progress.	🔄 In Progress
DIRTY_MONEY	Refund flagged as suspicious. Manual compliance review required.	⚠️ Review
FAILED	Refund attempt failed due to an error.	❌ Final
SETTLEMENT_PROCESSED	Refund has been included in a settlement.	✅ Final
SETTLEMENT_CAPTURED	Refund settlement has been captured.	✅ Final

Status Flow Diagram

                       ┌──────────┐
                       │   INIT   │
                       └────┬─────┘
                            │
                       ┌────▼──────────┐
                       │  PROCESSING   │
                       └────┬──────────┘
                            │
        ┌────────────┬──────┴──────┬─────────────┐
        │            │             │             │
   ┌────▼──────┐ ┌───▼────┐  ┌─────▼─────┐  ┌────▼───┐
   │  CAPTURED │ │REJECTED│  │DIRTY_MONEY│  │ FAILED │
   └────┬──────┘ └────────┘  └───────────┘  └────────┘
        │
        │  (intermediate: funds held, internal
        │   follow-up operation pending)
        │
   ┌────▼──────┐
   │ PROCESSED │  ◄── final: funds returned to payer
   └────┬──────┘
        │
   ┌────▼──────────────────┐
   │  SETTLEMENT_PROCESSED │
   └────┬───────────────────┘
        │
   ┌────▼──────────────────┐
   │  SETTLEMENT_CAPTURED  │
   └────────────────────────┘

---

---

📘

Tips

• Always run with dryRun=true first to validate the refund amount and currency before executing it for real.
• fromAmount must be less than or equal to the sum of the original payment items.
• Use List Refunds with the statuses and paymentMethods filters to monitor refund progress across your merchant account.

---

Related Endpoints

Endpoint	Method	Description
Create Refund	POST	Create a new refund for a payment
Get Refund by ID	GET	Retrieve refund details
List Refunds	GET	List all refunds for the merchant
Get Exchange Rate	GET	Obtain signed rate for a currency conversion
Get Invoice Payment	GET	Retrieve the payment being refunded