docs(secure-payments): add standalone Secure Payment Pages docs and API reference, clarify support model, and simplify integration guidance

api-features/secure-payment-pages.mdx

@@ -0,0 +1,78 @@
+---
+title: "Secure Payment Pages"
+description: "Create hosted secure payment links and let payers complete payments from a dedicated secure flow."
+---
+
+## Overview
+
+Secure Payment Pages let you generate a hosted payment URL from the API and redirect the payer to a dedicated payment experience.
+
+This feature is useful when you want to reduce frontend tampering risk and separate payment execution from your checkout UI.
+
+## Built-in contract safety check
+
+Before signing, the secure page validates that the transaction targets official Request Network contracts.
+
+The payer-facing status copy is:
+- "This is a safe smart contract"
+- "The smart contract you are interacting with is an official Request Network smart contract, it is audited and valid."
+
+If validation fails, the secure page warns the payer and prevents continuing with unsafe contract interactions.
+
+## How the flow works
+
+<Steps>
+  <Step title="Create a secure payment link">
+    Call `POST /v2/secure-payments` with one or more requests.
+
+    The API creates Request records and returns:
+    - `requestIds`
+    - `token`
+    - `securePaymentUrl`
+  </Step>
+
+  <Step title="Redirect the payer to the hosted page">
+    Send the payer to `securePaymentUrl`.
+  </Step>
+
+  <Step title="Payer reviews payment details">
+    The hosted page loads the payment details and prepares the required transaction flow.
+  </Step>
+
+  <Step title="Sign and submit payment transactions">
+    The payer signs the returned transaction set from their wallet. Depending on token approvals, this can be one or more transactions.
+  </Step>
+</Steps>
+
+## Authentication
+
+Both secure payment endpoints accept:
+- `x-api-key`, or
+- `x-client-id` with browser `Origin`
+
+See [Authentication](/api-reference/authentication) for implementation options.
+
+## API Reference
+
+<Card title="POST /v2/secure-payments" icon="code" href="/api-reference/v2secure-payment/create-a-secure-payment-entry">
+  Create a secure payment entry and return a hosted secure payment URL. View the complete endpoint documentation with request/response schemas and examples.
+</Card>
+
+## Status outcomes
+
+- `200`: token is valid and payable
+- `403`: token expired or status is not payable
+- `404`: token not found
+- `409`: payment already completed
+
+## Next pages
+
+<CardGroup cols={2}>
+  <Card title="Secure Payments API Reference" icon="book" href="/api-reference/secure-payments">
+    Endpoint details, request and response schemas, and error codes.
+  </Card>
+
+  <Card title="Supported Networks and Currencies" icon="globe" href="/api-features/secure-payment-supported-networks-and-currencies">
+    Check supported chain and currency coverage before creating links.
+  </Card>
+</CardGroup>

api-features/secure-payment-supported-networks-and-currencies.mdx

@@ -0,0 +1,55 @@
+---
+title: "Secure Payment Supported Networks and Currencies"
+description: "Chain and currency coverage for Secure Payment Pages."
+---
+
+## Coverage model
+
+Secure Payment Pages use the same chain and currency coverage as standard Request API request flows.
+
+This means supported options are the networks and currencies available through the API token list and request creation endpoints.
+
+## Supported currencies
+
+Currencies are determined by the Request token list and available per network.
+
+Use `GET /v2/currencies` to query support by network.
+
+<RequestExample>
+```bash cURL
+curl -X GET "https://api.request.network/v2/currencies?network=sepolia" \
+  -H "x-api-key: YOUR_API_KEY"
+```
+</RequestExample>
+
+<ResponseExample>
+```json Example
+[
+  {
+    "id": "FAU-sepolia",
+    "name": "FAU",
+    "symbol": "FAU",
+    "decimals": 18,
+    "network": "sepolia",
+    "type": "ERC20",
+    "chainId": 11155111
+  }
+]
+```
+</ResponseExample>
+
+## How to verify support
+
+- Query `GET /v2/currencies` with `network` and `symbol` filters for discovery
+- Validate currency IDs before calling `POST /v2/secure-payments`
+- Use the same network and currency validation rules you apply to normal request flows
+
+<Info>
+For an at-a-glance list of ecosystem support, see [Supported Chains and Currencies](/resources/supported-chains-and-currencies).
+</Info>
+
+## Preflight checklist
+
+- Confirm each currency ID exists in `GET /v2/currencies`
+- Confirm each request network is supported by your target flow
+- Confirm your selected currencies are available on those networks

api-reference/secure-payments.mdx

@@ -0,0 +1,166 @@
+---
+title: "Secure Payments API Reference"
+description: "Generate secure payment URLs and retrieve token-based payment calldata."
+---
+
+## Endpoints
+
+- `POST /v2/secure-payments`
+- `GET /v2/secure-payments/:token`
+
+## Authentication
+
+Both endpoints support:
+- `x-api-key`, or
+- `x-client-id` with browser `Origin`
+
+## POST /v2/secure-payments
+
+Create a secure payment entry and return a hosted payment URL.
+
+### Request fields
+
+<ParamField body="requests" type="array" required>
+Array of payment requests. One item creates a single payment. Multiple items create a batch payment.
+</ParamField>
+
+<ParamField body="requests[].payee" type="string" required>
+Payee EVM address.
+</ParamField>
+
+<ParamField body="requests[].amount" type="string" required>
+Human-readable amount.
+</ParamField>
+
+<ParamField body="requests[].invoiceCurrency" type="string" required>
+Invoice currency ID.
+</ParamField>
+
+<ParamField body="requests[].paymentCurrency" type="string" required>
+Payment currency ID.
+</ParamField>
+
+<ParamField body="feePercentage" type="string">
+Optional fee percentage from `0` to `100`.
+</ParamField>
+
+<ParamField body="feeAddress" type="string">
+Optional fee recipient address.
+</ParamField>
+
+<RequestExample>
+```bash cURL
+curl -X POST "https://api.request.network/v2/secure-payments" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "requests": [
+      {
+        "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
+        "amount": "10",
+        "invoiceCurrency": "FAU-sepolia",
+        "paymentCurrency": "FAU-sepolia"
+      }
+    ],
+    "feePercentage": "2.5",
+    "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
+  }'
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201 Created
+{
+  "requestIds": [
+    "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"
+  ],
+  "securePaymentUrl": "https://secure.request.network/?token=01ABC123DEF456GHI789JKL",
+  "token": "01ABC123DEF456GHI789JKL"
+}
+```
+</ResponseExample>
+
+### Error responses
+
+- `400`: invalid body or unsupported secure payment configuration
+- `401`: unauthorized
+- `429`: rate limited
+
+## GET /v2/secure-payments/:token
+
+Retrieve secure payment status and prepared transactions.
+
+### Path parameters
+
+<ParamField path="token" type="string" required>
+Secure payment token returned from `POST /v2/secure-payments`.
+</ParamField>
+
+### Query parameters
+
+<ParamField query="wallet" type="string">
+Optional payer wallet address used to optimize approval checks.
+</ParamField>
+
+<RequestExample>
+```bash cURL
+curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL?wallet=0x1234567890123456789012345678901234567890" \
+  -H "x-api-key: YOUR_API_KEY"
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200 Single payment
+{
+  "paymentType": "single",
+  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
+  "network": "sepolia",
+  "amount": "10000000000000000000",
+  "paymentCurrency": "FAU-sepolia",
+  "isNativeCurrency": false,
+  "status": "pending",
+  "transactions": [
+    {
+      "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C",
+      "data": "0x...",
+      "value": 0
+    }
+  ],
+  "metadata": {
+    "stepsRequired": 1,
+    "needsApproval": false,
+    "paymentTransactionIndex": 0
+  }
+}
+```
+</ResponseExample>
+
+<ResponseExample>
+```json 200 Batch payment
+{
+  "paymentType": "batch",
+  "payees": [
+    "0xb07d2398d2004378cad234da0ef14f1c94a530e4",
+    "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
+  ],
+  "network": "sepolia",
+  "amounts": ["50", "10"],
+  "paymentCurrencies": ["FAU-sepolia", "FAU-sepolia"],
+  "isNativeCurrency": [false, false],
+  "status": "pending",
+  "ERC20ApprovalTransactions": [],
+  "batchPaymentTransaction": {
+    "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE",
+    "data": "0x...",
+    "value": 0
+  }
+}
+```
+</ResponseExample>
+
+### Error responses
+
+- `403`: token expired or not payable
+- `404`: token not found
+- `409`: secure payment already completed
+- `429`: rate limited

docs.json

@@ -101,6 +101,13 @@
                   "api-features/webhooks-events"
                 ]
               },
+              {
+                "group": "Secure Payment Pages",
+                "pages": [
+                  "api-features/secure-payment-pages",
+                  "api-features/secure-payment-supported-networks-and-currencies"
+                ]
+              },
               {
                 "group": "Fee Structure",
                 "pages": [
@@ -114,6 +121,7 @@
             "group": "📚 API Reference",
             "pages": [
               "api-reference/authentication",
+              "api-reference/secure-payments",
               "api-reference/webhooks",
               {
                 "group": "Endpoints",
@@ -198,8 +206,7 @@
         "href": "https://github.com/orgs/RequestNetwork/discussions"
       }
     ],
-    "primary": 
-    {
+    "primary": {
       "type": "button",
       "label": "Get your API Key",
       "href": "https://portal.request.network"
@@ -233,32 +240,31 @@
     "links": [
       {
         "items": [
-        {
-          "label": "Website",
-          "href": "https://request.network"
-        },
-        {
-          "label": "Community",
-          "href": "https://discord.com/invite/FsVAR3ny3f"
-        },
-        {
-          "label": "Portal",
-          "href": "https://portal.request.network"
-        },
-        {
-          "label": "Scan",
-          "href": "https://scan.request.network"
-        },
-        {
-          "label": "Status",
-          "href": "https://status.request.network"
-        },
-        {
-          "label": "Blog",
-          "href": "https://request.network/blog"
-        }
+          {
+            "label": "Website",
+            "href": "https://request.network"
+          },
+          {
+            "label": "Community",
+            "href": "https://discord.com/invite/FsVAR3ny3f"
+          },
+          {
+            "label": "Portal",
+            "href": "https://portal.request.network"
+          },
+          {
+            "label": "Scan",
+            "href": "https://scan.request.network"
+          },
+          {
+            "label": "Status",
+            "href": "https://status.request.network"
+          },
+          {
+            "label": "Blog",
+            "href": "https://request.network/blog"
+          }
         ]
-
       }
     ]
   }