B2B Quoted Purchase Order API

An external B2B partner converts a partner-side asset into WBX for its own authenticated end-user through three endpoints: register a quotation, renew it, and confirm it into a purchase order. The platform resolves the payer wallet automatically, server-side, from the authenticated end-user’s whitelabel and the fluxo value supplied in the request - the partner never sends a payer-company identifier directly. The receiver is always the authenticated end-user’s own wallet. A quotation is valid for a configurable TTL (5 minutes by default) and its locked rate tolerates a configurable drift against the live market rate (±5% by default) before it must be renewed; it can be renewed up to 3 times before a fresh quotation is required. These figures are configured per whitelabel/fluxo, not platform-wide constants.

Confirming a purchase order is synchronous: the WBX transfer executes within the same request, and the response always reflects the final outcome - there is no polling, no webhook, and no separate status-check endpoint.

Every operation below requires an already-authenticated end-user session (connect.sid cookie) - there is no separate partner login and no API key for this API. Before a partner can call any of these three endpoints, the end-user must have completed the platform’s own account login/registration flow, documented in Onboarding. Integrate that flow first; these B2B endpoints only work on top of a session it establishes.

Method	Path	Purpose
POST	/v2/e-commerce/b2b/quoted-purchase-order/quotation	Register a new WBX quotation for the authenticated user
POST	/v2/e-commerce/b2b/quoted-purchase-order/quotation/{quotationId}/renew	Renew a still-valid quotation under the same id, re-locking the rate and resetting the TTL
POST	/v2/e-commerce/b2b/quoted-purchase-order	Confirm a valid quotation into a purchase order, triggering the WBX transfer

Contract accepted; the backend that implements it ships in a later phase, so every operation currently returns 501. There is no PUT, confirm, or reconfirmation endpoint - the partner only ever calls in; the platform never calls back.

Field	Type	Required	Description
fluxo	string	yes	Identifier of the integration flow this quotation belongs to, issued to the partner alongside their credentials. Determines which company wallet will fund the eventual transfer; validated server-side before any wallet is resolved.
tokenQuantity	string	yes	Quantity of WBX being quoted, up to 18 decimal places.

Field	Type	Required	Description
quotationId	string	yes	Prefixed identifier (qt- + UUIDv4), e.g. qt-3fa85f64-5717-4562-b3fc-2c963f66afa6.
rate	string	yes	Live WBX exchange rate locked for this quotation, expressed as USD per 1 WBX, up to 18 decimal places.
expiresAt	string (date-time)	yes	Date and time after which this quotation is no longer valid.

No request body - the quotation id travels in the path. Renewal reuses and re-locks the same quotation resource under the same quotationId; it is a distinct action, not a fresh registration. Renewal is capped at 3 calls per quotationId (~20 minutes total exposure); a 4th renewal attempt is rejected (see error contract below) and a fresh quotation must be requested from the register endpoint instead. The rate-variation check on a renewal is measured against the original locked rate, not the previous renewal, so repeated small renewals cannot drift the price far from where the quotation started.

Same shape as the registration response above: quotationId, rate, expiresAt.

Field	Type	Required	Description
partnerOrderId	string	yes	Partner-supplied idempotency key. A retried call with the same value returns the original result (200, same body) instead of dispatching a second transfer.
quotationId	string	yes	The previously registered, still-valid quotation this purchase order confirms.
tokenQuantity	string	yes	Quantity of WBX being purchased, up to 18 decimal places. Must match the quantity the partner originally submitted when registering the referenced quotation - that value is not echoed back by the quotation response, so the partner must retain it on their own side.

A 200 response means the transfer already executed - settlement is synchronous, there is nothing further to poll or wait for.

Field	Type	Required	Description
purchaseOrderId	string	yes	Prefixed identifier (po- + UUIDv4), e.g. po-3fa85f64-5717-4562-b3fc-2c963f66afa6.
status	string	yes	Always CONFIRMED on a 200 response - the WBX transfer has already settled. Any rejection is returned as a non-200 error (see below), never as a different status value.
transferredAt	string (date-time)	yes	Date and time the WBX transfer settled. Always present on a 200 response.

Every error response uses the platform’s standard envelope (errorCode, message, httpCode). Authentication failures use 405, matching the convention of the rest of the e-commerce API.

HTTP status	errorCode	Endpoint(s)	When
405	(session convention)	all	No valid authenticated session (connect.sid).
403	PGH-B0001	quotation, confirm	The fluxo in the request is not authorized for the calling credential, or does not match the caller’s whitelabel.
404	PGH-B0002	renew, confirm	quotationId does not exist.
409	PGH-B0003	renew, confirm	The quotation’s TTL has elapsed.
409	PGH-B0004	renew, confirm	The live rate has drifted beyond the configured tolerance against the quotation’s original locked rate.
409	PGH-B0005	renew	The quotation has already been renewed 3 times; request a new quotation instead.
422	PGH-B0006	confirm	tokenQuantity does not match the quantity originally submitted when the referenced quotation was registered.

A 409 from PGH-B0003 or PGH-B0004 on confirm means the quotation must be renewed (if renewals remain) or re-registered before retrying; the failed call is not itself retried with the same quotationId.

Every operation requires the same session-cookie authentication (connect.sid) as the rest of the e-commerce API - the partner never has its own login; the end-user’s session already exists in the integrated environment.

The full machine-readable contract for these three operations is published under the existing “E-commerce” tag of the platform’s OpenAPI specification, version 4.2.0:

• Register a quotation
• Renew a quotation
• Confirm a purchase order