Get

application/json

• dataobjectRequired
  • Unknown properties are rejected

  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"}

  • 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

{
  "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"
  }
}

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"
  }
}

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"
  }
}

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"
  }
}

application/json

• errorobjectRequired
  The error code and diagnostic message.
  • Unknown properties are rejected

  Example: {"code":"not_found","message":"string","details":["string"]}

  • code"not_found"Required
    `not_found`: The refund was not found in the API key's merchant and environment scope.

    Example: not_found

  • 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": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

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"
  }
}

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"
  }
}