feat: add complete integration tutorial with Node.js backend and React frontend by aimen74 · Pull Request #54 · RequestNetwork/mintlify-docs

aimen74 · 2026-03-02T00:57:23Z

TL;DR

Added a comprehensive integration tutorial that walks developers through building a complete payment application using Request Network API with Node.js backend and React frontend.

What changed?

Created a new integration tutorial (api-setup/integration-tutorial.mdx) that provides:

Step-by-step backend setup using Fastify, Drizzle ORM, and SQLite
API key configuration and Request Network API integration
Payment creation endpoint that interfaces with /v2/payouts
Webhook implementation for real-time payment status tracking
Complete React frontend with wallet connection using wagmi
Payment creation form and payment status viewing interface
End-to-end payment flow demonstration using Sepolia testnet

Added supporting images showing UI components, API portal screenshots, database views, and transaction signing flows.

How to test?

Follow the backend setup instructions to create the Node.js API server
Obtain API keys from the Request Network portal
Set up ngrok for local webhook testing
Create the React frontend application
Connect a MetaMask wallet with Sepolia ETH
Create a payment between two wallet addresses
Observe the payment status updates through webhooks

Why make this change?

This tutorial addresses the need for comprehensive developer onboarding by providing a complete, working example that demonstrates:

Real-world integration patterns with Request Network API
Proper webhook handling for payment tracking
Frontend wallet integration best practices
End-to-end payment flow implementation

The tutorial bridges the gap between basic API documentation and practical implementation, giving developers a solid foundation to build upon.

aimen74 · 2026-03-02T00:57:34Z

docs(review): apply Tristan's two must-fix items from the final review #97
docs(review): address Greptile review feedback across the stack #96
docs(feedback): apply Tristan's revisions from RequestNetwork/request-api#806 #95
docs(kyt): document KYT-screened payments as a use case + payee-destination field #94
docs(secure-payments): document redirectUrl + redirectLabel #93
docs(verify): fix broken cross-refs surfaced by mintlify broken-links #92
docs(scripts): add Playwright screenshot capture scaffolding #91
docs(content): add use-case pages, Dashboard + Secure Payment tools pages #90
docs(content): refresh Tron coverage, batch-payment EVM scope, webhook 12-event list #89
docs(nav): restructure navigation, remove legacy pages, retire Portal #88
docs: fix broken links and clarify edge cases #87
docs: add missing feature documentation for recent API changes #86
docs: fix implementation discrepancies across API docs #85
docs: remove beta banner and legacy SDK tab #78
Remove AI-generated content warnings and update internal links #77
docs(lifecycle): replace external image with local asset and remove AI-generated warning #76
docs: remove AI-generated content warnings and simplify Request Scan page #75
docs(resources): remove community page from navigation #74
docs(supported-chains): add Tron network support and enhance currency documentation #73
docs(supported-chains): streamline supported chains and currencies documentation #72
docs(api-reference): add v2 endpoints overview and switch docs OpenAPI to v2-only spec Improve API Reference navigation by introducing a dedicated Endpoints Overview page in docs and wiring Mintlify OpenAPI rendering to a local v2-only spec. - add `api-re #71
docs(authentication): simplify auth guide with API key vs Client ID methods and remove AI-generated content #70
docs(fee-breakdowns): rewrite to focus on API response locations and reconciliation usage #69
docs(protocol-fees): add protocol fees documentation and navigation #68
docs(platform-fees): simplify configuration guide and remove AI-generated content warning #67
docs(query-payments): rewrite with practical implementation focus and remove AI warning #66
docs(query-requests): simplify and refactor query requests documentation for practical implementation #65
docs(payment-detection): simplify content and remove AI warning #64
docs(partial-payments): rewrite with step-by-step implementation guide and clarify API usage #63
docs(standard-payments): remove AI warning, restructure content with step-by-step flow, and update API references #62
docs(conversion-payments): rewrite with step-by-step implementation guide and remove AI-generated warning #61
docs(payment-types): simplify overview and add payment type selection guidance #60
docs(crypto-to-fiat): expand comprehensive guide with sandbox access, compliance flows, and implementation details #59
docs(recurring-payments): rewrite with comprehensive workflow, security details, and practical implementation guide #58
docs(batch-payments): add comprehensive implementation guide with examples, workflow diagrams, and demo videos #57
docs(crosschain-payments): replace AI-generated content with comprehensive implementation guide #56
docs(create-requests): rewrite with workflows, examples, and remove AI warning #55
feat: add complete integration tutorial with Node.js backend and React frontend #54 👈 (View in Graphite)
docs(getting-started): remove AI warning and refactor to focus on practical payment integration #53
docs(api-portal): remove AI warning, add local screenshot, and update .gitignore #52
docs: remove release notes section and streamline use cases to core features #51
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

greptile-apps · 2026-03-02T12:09:12Z

Greptile Summary

This PR adds a new end-to-end integration tutorial (api-setup/integration-tutorial.mdx) walking developers through building a payment application with a Node.js/Fastify backend and a React/wagmi frontend on top of the Request Network API. It also registers the page in docs.json navigation and adds 21 supporting screenshot assets.

Backend: Sets up Fastify + Drizzle ORM + SQLite, creates /payments (POST/GET/PATCH) endpoints that call /v2/payouts, and adds a webhook handler with HMAC signature verification for real-time payment status updates.
Frontend: Scaffolds a Vite/React app with wagmi wallet connection, a payment-creation form that executes on-chain transactions, and a polling payment-status view.
Flow: Guides the developer from project setup through API key/ngrok configuration to a full end-to-end Sepolia testnet payment cycle.

Confidence Score: 3/5

Hold for fixes before merging — two code examples contain defects that will prevent developers from successfully following the tutorial as written.

The WalletConnect component uses React.FC without importing React, causing a TypeScript compilation error for anyone copying the snippet verbatim. The webhook HMAC is computed over a re-serialized JavaScript object rather than the raw request bytes, meaning the signature check will silently fail for real-world webhook deliveries — undermining the payment-confirmation security the tutorial is meant to demonstrate.

api-setup/integration-tutorial.mdx — the WalletConnect component block and both webhook handler blocks need corrections.

Security Review

Broken webhook signature verification (api-setup/integration-tutorial.mdx, webhook handler): The HMAC is computed over JSON.stringify(request.body) \u2014 a re-serialized JavaScript object \u2014 rather than the raw request body bytes. Request Network signs the original byte stream before transmission, so differences in whitespace, key order, or encoding will cause legitimate webhooks to be rejected.
Broad CORS origin (origin: true): Both server setup code blocks use origin: true with only an inline comment suggesting restriction in production; a Mintlify Warning callout would make this more visible to readers.

Important Files Changed

Filename	Overview
api-setup/integration-tutorial.mdx	New 1516-line integration tutorial; contains a missing React import that prevents the WalletConnect component from compiling, a webhook HMAC computed over re-serialized JSON instead of the raw request body, misplaced dev-only packages in `dependencies`, and inconsistent import paths between two App.tsx code snippets.
docs.json	Adds `api-setup/integration-tutorial` to the API tab navigation under the API Setup group — correctly placed and no structural issues.

Sequence Diagram

sequenceDiagram
participant User
participant Frontend as React Frontend
participant Backend as Node.js Backend
participant RN as Request Network API
participant Webhook as Webhook Handler
User->>Frontend: Fill payment form and submit
Frontend->>Backend: POST /payments
Backend->>RN: POST /v2/payouts (X-Api-Key)
RN-->>Backend: requestId, transactions, metadata
Backend->>Backend: INSERT payment status pending
Backend-->>Frontend: payment and calldata
Frontend->>User: Prompt wallet signature
User->>Frontend: Sign and send transaction
Frontend->>Backend: PATCH /payments/:id status in-progress
Note over RN,Webhook: On-chain confirmation detected
RN->>Webhook: POST /webhooks with signature header
Webhook->>Webhook: Verify HMAC signature
Webhook->>Backend: UPDATE payment SET status confirmed
Backend-->>Frontend: polled every 3s status confirmed
Frontend->>User: Show payment confirmed

_{Reviews (2): Last reviewed commit: "docs(api-setup): migrate Integration Tut..." | Re-trigger Greptile}

greptile-apps

_{21 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-03-02T12:09:25Z

Additional Comments (1)

images/api-setup/integration-tutorial/wallet-conencted.webp
Rename file to wallet-connected.webp to fix typo

Bundles two passes of Greptile feedback: (A) PR #96 follow-up — the fixes PR itself attracted two new comments: - use-cases/programmatic-payment-links.mdx: cURL language tag bash → curl - RN_API_KEY → RN_CLIENT_ID and X-Api-Key → x-client-id renamed across api-setup/integration-tutorial.mdx, api-setup/getting-started.mdx, api-features/create-requests.mdx for stack-wide consistency. Zero RN_API_KEY / X-Api-Key references remain. (B) Older PRs (51-87) — 23 still-applicable comments out of 51 total. The other 28 are stale (resolved by the revamp rewriting or removing the relevant sections/files); those will be resolved on GitHub with a note explaining staleness. PR #53 — getting-started.mdx - Added Express setup (express + app.use(express.json())) before the webhook handler example so the snippet is runnable. PR #54 — integration-tutorial.mdx - Added missing `import { eq } from 'drizzle-orm';`. - Fixed spelling "succesfully" → "successfully". PR #55 — create-requests.mdx - v2 pay endpoint takes requestId, not paymentReference (mermaid + code sample updated to `${requestId}/pay`). PR #56 + #87 — crosschain-payments.mdx - Boundary wording: "under \$1" → "of \$1 or less" to align with the "greater than 1 USD" half of the sentence. - viem snippet now imports createPublicClient + http and instantiates publicClient so `publicClient.waitForTransactionReceipt(...)` works. PR #57 — batch-payments.mdx - Code samples now use x-client-id (consistent with rest of docs), dropped legacy x-platform-id, added `if (!response.ok)` error handling on both examples. PR #59 — crypto-to-fiat-payments.mdx - "I**mportant:" → "**Important:" - mermaid: {payerId} → {clientUserId} (twice). - Endpoint paths: /payer → /v2/payer for consistency. - mermaid: declared "Payee Bank" as a participant (was used but never declared, breaking the diagram). PR #66 — query-payments.mdx - Frontmatter description: /payments → /v2/payments. PR #67 — platform-fees.mdx - Clarified query- vs body-param scope: GET /v2/request/{id}/pay uses query params; POST /v2/payouts and /payouts/batch use body params. PR #68 — protocol-fees.mdx - Grammar: "protocol fees applies" → "protocol fee applies". - Typo: "simple reduce" → "simply reduce". - Math: payee receives 999.50 USDC (not 999.95). Added intermediate invoice/fee lines for transparency. PR #77 — faq.mdx - On-ramp question now explicitly answered: "Fiat-to-crypto (on-ramp) payments are not currently supported by the API." PR #86 — payouts.mdx - "ERC-712" → "EIP-712" (correct EIP designation). PR #86 — api-reference/secure-payments.mdx - expiresAt example: 15 minutes → 7 days, matching the documented default expiry. PR #87 — payouts.mdx - Added "500" row to error-handling table. mintlify broken-links: zero.

We will drop the Codesandbox link.

rodrigopavezi · 2026-05-12T16:02:52Z

Merge activity

May 12, 4:02 PM UTC: A user started a stack merge that includes this pull request via Graphite.
May 12, 4:08 PM UTC: Graphite rebased this pull request as part of a merge.
May 12, 4:08 PM UTC: @rodrigopavezi merged this pull request with Graphite.

Migrate complete Integration Tutorial from legacy GitBook to Mintlify, converting all 19 external image URLs to local webp assets for improved performance and reliability. Content Migration: - Port full Integration Tutorial content from /request-network-api/integration-tutorial - Backend setup: Fastify + Drizzle + SQLite configuration with complete code - Frontend implementation: React + Vite + wagmi wallet integration - Webhook handling with signature verification examples - Step-by-step walkthrough from API key creation to payment confirmation Format Conversions: - Convert GitBook <figure> tags to Mintlify <Frame> components - Transform markdown image syntax to JSX <img> tags for MDX compatibility - Remove angle brackets around URLs to prevent JSX parsing errors - Add frontmatter (title, description) for Mintlify page structure Image Localization: - Download and convert all 19 tutorial screenshots to webp format - Organize images in images/api-setup/integration-tutorial/ directory - Replace all external gitbook.io URLs with local paths - Images included: folder-structure, api-portal steps, database-studio, ngrok-terminal, webhook steps, vite-setup, UI components, wallet states, payment flows, and confirmation screenshots Navigation: - Add Integration Tutorial to docs.json API Setup section - Position between Getting Started and API Portal docs for logical flow Performance: - Eliminate external image dependencies (19 GitBook URLs removed) - Reduce page load times with local webp assets - Enable offline documentation viewing All content preserved exactly from legacy docs with only necessary format conversions for Mintlify compatibility.

greptile-apps · 2026-05-12T16:12:20Z

+import { useAccount, useConnect, useDisconnect } from 'wagmi'
+import './styles.css';
+
+const WalletConnect: React.FC = () => {
+ const { address, isConnected } = useAccount()


Missing React import — component won't compile
The WalletConnect component uses React.FC as its type annotation but never imports React. TypeScript will fail with Cannot find name 'React' at build time. Compare this with CreatePayment and ViewPayments, which both open with import React from 'react';. The React namespace must be imported for React.FC to be resolvable, even when JSX auto-transform is enabled (the transform covers JSX syntax, not namespace access).

greptile-apps · 2026-05-12T16:12:21Z

+
+ const expectedSignature = crypto.createHmac('sha256', webhookSecret)
+ .update(JSON.stringify(body))
+ .digest('hex');
+
+ if (signature !== expectedSignature) {
+ fastify.log.error('Invalid webhook signature');
+ return reply.status(401).send({ error: 'Invalid signature' });
+ }


Webhook HMAC computed over re-serialized JSON, not the raw request body
The tutorial computes the expected signature with JSON.stringify(body) where body is already the Fastify-parsed JavaScript object. The webhook sender (Request Network) signs the original raw bytes of the HTTP body before it is parsed. Re-stringifying a parsed object may produce different bytes — different whitespace, different key ordering, Unicode normalization — causing the comparison to fail for valid webhooks. The standard pattern is to capture the raw body buffer using Fastify's addContentTypeParser, then run the HMAC over those bytes, and parse the JSON separately afterward.

Bundles two passes of Greptile feedback: (A) PR #96 follow-up — the fixes PR itself attracted two new comments: - use-cases/programmatic-payment-links.mdx: cURL language tag bash → curl - RN_API_KEY → RN_CLIENT_ID and X-Api-Key → x-client-id renamed across api-setup/integration-tutorial.mdx, api-setup/getting-started.mdx, api-features/create-requests.mdx for stack-wide consistency. Zero RN_API_KEY / X-Api-Key references remain. (B) Older PRs (51-87) — 23 still-applicable comments out of 51 total. The other 28 are stale (resolved by the revamp rewriting or removing the relevant sections/files); those will be resolved on GitHub with a note explaining staleness. PR #53 — getting-started.mdx - Added Express setup (express + app.use(express.json())) before the webhook handler example so the snippet is runnable. PR #54 — integration-tutorial.mdx - Added missing `import { eq } from 'drizzle-orm';`. - Fixed spelling "succesfully" → "successfully". PR #55 — create-requests.mdx - v2 pay endpoint takes requestId, not paymentReference (mermaid + code sample updated to `${requestId}/pay`). PR #56 + #87 — crosschain-payments.mdx - Boundary wording: "under \$1" → "of \$1 or less" to align with the "greater than 1 USD" half of the sentence. - viem snippet now imports createPublicClient + http and instantiates publicClient so `publicClient.waitForTransactionReceipt(...)` works. PR #57 — batch-payments.mdx - Code samples now use x-client-id (consistent with rest of docs), dropped legacy x-platform-id, added `if (!response.ok)` error handling on both examples. PR #59 — crypto-to-fiat-payments.mdx - "I**mportant:" → "**Important:" - mermaid: {payerId} → {clientUserId} (twice). - Endpoint paths: /payer → /v2/payer for consistency. - mermaid: declared "Payee Bank" as a participant (was used but never declared, breaking the diagram). PR #66 — query-payments.mdx - Frontmatter description: /payments → /v2/payments. PR #67 — platform-fees.mdx - Clarified query- vs body-param scope: GET /v2/request/{id}/pay uses query params; POST /v2/payouts and /payouts/batch use body params. PR #68 — protocol-fees.mdx - Grammar: "protocol fees applies" → "protocol fee applies". - Typo: "simple reduce" → "simply reduce". - Math: payee receives 999.50 USDC (not 999.95). Added intermediate invoice/fee lines for transparency. PR #77 — faq.mdx - On-ramp question now explicitly answered: "Fiat-to-crypto (on-ramp) payments are not currently supported by the API." PR #86 — payouts.mdx - "ERC-712" → "EIP-712" (correct EIP designation). PR #86 — api-reference/secure-payments.mdx - expiresAt example: 15 minutes → 7 days, matching the documented default expiry. PR #87 — payouts.mdx - Added "500" row to error-handling table. mintlify broken-links: zero.

This was referenced Mar 2, 2026
docs: remove release notes section and streamline use cases to core features #51
Merged
docs(api-portal): remove AI warning, add local screenshot, and update .gitignore #52
Merged

aimen74 requested review from MantisClone, bassgeta and rodrigopavezi March 2, 2026 12:02

aimen74 self-assigned this Mar 2, 2026

aimen74 changed the title ~~Add complete integration tutorial with Node.js backend and React frontend~~feat: add complete integration tutorial with Node.js backend and React frontendMar 2, 2026

aimen74 marked this pull request as ready for review March 2, 2026 12:03

greptile-appsBot reviewed Mar 2, 2026
View reviewed changes

Comment threadapi-setup/integration-tutorial.mdx
Comment threadapi-setup/integration-tutorial.mdx
Comment threadapi-setup/integration-tutorial.mdx
Comment threadapi-setup/integration-tutorial.mdx

This was referenced Mar 30, 2026
docs: fix implementation discrepancies across API docs #85
Merged
docs: add missing feature documentation for recent API changes #86
Merged
docs: fix broken links and clarify edge cases #87
Merged

rodrigopavezi requested a review from bassgeta May 11, 2026 15:20

rodrigopavezi mentioned this pull request May 12, 2026
docs(review): apply Tristan's two must-fix items from the final review #97
Merged

rodrigopavezi changed the base branch from graphite-base/54 to mainMay 12, 2026 16:06

rodrigopavezi merged commit 637a7bb into mainMay 12, 2026
2 checks passed

rodrigopavezi deleted the 03-01-docs_api-setup_migrate_integration_tutorial_with_localized_images_migrate_complete_integration_tutorial_from_legacy_gitbook_to_mintlify_converting_all_19_external_image_urls_to_local_webp_assets_for_improved_performance_and_reli branch May 12, 2026 16:08

greptile-appsBot reviewed May 12, 2026
View reviewed changes

Navigation Menu

Uh oh!

feat: add complete integration tutorial with Node.js backend and React frontend - #54

aimen74 commented Mar 2, 2026•
edited
Loading

Uh oh!

aimen74 commented Mar 2, 2026•
edited
Loading

Uh oh!

greptile-appsBot commented Mar 2, 2026•
edited
Loading

Security Review

Uh oh!

greptile-appsBot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-appsBot commented Mar 2, 2026

Uh oh!

rodrigopavezi commented May 12, 2026•
edited
Loading

Uh oh!

Uh oh!

greptile-appsBotMay 12, 2026

Uh oh!

greptile-appsBotMay 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

aimen74 commented Mar 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

What changed?

How to test?

Why make this change?

Uh oh!

aimen74 commented Mar 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-appsBot commented Mar 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 3/5

Security Review

Important Files Changed

Sequence Diagram

Uh oh!

greptile-appsBot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-appsBot commented Mar 2, 2026

Uh oh!

rodrigopavezi commented May 12, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

greptile-appsBotMay 12, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-appsBotMay 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aimen74 commented Mar 2, 2026•
edited
Loading

aimen74 commented Mar 2, 2026•
edited
Loading

greptile-appsBot commented Mar 2, 2026•
edited
Loading

rodrigopavezi commented May 12, 2026•
edited
Loading