From 64bce282609d081e065571c0ce07e6ab6fffb2e6 Mon Sep 17 00:00:00 2001 From: Aimen Sahnoun Date: Mon, 2 Mar 2026 02:04:48 +0400 Subject: [PATCH] =?UTF-8?q?docs(api-features):=20rewrite=20conversion-paym?= =?UTF-8?q?ents=20with=20verified=20API=20behavior=20Refactor=20`api-featu?= =?UTF-8?q?res/conversion-payments.mdx`=20from=20AI-generated=20placeholde?= =?UTF-8?q?r=20content=20into=20endpoint-driven=20documentation=20aligned?= =?UTF-8?q?=20with=20current=20API=20behavior.=20-=20removed=20AI=20warnin?= =?UTF-8?q?g=20banner=20and=20unsupported=20assumptions=20-=20rewrote=20pa?= =?UTF-8?q?ge=20to=20explain=20conversion=20as=20=E2=80=9Cdifferent=20invo?= =?UTF-8?q?ice=20and=20payment=20currencies=E2=80=9D=20=20=20instead=20of?= =?UTF-8?q?=20fiat-only=20behavior=20-=20updated=20conversion=20flow=20to?= =?UTF-8?q?=20a=20step-based=20implementation=20using:=20=20=20-=20POST=20?= =?UTF-8?q?/v2/request=20=20=20-=20GET=20/v2/request/{requestId}/pay=20=20?= =?UTF-8?q?=20-=20GET=20/v2/request/{requestId}=20-=20documented=20status-?= =?UTF-8?q?level=20conversion=20fields=20used=20in=20practice:=20=20=20-?= =?UTF-8?q?=20amountInUsd=20=20=20-=20conversionRate=20=20=20-=20rateSourc?= =?UTF-8?q?e=20=20=20-=20conversionBreakdown=20(for=20partial/multi-paymen?= =?UTF-8?q?t=20cases)=20-=20replaced=20invalid=20currency=20example=20`USD?= =?UTF-8?q?C-base-base`=20with=20valid=20`USDC-base`=20-=20removed=20hidde?= =?UTF-8?q?n/unsupported=20use-case=20references=20and=20kept=20only=20act?= =?UTF-8?q?ive=20links=20-=20standardized=20API=20docs=20reference=20to=20?= =?UTF-8?q?canonical=20OpenAPI=20URL:=20=20=20https://api.request.network/?= =?UTF-8?q?open-api?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-features/conversion-payments.mdx | 74 ++++++++++++++++------------ 1 file changed, 43 insertions(+), 31 deletions(-) diff --git a/api-features/conversion-payments.mdx b/api-features/conversion-payments.mdx index 68ae6f3..4c20238 100644 --- a/api-features/conversion-payments.mdx +++ b/api-features/conversion-payments.mdx @@ -1,45 +1,61 @@ --- title: "Conversion Payments" -description: "Fiat-denominated requests settled in cryptocurrency with real-time conversion" +description: "Requests denominated in one currency and settled in another with conversion at payment time" --- - -**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions). - - ## Overview -Conversion payments allow you to create requests denominated in fiat currencies (USD, EUR) while receiving settlement in cryptocurrency, with automatic exchange rate conversion at payment time. +Conversion payments let you denominate a request in one currency (for example USD) and collect payment in a different currency (for example USDC or ETH). + +This is useful when you want stable invoicing amounts while still collecting crypto on-chain. ## How It Works -```mermaid -graph LR - A[Request: $100 USD] --> B[Real-time Rate] - B --> C[Pay: 0.041 ETH] - C --> D[Receive: 0.041 ETH] -``` + + +Create the request with [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request): + +- `invoiceCurrency`: currency you want to denominate the request in (for example `USD`) +- `paymentCurrency`: currency you want to receive on-chain (for example `USDC-base`) + +The API stores both values and computes payable amounts using the configured rate source. + + + +Use [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}/pay) to get transaction payloads, then execute on-chain. + +At payment time, the converted amount is applied so the request can be settled in `paymentCurrency`. + -**Benefits:** -- Stable pricing in familiar currencies -- Automatic exchange rate handling -- No manual conversion required + +Use [GET /v2/request/{requestId}](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}) to inspect status fields such as: -## Supported Fiat Currencies +- `amountInUsd` +- `conversionRate` +- `rateSource` +- `conversionBreakdown` (for multi-payment or partial-payment scenarios) -- **USD** - US Dollar -- **EUR** - Euro -- **GBP** - British Pound -- **CNY** - Chinese Yuan -- **JPY** - Japanese Yen +When a request is paid in multiple parts, conversion details are returned in the breakdown instead of a single conversion rate value. + + -## Exchange Rate Sources +## Conversion Behavior -Real-time rates from multiple providers ensure accuracy and reliability. +- Single-payment requests can expose a direct `conversionRate` +- Multi-payment or partial-payment requests return detailed `conversionBreakdown` +- Rate source metadata is returned by the status endpoint + +## Supported Currencies and Chains + +Use [Request Network Token List](/resources/token-list) and [Supported Chains and Currencies](/resources/supported-chains-and-currencies) to choose valid `invoiceCurrency` and `paymentCurrency` pairs. + + +Conversion behavior depends on the selected currency pair and network support. + ## Used In - + Professional invoices in fiat @@ -47,12 +63,8 @@ Real-time rates from multiple providers ensure accuracy and reliability. E-commerce pricing - - - Predictable subscription pricing - -## Implementation Details +## API Reference -See [API Reference - Conversion Payments](/api-reference/conversion-payments) for complete technical documentation. \ No newline at end of file +For full endpoint schemas and examples, see [Request Network API Reference](https://api.request.network/open-api).