Points Conversion API

Contract version 1.0.0 (accepted on 2026-09-04). Base URL: https://<host>/v1/conversions. JSON, UTF-8. Machine-readable specification: points-conversion.v1.openapi.yaml.

The API converts a balance of the partner’s points programme into WiBX credited to the authenticated user’s wallet, using the whitelabel’s contractual points/BRL rate and the market BRL/WiBX quotation.

Three operations form the contract: quote, credit and reversal (total or partial, at any time). Lookups by identifier complete the cycle.

The beneficiary is always the session user; no user identifier travels in the body. The partner is identified by the whitelabel.

Every credit follows the same path — reserve, settlement queue, credit, reserve closure — with or without stock; the only difference is when the reserve can be taken: immediately, or after the liquidity desk replenishes the stock.

The liquidity desk is Wibx’s counterpart, not the partner’s. Internally: the platform states the need to buy (it does not execute the purchase); every purchase request leaves through a transactional queue (outbox) with retries and alerts; several scheduled credits may be batched into one request; the holding wallet is monitored and a preventive request is issued below a threshold; requests go through manual approval; delivery is recognised from the Treasury balance, after which scheduled credits are released.

Without a session the response is 405. The session is server-side, expires after 7 days of inactivity and renews on every call.

The partner app obtains the session through the platform’s identity federation: POST /v4/accounts/authentication/inbound/jwt with x-api-key, x-whitelabel-id and the partner’s JWT; the response carries the user and the connect.sid cookie.

Response: wiboo-trace-id (equals globalTraceId in the body — quote it to support), traceparent, set-cookie.

• Amounts are decimal strings ("1500", "15.00"); points follows the whitelabel’s decimals.
• Idempotency: partnerReferenceId is unique per whitelabel. Same id + same body → 200 with the original resource; same id + different body → 409. On timeout, resend: there is never a duplicate credit.
• The quote is informational: the credit is always re-quoted; quoteId is correlation only.
• Success: the resource in the body plus globalTraceId. Error: { message, httpCode, status, globalTraceId, eventError: { errorCode, moduleName } }.

settlement.state: RESERVED (reserve taken), SETTLED (user balance updated), PENDING_STOCK (only for SCHEDULED), CANCELLED (pending part cancelled by a reversal).

{ "points": "1500" }

{
  "quoteId": "0192c9f0-6b1e-7a5c-9d2f-3a4b5c6d7e8f",
  "wlc": "155f9cd6-2c5f-41a9-8d3c-ebf0ae433854",
  "points": "1500",
  "brlAmount": "15.00",
  "wibxAmount": "356.29453682",
  "rate": { "pointsPerBrl": "100", "brlPerWibx": "0.0421", "quotationAt": "2026-09-04T14:02:11Z" },
  "expiresAt": "2026-09-04T14:04:11Z",
  "disclaimer": "Cotação de mercado sujeita a variação; o valor final é definido no momento do crédito.",
  "globalTraceId": "…"
}

brlAmount = points ÷ pointsPerBrl; wibxAmount = brlAmount ÷ brlPerWibx.

{
  "partnerReferenceId": "GP-2026-000123",
  "points": "1500",
  "description": "Resgate campanha setembro",
  "quoteId": "0192c9f0-6b1e-7a5c-9d2f-3a4b5c6d7e8f",
  "metadata": { "storeId": "77" }
}

{
  "creditId": "0192c9f1-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
  "partnerReferenceId": "GP-2026-000123",
  "wlc": "155f9cd6-2c5f-41a9-8d3c-ebf0ae433854",
  "status": "CREDITED",
  "points": "1500",
  "brlAmount": "15.00",
  "wibxAmount": "356.29453682",
  "rate": { "pointsPerBrl": "100", "brlPerWibx": "0.0421", "quotationAt": "2026-09-04T14:03:40Z" },
  "createdAt": "2026-09-04T14:03:40Z",
  "expectedBy": null,
  "settlement": { "state": "RESERVED", "reserveId": "6f1c…", "settledAt": null },
  "reversedPoints": "0",
  "globalTraceId": "…"
}

• GET /points/credits/{creditId} — credit status (404 outside the whitelabel).
• GET /points/credits?partnerReferenceId=… — by the partner’s identifier; use after a timeout, before resending.
• GET /points/reversals/{reversalId} — reversal status.

No event push in this version; the partner polls the status.

Reverses a credit in CREDITED or SCHEDULED, totally or partially, at any time. Debited WiBX is proportional to the credit’s original rate — never re-quoted.

{
  "partnerReferenceId": "GP-REV-000045",
  "creditId": "0192c9f1-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
  "points": "500",
  "reason": "CANCELLED_PURCHASE",
  "description": "Cancelamento parcial do pedido 88213"
}

{
  "reversalId": "0192c9f4-8a1b-7c2d-9e3f-4a5b6c7d8e9f",
  "partnerReferenceId": "GP-REV-000045",
  "creditId": "0192c9f1-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
  "wlc": "155f9cd6-2c5f-41a9-8d3c-ebf0ae433854",
  "status": "REVERSED",
  "points": "500",
  "wibxAmount": "118.76484561",
  "reason": "CANCELLED_PURCHASE",
  "createdAt": "2026-09-05T09:12:03Z",
  "settlement": { "state": "RESERVED" },
  "globalTraceId": "…"
}

Rules: points ≤ credit points − reversedPoints (otherwise 422 REVERSAL_EXCEEDS_CREDIT); reason ∈ CANCELLED_PURCHASE | PARTNER_ERROR | FRAUD_SUSPECT | OTHER; a SCHEDULED credit → the pending part is cancelled without debit; insufficient user balance → 202 REVERSAL_PENDING_BALANCE, debited automatically once balance arrives.

1. The user picks the points; the app calls POST /points/quotes and shows wibxAmount with the variation notice.
2. The user confirms; the app calls POST /points/credits with a new partnerReferenceId.
3. 201 CREDITED: the partner debits the points. settlement.state turns SETTLED within seconds.

1. POST /points/credits answers 202 SCHEDULED with expectedBy (72 h); the WiBX amount is already fixed.
2. The partner tells the user the credit is scheduled and debits the points.
3. The platform replenishes the stock and releases; the lookup turns CREDITED, then SETTLED.

Purchase request, approval, replenishment by the desk and release of scheduled credits in creation order at the fixed amount; if the stock covers only part, the rest stays scheduled and a new request is issued.

1. No response: GET /points/credits?partnerReferenceId=….
2. Found: use the resource. 404: resend the same body — idempotency guarantees a single credit.

1. Cancellation on the partner side; POST /points/reversals with the creditId and the points to return.
2. 201 REVERSED: the partner re-credits the points. 202 REVERSAL_PENDING_BALANCE: the debit happens once balance arrives; follow through the lookup.

Until the conversion backend is deployed, every operation answers 501 with the standard error envelope and eventError.errorCode = "APIS-C0001". The contract does not change when the backend lands; only the 501 disappears. No body validation happens during the transition — validate against the OpenAPI specification (local mock).