Get

Returns merchant-safe status for one manual conversion operation. The response intentionally omits provider, route, raw processor error and treasury details.

Usage notes#

Requires balances:read. Only operations in the API key’s merchant and environment are visible. Check the lifecycle status and booked native amounts. expected_target_amount is not a completed-credit amount. Do not replace a submitted or stuck operation with a fresh request while its outcome remains unresolved.

Live-only: a test API key returns 422 not_live. See conversion lifecycle and webhooks for completion, failure, recovery, and ID reconciliation.

GET/v1/conversions/{operationID}

curl --request GET 'https://api.thehalfin.com/v1/conversions/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

operationIDstringRequired
- Format: uuid
Example: 00000000-0000-0000-0000-000000000001

Response Body

200 Manual conversion status.

application/json

dataobjectRequired
- Unknown properties are rejected
Example: {"updated_at":"2026-01-01T00:00:00Z","operation_id":"00000000-0000-0000-0000-000000000001","status":"pending_execution","source_currency":"string","source_network":"string","target_currency":"string","target_network":"string","source_amount":"string","expected_target_amount":"string","effective_rate":"string","conversion_amount":"string","fee_amount":"string","fee_currency":"string","fee_network":"string","fee_payer":"merchant","converted_amount":"string","fee_charged_amount":"string","source_returned_amount":"string","credited_target_amount":"string","created_at":"2026-01-01T00:00:00Z","settled_at":null,"source_restored_at":null,"stuck_at":null}
- updated_atstringRequired
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- operation_idstringRequired
  Standalone conversion ID, equal to webhook conversion_id. Use with /v1/conversions/{operationID}.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- status"pending_execution" | "submitted" | "settled" | "failed" | "source_restored" | "stuck"Required
  Merchant lifecycle status. failed is recoverable and may later become settled or source_restored. submitted and stuck are merchant-facing states; the admin ops_status is a separate operational projection, including pending_execution and ops_review_required.
  Example: pending_execution
- source_currencystringRequired
  Example: string
- source_networkstringRequired
  Example: string
- target_currencystringRequired
  Example: string
- target_networkstringRequired
  Example: string
- source_amountstringRequired
  Example: string
- expected_target_amountstringRequired
  Example: string
- effective_ratestringRequired
  Example: string
- conversion_amountstringOptional
  The principal actually exchanged: source_amount minus the merchant-paid fee. The fee is deducted from the amount and never added on top, so source_amount is the ceiling on what this operation may debit.
  Example: string
- fee_amountstringOptional
  The fee withheld from source_amount when the whole principal is exchanged. "0" when the platform covers it, because nothing is then withheld from the merchant.
  Example: string
- fee_currencystringOptional
  Rail of the fee. Always the source rail.
  Example: string
- fee_networkstringOptional
  Example: string
- fee_payer"merchant" | "platform"Optional
  Example: merchant
- converted_amountstringOptional
  Principal the execution actually consumed. "0" until the ledger books it.
  Example: string
- fee_charged_amountstringOptional
  Fee actually charged. "0" until the ledger books it.
  Example: string
- source_returned_amountstringOptional
  Unspent source released back to the available balance. "0" until the ledger books it.
  Example: string
- credited_target_amountstringOptional
  Target amount actually credited to the merchant. It is the frozen obligation scaled by the consumed share, not the amount the venue delivered — gain and loss against it are the platform's position. "0" until the ledger books it.
  Example: string
- created_atstringRequired
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- settled_atstring | nullRequired
  - Format: date-time
  Example: null
- source_restored_atstring | nullRequired
  - Format: date-time
  Example: null
- stuck_atstring | nullRequired
  - Format: date-time
  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": {
    "updated_at": "2026-01-01T00:00:00Z",
    "operation_id": "00000000-0000-0000-0000-000000000001",
    "status": "pending_execution",
    "source_currency": "string",
    "source_network": "string",
    "target_currency": "string",
    "target_network": "string",
    "source_amount": "string",
    "expected_target_amount": "string",
    "effective_rate": "string",
    "conversion_amount": "string",
    "fee_amount": "string",
    "fee_currency": "string",
    "fee_network": "string",
    "fee_payer": "merchant",
    "converted_amount": "string",
    "fee_charged_amount": "string",
    "source_returned_amount": "string",
    "credited_target_amount": "string",
    "created_at": "2026-01-01T00:00:00Z",
    "settled_at": null,
    "source_restored_at": null,
    "stuck_at": null
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

400 `validation_error`: The request format 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 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"
  }
}

404 `not_found`: The conversion does not exist for this merchant.

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 conversion does not exist for this merchant.
  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"
  }
}

422 `not_live`: Manual conversion is available with live API keys only.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"not_live","message":"string","details":["string"]}
- code"not_live"Required
  `not_live`: Manual conversion is available with live API keys only.
  Example: not_live
- 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_live",
    "message": "Manual conversion is available in the live contour only."
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001"
  }
}

500 `internal_error`: The request could not be completed. Contact support with the request ID.

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 request could not be completed. Contact support with the request ID.
  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.

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.
  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