Get Refund Session

Retrieve a refund session by ID.

GET /api/v1/widgets/refund-sessions/:sessionId

Returns the current state of a refund session, including whether the refund transaction has been detected on-chain and confirmed.

Parameters

Path

Name	Type	Required	Description
sessionId	string	Yes	The refund session ID

Request example

curl --request GET 'https://payments.bleepay.com/api/v1/widgets/refund-sessions/ref_a1b2c3d4e5f6' \
  --header 'Authorization: Bearer <business_token>'

Response

Response schema

Field	Type	Description
id	string	Unique refund session identifier
businessId	string	The business ID
widgetId	string	The widget ID
depositSessionId	string	The parent deposit session ID
paymentStatus	string	Status: CREATED, PENDING, CONFIRMED, EXPIRED, FAILED, CANCELLED
status	string	Session status: PENDING, ENABLED, DISABLED, SUSPENDED
amount	string	Refund amount
amountRaw	string	Raw amount in lowest denominator
currency	string	Currency symbol
network	string	Blockchain network
currencyAddress	string	Currency contract address
dstAddress	string	Refund destination address
value	string	Estimated USD value
valueRaw	string	Raw USD value in lowest denominator
payers	array	Payer addresses for the refund
confirmedTxid	string or null	Confirmed blockchain transaction hash
confirmedPayerAddress	string or null	Confirmed payer wallet address
metadata	object or null	Custom metadata
expiresAt	string	ISO 8601 expiry timestamp
confirmedAt	string or null	ISO 8601 confirmation timestamp
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Example response

{
  "id": "ref_a1b2c3d4e5f6",
  "businessId": "biz_abc123",
  "widgetId": "wdgt_abc",
  "depositSessionId": "dep_a1b2c3d4e5f6",
  "paymentStatus": "CONFIRMED",
  "status": "ENABLED",
  "amount": "100",
  "amountRaw": "100000000",
  "currency": "USDC",
  "network": "polygon",
  "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "dstAddress": "0xPayerWalletAddress",
  "value": "100.00",
  "valueRaw": "10000",
  "payers": [
    { "address": "0xPayerWalletAddress" }
  ],
  "confirmedTxid": "0xabc123def456...",
  "confirmedPayerAddress": "0xPayerWallet123...",
  "metadata": { "reason": "customer_request" },
  "expiresAt": "2026-06-09T12:30:00.000Z",
  "confirmedAt": "2026-06-09T12:05:00.000Z",
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:05:00.000Z"
}

Error responses

Status	Code	Description
401	unauthorized	Missing or invalid authentication
404	not_found	Refund session not found