List

Includes API refunds and every individual return confirmed in Dashboard or Admin, including payments not credited to the merchant. Use invoice_id to select one invoice. Poll for complete progress; refund webhooks do not cover every return.

Usage notes#

Requires refunds:read. Returns all refunds in the API key's merchant and environment, including returns confirmed in Dashboard or Admin and payments not credited to the merchant. Each item has the same representation as Get refund.

Use invoice_id to select one invoice. Lists use opaque cursors; keep the filter unchanged when following meta.next_cursor. The default limit is 20 and maximum 100. No matches returns an empty array. See pagination.

payment_id links a return to its incoming payment when known. refund_request_id groups returns confirmed together. Save each opaque id unchanged. Poll for complete progress: existing refund webhooks do not cover returns of payments not credited to the merchant. See tracking refunds.

GET/v1/refunds

curl --request GET 'https://api.thehalfin.com/v1/refunds' \
  --header "X-API-Key: $HALFIN_API_KEY"

Authorization

X-API-KeystringRequired
API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.
Example: $HALFIN_API_KEY

Query Parameters

invoice_idstringOptional
Return all refunds linked to this invoice in the same format as the unfiltered list.
- Format: uuid
Example: 00000000-0000-0000-0000-000000000001
limitintegerOptional
Maximum number of items to return (default 20, max 100).
- Minimum: 1
- Maximum: 100
- Default: 20
Example: 20
cursorstringOptional
Opaque cursor from meta.next_cursor. Omit for the first page. Bound to the collection, scope, filters, and ordering.
- Maximum length: 8192
Example: string

Response Body

200 Cursor-paginated refund list.

application/json

dataarray<object>Required
Example: [{"id":"00000000-0000-0000-0000-000000000004","invoice_id":"00000000-0000-0000-0000-000000000003","payout_id":"00000000-0000-0000-0000-000000000004","currency":"USDC","network":"ethereum","amount":"5.00","recipient_amount":"5.00","merchant_debit_amount":"5.10","refund_fee":"0.10","refund_fee_allocation":"merchant","network_fee":null,"configured_network_fee_amount":"0.00","network_fee_allocation":"platform","destination":"0x0000000000000000000000000000000000000001","destination_tag":null,"status":"pending","environment":"live","tx_hash":null,"failure_reason":null,"description":"Partial refund for order 1001","metadata":null,"completed_at":null,"created_at":"2026-09-14T10:00:00Z","payment_id":null,"refund_request_id":null}]
- idstringRequired
  Opaque refund identifier. Save and pass it unchanged to GET refund.
  - Maximum length: 80
  Example: string
- invoice_idstringRequired
  Invoice UUID being refunded.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- payment_idstring | nullRequired
  Original incoming payment. Null for invoice-level API refunds without payment attribution.
  - Format: uuid
  Example: null
- refund_request_idstring | nullRequired
  Groups refunds authorized by one manual confirmation. Null for individually created API refunds.
  - Format: uuid
  Example: null
- payout_idstringRequired
  Compatibility identifier equal to this refund's ID. It does not identify a separate payout.
  - Maximum length: 80
  Example: string
- currencystringRequired
  Refunded asset currency.
  Example: string
- networkstringRequired
  Refunded asset network.
  Example: string
- amountstringRequired
  Base/requested refund amount as a decimal string.
  Example: 1
- recipient_amountstringRequired
  Amount sent to the customer after customer-allocated commercial charges.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- merchant_debit_amountstringRequired
  Authorized merchant debit including merchant-paid charges. For a payment not credited to the merchant, its held funds supply principal and this amount covers charges only. Failed or reversed execution can release or reverse the debit.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- refund_feestringRequired
  Decimal string platform refund fee in refund currency.
  Example: 1
- refund_fee_allocation"customer" | "merchant" | "platform"Required
  Example: customer
- network_feestring | nullRequired
  Decimal string actual on-chain network fee when available; null when unavailable, including returns of funds that were not credited to the merchant balance.
  Example: null
- configured_network_fee_amountstringRequired
  Snapshotted commercial network charge; distinct from actual on-chain cost.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- network_fee_allocation"customer" | "merchant" | "platform"Required
  Example: customer
- destinationstringRequired
  Destination blockchain address.
  Example: string
- destination_tagstring | nullRequired
  Memo/tag if applicable.
  Example: null
- status"pending" | "processing" | "confirming" | "completed" | "failed" | "reversed"Required
  Refund execution status.
  Example: pending
- environment"live" | "test"Required
  Environment this refund belongs to.
  Example: live
- tx_hashstring | nullRequired
  On-chain transaction hash after completion.
  Example: null
- failure_reasonstring | nullRequired
  Merchant-facing reason when the refund fails. A rejected destination is reported as destination_rejected; other failures are reported as internal_error. Null while processing or after completion.
  Example: null
- descriptionstring | nullRequired
  Refund description.
  Example: null
- metadataobject | nullRequired
  Merchant-supplied metadata.
  Example: null
  - [key]stringOptional
    Example: string
- completed_atstring | nullRequired
  Completion timestamp.
  - Format: date-time
  Example: null
- created_atstringRequired
  Creation timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001","has_more":false,"next_cursor":null}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. An inbound value is adopted only from explicitly trusted ingress; public client values are replaced.
  Example: string
- has_morebooleanRequired
  True exactly when next_cursor is not null.
  Example: false
- next_cursorstring | nullRequired
  Opaque cursor for the next page. Null when this is the last page.
  Example: null

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000004",
      "invoice_id": "00000000-0000-0000-0000-000000000003",
      "payout_id": "00000000-0000-0000-0000-000000000004",
      "currency": "USDC",
      "network": "ethereum",
      "amount": "5.00",
      "recipient_amount": "5.00",
      "merchant_debit_amount": "5.10",
      "refund_fee": "0.10",
      "refund_fee_allocation": "merchant",
      "network_fee": null,
      "configured_network_fee_amount": "0.00",
      "network_fee_allocation": "platform",
      "destination": "0x0000000000000000000000000000000000000001",
      "destination_tag": null,
      "status": "pending",
      "environment": "live",
      "tx_hash": null,
      "failure_reason": null,
      "description": "Partial refund for order 1001",
      "metadata": null,
      "completed_at": null,
      "created_at": "2026-09-14T10:00:00Z",
      "payment_id": null,
      "refund_request_id": null
    }
  ],
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001",
    "has_more": false,
    "next_cursor": null
  }
}

400 `validation_error`: The request format, parameters, headers, or field values are invalid.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"validation_error","message":"string","details":["string"]}
- code"validation_error"Required
  `validation_error`: The request format, parameters, headers, or field values are invalid.
  Example: validation_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

401 `unauthorized`: A valid API key is required.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unauthorized","message":"string","details":["string"]}
- code"unauthorized"Required
  `unauthorized`: A valid API key is required.
  Example: unauthorized
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

403 `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"forbidden","message":"string","details":["string"]}
- code"forbidden" | "api_key_ip_forbidden"Required
  `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.
  Example: forbidden
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "forbidden",
    "message": "Permission denied"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

500 `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"internal_error","message":"string","details":["string"]}
- code"internal_error"Required
  `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.
  Example: internal_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

503 `service_unavailable`: The service is temporarily unavailable. Retry later.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"service_unavailable","message":"string","details":["string"]}
- code"service_unavailable"Required
  `service_unavailable`: The service is temporarily unavailable. Retry later.
  Example: service_unavailable
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

Usage notes# #

Authorization #

Query Parameters #

Response Body #

Usage notes#

Authorization

Query Parameters

Response Body