Skip to content

docs(partial-payments): rewrite with step-by-step implementation guide and clarify API usage #63

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_rewrite_standard-payments_with_verified_api_flow_refactor_api-features_standard-payments.mdx_from_ai-generated_placeholder_content_into_a_clearer_endpoint-driven_page_aligned_with_current_api_behavior._-_remove
Choose a base branch
from
+36 −29
Open

docs(partial-payments): rewrite with step-by-step implementation guide and clarify API usage #63

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
65 changes: 36 additions & 29 deletions api-features/partial-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,39 @@ title: "Partial Payments"
description: "Split payments across multiple transactions and funding sources"
---

<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

Partial payments allow requests to be fulfilled through multiple transactions, enabling split payments, installment plans, and flexible funding approaches.
Partial payments let you settle a request over multiple transactions instead of one full payment.

This is useful for installments, split settlement, and staged collections.

## How It Works

```mermaid
graph TD
A[Request: $1000] --> B[Payment 1: $400]
A --> C[Payment 2: $300]
A --> D[Payment 3: $300]
B --> E[Request Fulfilled]
C --> E
D --> E
```

**Benefits:**
- **Flexible Payment Plans:** Installments and split payments
- **Multiple Funding Sources:** Different wallets, chains, or currencies
- **Risk Management:** Partial fulfillment tracking
<Steps>
<Step title="Create the request">
Create a request with [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request).
</Step>

<Step title="Pay a partial amount">
Fetch payment payload with [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}/pay) and pass `amount` in query parameters to pay only part of the request.

The `amount` query parameter is human-readable and must be greater than 0.
</Step>

<Step title="Repeat until fully paid">
Execute additional partial payments as needed until the request reaches full settlement.
</Step>

<Step title="Track status and breakdown">
Check [GET /v2/request/{requestId}](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}) for status and conversion/payment breakdown fields.
</Step>
</Steps>

## Key Behavior

- Partial payments are applied incrementally against the same request
- Request status reflects progress until full settlement
- For conversion flows, breakdown fields expose paid vs remaining values

## Use Cases

Expand All @@ -42,28 +51,26 @@ graph TD

## Supported Payment Types

Works with all payment types except Crypto-to-fiat payments:
Partial settlement can be used in request-based payment flows where payment payloads are fetched via `GET /v2/request/{requestId}/pay`.

Commonly used with:

- Native & ERC20 payments
- Conversion payments
- Conversion payments
- Crosschain payments
- Batch payments

## Used In

<CardGroup cols={3}>
<CardGroup cols={2}>
<Card title="Invoicing" href="/use-cases/invoicing">
Large invoice installments
</Card>

<Card title="Checkout" href="/use-cases/checkout">
Flexible payment options
</Card>

<Card title="Subscriptions" href="/use-cases/subscriptions">
Partial subscription payments
</Card>
</CardGroup>

## Implementation Details
## API Reference

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