Overview

A manual conversion exchanges part of your merchant balance into another supported currency and network. It creates its own operation and uses your manual conversion commercial terms. Standalone conversions are live-only. The API key selects the merchant; a test key returns 422 not_live on all four conversion endpoints.

Create a conversion# #

1. Read eligible targets for the source currency and network.
2. Configure your receiver and subscribe to the conversion events below before creating a conversion.
3. Submit a conversion with a persisted idempotency key and decimal-string source_amount.
4. Save operation_id and read the conversion to reconcile its current state.

Creating requires balances:manage; reading requires balances:read. Target availability is checked again during creation and can change after discovery.

Webhooks# #

Subscribe through Developers → Webhooks & deliveries to:

• conversion.completed: settlement and merchant credit committed.
• conversion.failed: the first failed execution; recovery may follow and funds are not necessarily returned.
• conversion.source_restored: source released or returned, including an inventory refusal before any debit.

These events apply to standalone conversions created through the API or dashboard. Invoice auto-conversion and payout funding use their parent object's events. Validation failures without a persisted conversion produce no event. An inventory refusal can return a replayable 201 with source_restored and zero booked amounts because no source was reserved.

Webhook conversion_id and conversion API operation_id identify the same conversion. Use that ID with Get conversion.

Inventory settlement or refusal can complete during the create request. Events with no matching subscriber are not retained, and adding a subscription does not backfill past outcomes.

Deduplicate deliveries by event id. A repeated failed callback or another failed recovery attempt does not create a second conversion.failed. Recovery may subsequently emit conversion.completed or conversion.source_restored. Delivery order is not guaranteed; GET supplies current state.

source_amount is the gross maximum source debit. The merchant-paid conversion fee is included in this amount, not added on top. conversion_amount is the principal to exchange; fee_amount is the planned fee. A platform-paid fee does not increase the merchant debit.

Results and recovery# #

expected_target_amount is the locked expectation, not evidence of a completed credit. Read converted_amount, fee_charged_amount, source_returned_amount, and credited_target_amount for booked results. Keep each amount with its currency and network; never add amounts from different assets into one native total.

After a timeout or unresolved response, retry the original body with the same idempotency key. Do not create another conversion to replace an unknown outcome. Follow idempotency when a refusal explicitly releases a key for correction.