Refunds

Creates a merchant-funded refund to a supplied destination address using the existing payout rail. The refund amount is capped by the invoice's credited merchant balance for the same asset. The merchant is charged the refund amount, the configured refund fee, and the actual on-chain network fee reported when the linked payout completes.

POST
/v1/refunds

Authorization

X-API-Key<token>

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.

In: header

Header Parameters

Idempotency-Keystring

Per-merchant idempotency key for refund POSTs. Replays return the previously recorded refund without duplicate side effects.

Length1 <= length <= 255

Request Body

invoice_idstring

Invoice UUID whose credited balance is being refunded.

Formatuuid
currencystring

Credited asset currency to refund.

Lengthlength <= 20
network?string

Credited asset network. Optional when the currency has an unambiguous network.

Lengthlength <= 64
amountstring

Decimal string amount to refund.

Lengthlength <= 50
destinationstring

Customer-supplied destination address.

Lengthlength <= 256
destination_tag?string

Memo/tag for chains that require it.

Lengthlength <= 256
description?string

Human-readable refund description.

Lengthlength <= 1000
metadata?object

Key-value metadata.

Propertiesproperties <= 50

Empty Object

Response Body

curl -X POST "https://dashboard.halfin.xyz/api/v1/refunds" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",    "currency": "string",    "amount": "string",    "destination": "string"  }'
{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
    "payout_id": "89e4daf5-d103-4869-b9da-3d54ecc98dfe",
    "currency": "string",
    "network": "string",
    "amount": "string",
    "recipient_amount": "string",
    "merchant_debit_amount": "string",
    "refund_fee": "string",
    "refund_fee_allocation": "customer",
    "network_fee": "string",
    "configured_network_fee_amount": "string",
    "network_fee_allocation": "customer",
    "destination": "string",
    "destination_tag": "string",
    "status": "pending",
    "environment": "live",
    "tx_hash": "string",
    "failure_reason": "string",
    "description": "string",
    "metadata": {},
    "completed_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Get

Previous Page

Rates

Next Page