Get

Returns the payout detail. The payout must belong to the authenticated merchant and match the API key's environment.

Usage notes#

Returns the payout detail. The payout must belong to the authenticated merchant and match the API key's environment.

Requires payouts:read. Read status, tx_hash, and failure_reason when reconciling execution. processing includes unresolved outcomes; do not resend as a new payout while the old one is unresolved.

recipient_amount, not the requested principal or its USD display value, identifies the on-chain transfer amount. Actual network cost uses its own network_fee_currency and network_fee_network. The compatibility enum includes cancelled, but individual payouts do not enter that status. See payouts.

Inspect every funding source and native balance movement. A failed payout can retain completed conversion debits and acquired target funds.

GET/v1/payouts/{payoutID}

curl --request GET 'https://api.thehalfin.com/v1/payouts/00000000-0000-0000-0000-000000000001' \
  --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

Path Parameters

payoutIDstringRequired
Payout UUID.
- Format: uuid
Example: 00000000-0000-0000-0000-000000000001

Response Body

200 The payout.

application/json

dataobjectRequired
- Unknown properties are rejected
Example: {"id":"00000000-0000-0000-0000-000000000003","currency":"USDC","network":"ethereum","amount":"10.00","recipient_amount":"10.00","amount_in_base_currency":null,"network_fee":null,"network_fee_currency":null,"network_fee_network":null,"fee_amount":"0.10","payout_fee_allocation":"merchant","configured_network_fee_amount":"0.00","network_fee_allocation":"platform","destination":"0x0000000000000000000000000000000000000001","destination_tag":null,"beneficiary_type":"third_party","status":"queued","environment":"live","tx_hash":null,"description":"Withdrawal 1001","executable_at":null,"completed_at":null,"created_at":"2026-09-14T10:00:00Z","updated_at":"2026-09-14T10:00:00Z","failure_reason":null,"operation_id":null,"target_funding_amount":"10.10","funding":null,"balance_movements":[],"economics_status":"available","metadata":{"withdrawal_id":"1001"},"created_by_id":null}
- idstringRequired
  Payout UUID.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- currencystringRequired
  Cryptocurrency code.
  Example: string
- networkstringRequired
  Blockchain network key for explorer and gate routing.
  Example: string
- amountstringRequired
  Base/requested payout amount. This field keeps its historical meaning.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- recipient_amountstring | nullRequired
  Amount sent to the recipient after customer-allocated commercial charges.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- amount_in_base_currencystring | nullRequired
  Historical USD display valuation from the accepted pricing snapshot. Null when that snapshot has no valuation; current rates are never substituted.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_feestring | nullRequired
  Actual processor-reported on-chain network cost denominated in `network_fee_currency` on `network_fee_network`. Null until the payout reaches a terminal state and the processor reports that cost: before completion the actual cost does not exist, and the configured estimate is never substituted for it. The snapshotted commercial charge is the separate `configured_network_fee_amount` field, which is populated from creation in payout currency. The actual on-chain cost is not added to `target_funding_amount`.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_fee_currencystring | nullRequired
  Currency of the actual processor-reported network fee.
  Example: null
- network_fee_networkstring | nullRequired
  Network of the actual processor-reported network fee.
  Example: null
- fee_amountstring | nullRequired
  Decimal string of the platform payout fee in payout currency.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- payout_fee_allocation"customer" | "merchant" | "platform" | nullRequired
  Allocation of the snapshotted payout service fee.
  Example: null
- configured_network_fee_amountstring | nullRequired
  Snapshotted commercial network charge in payout currency; distinct from actual on-chain cost.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_fee_allocation"customer" | "merchant" | "platform" | nullRequired
  Allocation of the commercial `configured_network_fee_amount` in payout currency, not the actual on-chain `network_fee`.
  Example: null
- destinationstringRequired
  Destination blockchain address.
  Example: string
- destination_tagstring | nullRequired
  Memo/tag if applicable.
  Example: null
- beneficiary_type"self" | "third_party"Required
  Who receives the funds, declared by the merchant on every payout. `self` — the merchant's own wallet or its own account at an exchange; `third_party` — a wallet that belongs to someone else (a customer, a partner, a payroll recipient). Required on creation, no default. The platform stores the declared value and returns it on the payout; it does not change how the payout executes. Travel Rule handling branches on this axis, so the declaration must be truthful.
  Example: self
- status"queued" | "processing" | "confirming" | "completed" | "failed" | "cancelled" | "reversed"Required
  Payout status. `processing` covers the whole span between dispatch and a terminal outcome: the merchant's funds stay reserved until the payout reaches `completed` or `failed`. `cancelled` is retained in this enum for compatibility but is not emitted for an individual payout.
  Example: queued
- environment"live" | "test"Required
  Environment this payout belongs to.
  Example: live
- tx_hashstring | nullRequired
  On-chain transaction hash (populated after broadcast).
  Example: null
- descriptionstringRequired
  Payout description.
  Example: string
- executable_atstring | nullRequired
  Earliest time the payout can be executed.
  - Format: date-time
  Example: null
- completed_atstring | nullRequired
  Completion timestamp.
  - Format: date-time
  Example: null
- created_atstringRequired
  Creation timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- updated_atstringRequired
  Last update timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- failure_reasonstring | nullRequired
  Merchant-facing terminal reason. A failed payout reports destination_rejected for a rejected destination, or internal_error for other failures. A reversed payout reports reorg. Null while queued, processing, confirming, or completed.
  Example: null
- operation_idstring | nullRequired
  Finance operation UUID linked to this payout.
  - Format: uuid
  Example: null
- target_funding_amountstring | nullRequired
  Target-denominated obligation H. It is not a source-gate debit.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- fundingobject | nullRequired
  Frozen multi-source funding and its durable progress. Null for ordinary source-free payouts and historical payouts without accepted economics.
  - Unknown properties are rejected
  Example: null
  - mode"same_asset_only" | "source_only" | "target_first"Required
    Example: same_asset_only
  - service_class"immediate" | "waiting"Required
    Example: immediate
  - direct_target_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - target_ready_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - target_surplus_releasedstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - funding_deadlinestring | nullRequired
    - Format: date-time
    Example: null
  - sourcesarray<object>Required
    Example: [{"conversion_fee_payer":"merchant","source_id":"00000000-0000-0000-0000-000000000001","gate":{"currency":"string","network":"string"},"reserved_gross":"1","exchanged_principal":"1","earned_conversion_fee":"1","refunded_source":"1","outstanding_reserve":"1","target_delivered":"1"}]
    - conversion_fee_payer"merchant" | "platform"Required
      Example: merchant
    - source_idstringRequired
      - Format: uuid
      Example: 00000000-0000-0000-0000-000000000001
    - gateobjectRequired
      - Unknown properties are rejected
      Example: {"currency":"string","network":"string"}
      - currencystringRequired
        Minimum length: 1
        Maximum length: 20
        Example: string
      - networkstringRequired
        Minimum length: 1
        Maximum length: 64
        Example: string
    - reserved_grossstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - exchanged_principalstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - earned_conversion_feestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - refunded_sourcestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - outstanding_reservestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - target_deliveredstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
  - status"converting" | "needs_review" | "ready" | "closed"Required
    Funding lifecycle within the payout. The outer payout status remains processing during converting and needs_review.
    Example: converting
- balance_movementsarray<object>Required
  Example: [{"gate":{"currency":"string","network":"string"},"direction":"credit","amount":"1","credit_amount":"1","debit_amount":"1","reversed_credit_amount":"1","reversed_debit_amount":"1","amount_usd":null}]
  - gateobjectRequired
    - Unknown properties are rejected
    Example: {"currency":"string","network":"string"}
    - currencystringRequired
      - Minimum length: 1
      - Maximum length: 20
      Example: string
    - networkstringRequired
      - Minimum length: 1
      - Maximum length: 64
      Example: string
  - direction"credit" | "debit" | "none"Required
    Example: credit
  - amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - credit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - debit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - reversed_credit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - reversed_debit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - amount_usdstring | nullRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: null
- economics_status"available" | "unavailable"Required
  Available when the original accepted commercial snapshot exists. Unavailable historical economics are null; current prices never reconstruct them.
  Example: available
- metadataobjectRequired
  Merchant key-value metadata; omitted invoice metadata is stored and returned as an empty object.
  - Maximum properties: 50
  Example: {"key":"string"}
  - [key]stringOptional
    - Maximum length: 500
    Example: string
- created_by_idstring | nullRequired
  Dashboard user who created this payout. `null` when it was created through the API or expanded from a batch, which is what tells the two apart.
  - Format: uuid
  Example: null
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-000000000003",
    "currency": "USDC",
    "network": "ethereum",
    "amount": "10.00",
    "recipient_amount": "10.00",
    "amount_in_base_currency": null,
    "network_fee": null,
    "network_fee_currency": null,
    "network_fee_network": null,
    "fee_amount": "0.10",
    "payout_fee_allocation": "merchant",
    "configured_network_fee_amount": "0.00",
    "network_fee_allocation": "platform",
    "destination": "0x0000000000000000000000000000000000000001",
    "destination_tag": null,
    "beneficiary_type": "third_party",
    "status": "queued",
    "environment": "live",
    "tx_hash": null,
    "description": "Withdrawal 1001",
    "executable_at": null,
    "completed_at": null,
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:00:00Z",
    "failure_reason": null,
    "operation_id": null,
    "target_funding_amount": "10.10",
    "funding": null,
    "balance_movements": [],
    "economics_status": "available",
    "metadata": {
      "withdrawal_id": "1001"
    },
    "created_by_id": null
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

400 `validation_error`: Validation error.

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`: Validation error.
  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`: Unauthorized.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unauthorized","message":"string","details":["string"]}
- code"unauthorized"Required
  `unauthorized`: Unauthorized.
  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`: Forbidden. `api_key_ip_forbidden`: Api key ip forbidden.

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`: Forbidden. `api_key_ip_forbidden`: Api key ip forbidden.
  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"
  }
}

404 `not_found`: Not found.

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`: Not found.
  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"
  }
}

500 `internal_error`: Internal error.

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`: Internal error.
  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`: Service unavailable.

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`: Service unavailable.
  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 #

Path Parameters #

Response Body #

Usage notes#

Authorization

Path Parameters

Response Body