Skip to content

docs(conversion-payments): rewrite with step-by-step implementation guide and remove AI-generated warning #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aimensahnoun wants to merge 1 commit into
base: 03-02-docs_api-features_refocus_payment-types-overview_on_type_selection_clean_up_api-features_payment-types-overview.mdx_to_avoid_overlap_with_request_workflow_documentation_and_keep_this_page_focused_on_payment_type_navigation_and_d
Choose a base branch
from
+43 −31
Open

docs(conversion-payments): rewrite with step-by-step implementation guide and remove AI-generated warning #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 43 additions & 31 deletions api-features/conversion-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,70 @@
---
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"
---

<Warning>
**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).
</Warning>

## 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]
```
<Steps>
<Step title="Create a request with different invoice and payment currencies">
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.
</Step>

<Step title="Fetch payment calldata and execute payment">
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`.
</Step>

**Benefits:**
- Stable pricing in familiar currencies
- Automatic exchange rate handling
- No manual conversion required
<Step title="Check payment status and conversion details">
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.
</Step>
</Steps>

## 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.

<Info>
Conversion behavior depends on the selected currency pair and network support.
</Info>

## Used In

<CardGroup cols={3}>
<CardGroup cols={2}>
<Card title="Invoicing" href="/use-cases/invoicing">
Professional invoices in fiat
</Card>

<Card title="Checkout" href="/use-cases/checkout">
E-commerce pricing
</Card>

<Card title="Subscriptions" href="/use-cases/subscriptions">
Predictable subscription pricing
</Card>
</CardGroup>

## Implementation Details
## API Reference

See [API Reference - Conversion Payments](/api-reference/conversion-payments) for complete technical documentation.
For full endpoint schemas and examples, see [Request Network API Reference](https://api.request.network/open-api).