Flexible redemption, LIFO; fixed-term products cannot be redeemed early

POST /v1/earn/redemptions scope: earn:write

On behalf of a member · x-on-behalf-of required Requires x-idempotency-key Moves funds · Earn account → member available balance, principal plus accrued interest

This endpoint moves funds

See the response table below for failure handling. Retry timeouts (504) with the same idempotency key — we may already have processed the request; use a new key after a business failure; the same key replays that failure.

Flexible products only. Fixed-term products have no redemption endpoint. Client-side early redemption is prohibited by product design; offering an endpoint would falsely imply support. We automatically settle fixed-term principal and interest at maturity.

Redemption is LIFO, consuming the part not yet accruing interest first. A same-day subscription and redemption therefore neither consumes yesterday’s accruing principal nor earns interest.

⚠ Interest is integrated across rate segments with hourly precision and rounded only at payment, carrying remainders forward. interest can therefore be 0 when it has not reached one minimum ledger unit; this is not an error.

⚠ credited is the amount actually returned to available balance, equal to principal + interest. Read this field rather than adding them yourself.

⚠ This endpoint has no reversal operation; once redemption executes, the funds are already available.

Prerequisites

Target product kind is flexible; fixed-term input is rejected immediately
Member has a flexible position in this product and redemption does not exceed its principal

Field	Type	Required	Description
`x-on-behalf-of`	string	Required	Member for whom redemption is made.
`x-idempotency-key`	string	Required
`x-step-up`	string	Optional	UUID. Same-key replay retrieves the previous result without a second redemption.

Request Body

Field	Type	Required	Description
`product_id`	string	Required	Flexible product ID, with or without `ern_`.
`amount`	string	Optional	Principal to redeem. Fixed-point string using the product’s `ledger_scale`. Ignored with `all: true`.USDT uses 6 decimals, for example 500.000000
`all`	boolean	Optional	`true` redeems everything, zeroing principal and closing the position. ⚠ The criterion is strict equality to `true`; the string `"true"` does not count.

Response

201Redeemed. All three amounts are fixed-point decimal strings using the product’s ledger_scale. closed indicates whether this redemption emptied the position. Same-key replay adds duplicated: true, but HTTP remains 201, unlike the 200 used by exchange/transfers. Identify replay from the field, not the status code.

{
  "id": "err_2f80c5a7-6d19-4b3e-a0c8-4e91b7d25036",
  "principal": "500.000000",
  "interest": "0.412300",
  "credited": "500.412300",
  "closed": false
}

400Registered public codes: invalid_request, amount format or invalid body; product_not_available, nonexistent product; state_invalid, fixed-term product without redemption support; step_up_required, strong authentication required, action earn_redeem:<product_id>; idempotency_key_required; idempotency_key_invalid; member_context_required; member_not_found. ⚠ Still returning 500 api_error: member has no position in the product; redemption exceeds principal; amount ≤ 0.

409idempotency_key_reused · idempotency_in_progress

Request

curl -X POST 'https://api.zinfra.vip/v1/earn/redemptions' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
    "amount": "500.000000"
  }'

const res = await fetch("https://api.zinfra.vip/v1/earn/redemptions", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
    "amount": "500.000000"
  }),
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();

import requests

res = requests.post(
    "https://api.zinfra.vip/v1/earn/redemptions",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
      "amount": "500.000000"
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()

req, _ := http.NewRequest("POST", "https://api.zinfra.vip/v1/earn/redemptions",
    strings.NewReader(`{
  "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
  "amount": "500.000000"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/earn/redemptions"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
  "amount": "500.000000"
}
"""))
    .build();
// Use String / BigDecimal for amounts, not double.

$ch = curl_init('https://api.zinfra.vip/v1/earn/redemptions');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "product_id": "ern_3a91f0c2-5d17-4e88-b2a0-91c7d4e6b501",
  "amount": "500.000000"
}
JSON,
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.

201

{
  "id": "err_2f80c5a7-6d19-4b3e-a0c8-4e91b7d25036",
  "principal": "500.000000",
  "interest": "0.412300",
  "credited": "500.412300",
  "closed": false
}

Flexible redemption, LIFO; fixed-term products cannot be redeemed early

Prerequisites

Request Headers

Request Body

Response