diff --git a/api-features/secure-payment-pages.mdx b/api-features/secure-payment-pages.mdx new file mode 100644 index 0000000..2a35fa3 --- /dev/null +++ b/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 + + + + Call `POST /v2/secure-payments` with one or more requests. + + The API creates Request records and returns: + - `requestIds` + - `token` + - `securePaymentUrl` + + + + Send the payer to `securePaymentUrl`. + + + + The hosted page loads the payment details and prepares the required transaction flow. + + + + The payer signs the returned transaction set from their wallet. Depending on token approvals, this can be one or more transactions. + + + +## 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 + + + Create a secure payment entry and return a hosted secure payment URL. View the complete endpoint documentation with request/response schemas and examples. + + +## 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 + + + + Endpoint details, request and response schemas, and error codes. + + + + Check supported chain and currency coverage before creating links. + + diff --git a/api-features/secure-payment-supported-networks-and-currencies.mdx b/api-features/secure-payment-supported-networks-and-currencies.mdx new file mode 100644 index 0000000..f29bbbf --- /dev/null +++ b/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. + + +```bash cURL +curl -X GET "https://api.request.network/v2/currencies?network=sepolia" \ + -H "x-api-key: YOUR_API_KEY" +``` + + + +```json Example +[ + { + "id": "FAU-sepolia", + "name": "FAU", + "symbol": "FAU", + "decimals": 18, + "network": "sepolia", + "type": "ERC20", + "chainId": 11155111 + } +] +``` + + +## 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 + + +For an at-a-glance list of ecosystem support, see [Supported Chains and Currencies](/resources/supported-chains-and-currencies). + + +## 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 diff --git a/api-reference/secure-payments.mdx b/api-reference/secure-payments.mdx new file mode 100644 index 0000000..3b82143 --- /dev/null +++ b/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 + + +Array of payment requests. One item creates a single payment. Multiple items create a batch payment. + + + +Payee EVM address. + + + +Human-readable amount. + + + +Invoice currency ID. + + + +Payment currency ID. + + + +Optional fee percentage from `0` to `100`. + + + +Optional fee recipient address. + + + +```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" + }' +``` + + + +```json 201 Created +{ + "requestIds": [ + "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" + ], + "securePaymentUrl": "https://secure.request.network/?token=01ABC123DEF456GHI789JKL", + "token": "01ABC123DEF456GHI789JKL" +} +``` + + +### 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 + + +Secure payment token returned from `POST /v2/secure-payments`. + + +### Query parameters + + +Optional payer wallet address used to optimize approval checks. + + + +```bash cURL +curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789JKL?wallet=0x1234567890123456789012345678901234567890" \ + -H "x-api-key: YOUR_API_KEY" +``` + + + +```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 + } +} +``` + + + +```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 + } +} +``` + + +### Error responses + +- `403`: token expired or not payable +- `404`: token not found +- `409`: secure payment already completed +- `429`: rate limited diff --git a/docs.json b/docs.json index b138a6e..50b8030 100644 --- a/docs.json +++ b/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" + } ] - } ] }