Merge pull request 0xPolygon#2696 from 0xPolygon/payments-addition

Payments addition

Author: arnavshah01

docs/pos/payments/onramps/onramps-stripe.md

@@ -0,0 +1,84 @@
+# Stripe
+!!! info 
+    NOTE: Like all of crypto, payments require handling sensitive data. The following examples are demonstrations of integrations but should not be used in production. In production, sensitive information such as API keys, private-key wallets, etc., should be put in a secrets manager or vault.
+    
+!!! info Stripe Documentation
+
+    [Full documentation available on Stripe.](https://docs.stripe.com/)
+
+Stripe integration requires a US domicile (excluding Hawaii) and a registration for your business. Once that registration has cleared, the API `Crypto/Onramps_sessions` will be enabled. Below is an example using Stripe's Sandbox environment:
+
+### Prerequisites
+
+* [Stripe API access](https://docs.stripe.com/api)
+* [Stripe SDK](https://github.com/stripe/stripe-node)  
+
+### Server
+
+```curl
+# SERVER-SIDE ONLY
+curl https://api.stripe.com/v1/crypto/onramp_sessions \
+  -u sk_test_your_secret_key: \
+  -d "destination_currency"="usdc" \
+  -d "destination_network"="polygon" \
+  -d "wallet_addresses[0][type]"="self_custody" \
+  -d "wallet_addresses[0][address]"="0xYOUR_POLYGON_ADDRESS"
+```
+
+If successful, the server will return `client_secret` in a format similar to this:
+
+```json
+{
+  "id": "cos_0MYvmj589O8KAxCGp14dTjiw",
+  "object": "crypto.onramp_session",
+  "client_secret": "cos_0MYvmj589O8KAxCGp14dTjiw_secret_BsxEqQLiYKANcTAoVnJ2ikH5q002b9xzouk",
+  "created": 1675794053,
+  "livemode": false,
+  [...]
+  }
+}
+```
+
+Once you have the `client_secret`, you can pass that to the frontend. (Note: Only pass the `client_secret`, not the `STRIPE_SECRET_KEY`)
+
+### Node server
+
+```js
+import Stripe from "stripe";
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+
+export async function createOnrampSession(req, res) {
+  const session = await stripe.crypto.onramps.sessions.create({
+    destination_currency: "usdc",
+    destination_network: "polygon",
+    wallet_addresses: [{
+      type: "self_custody",
+      address: "0xYOUR_POLYGON_ADDRESS"
+    }],
+    // optional: customer, email, reference, etc.
+  });
+  res.json({ client_secret: session.client_secret });
+}
+```
+
+## Serving to Frontend
+
+`client_secret` can now be served to the frontend:
+
+```html
+<script src="https://js.stripe.com/v3/crypto/onramp.js"></script>
+<div id="onramp"></div>
+<script>
+(async () => {
+  // Fetch client_secret from your server
+  const { client_secret } = await fetch("/api/create-onramp-session").then(r => r.json());
+
+  const onramp = await window.StripeOnramp.init({
+    clientSecret: client_secret,
+    appearance: { /* optional branding overrides */ },
+  });
+
+  onramp.mount("#onramp");
+})();
+</script>
+```

docs/pos/payments/overview.md

@@ -0,0 +1,34 @@
+Launch payments on Polygon to benefit from ultra low cost transactions, a compliant and reliable network, and worldwide distribution.
+
+## Exchanges, On- and Offramps
+Polygon is the choice for major payment projects due to the hundreds of third-party options available on the network. Integrate with exchanges and on- and offramps to get crypto-to-fiat exposure in 150+ countries.
+
+Some of the major payment infrastructure projects Polygon supports:
+
+* **Payments and Ramps:** [Stripe](https://docs.stripe.com/crypto/stablecoin-payments), 
+[Shopify](https://depay.com/plugins/shopify), [MoonPay](https://dev.moonpay.com/docs/on-ramp-overview), [Bridge](https://apidocs.bridge.xyz/), [Revolut](https://www.revolut.com/en-US/), [BlindPay](https://blindpay.com/docs/getting-started/quick-start-payin), [Payy](https://payy.link/), [Avenia](https://avenia.io/), [Crossmint](https://crossmint.io), [MoonPay](https://dev.moonpay.com/docs/on-ramp-overview), [Transak](https://docs.transak.com/), [Ramp](https://docs.rampnetwork.com/)
+
+[Learn how to integrate Stripe on Polygon here.](./onramps/onramps-stripe.md)
+
+* **Stablecoins:** [USDC](https://developers.circle.com/), [USDT](https://tether.to/en/why-tether), Agora, Axelar, [DAI](https://docs.makerdao.com/smart-contract-modules/dai-module/dai-detailed-documentation), [FRAX](https://docs.frax.finance/fraxlend/abi-and-code)
+
+
+## Fastest, Ultra-Low Cost Transactions
+
+With the upgrade to Heimdall v2, deterministic finality on Polygon chain is now achieved between 2-5 seconds thanks to the 1-2 seconds block time in Heimdall, meaning miletones are voted on and finalized much faster.
+
+Fast finality means payments will be immediately available for your users.
+
+[Read more about finality here.](../concepts/finality/finality.md)
+
+Polygon transaction are also incredibly low-cost, around 0.0001 in cost. [You can track the average price of Polygon transactions here.](https://polygonscan.com/chart/avg-txfee-usd)
+
+## 99.999% Uptime
+
+Polygon is a rock of stability that provides 99.999% network uptime. [You can always check the status of Polygon's mainnet and testnet network here.](https://status.polygon.technology/)
+
+## Compliance
+
+Business payments require serious compliance. Polygon has the major providers on its platform, including: 
+
+[Sumsub](https://docs.sumsub.com/docs/overview), [Onfido](https://documentation.onfido.com/), [Persona](https://docs.withpersona.com/getting-started), [Chainanalysis](https://www.chainalysis.com/), [TRM](https://www.trmlabs.com/), [Forta](https://docs.forta.network/en/latest/), [Elliptic](https://developers.elliptic.co/docs/getting-started)

docs/pos/payments/transfers/transfer-usdc.md

@@ -0,0 +1,144 @@
+!!! info 
+    NOTE: Like all of crypto, payments require handling sensitive data. The following examples are demonstrations of integrations but should not be used in production. In production, sensitive information such as API keys, private-key wallets, etc., should be put in a secrets manager or vault.
+
+## USDC 
+USDC is a [top stablecoin used for payments on Polygon.](https://defillama.com/stablecoins/Polygon) Cost-efficient transactions on Polygon makes it the default chain for USDC payments, especially micro or high-volume payments.    
+
+### Integrating USDC
+Circle has [excellent documentation,](https://developers.circle.com/) including ready-to-use SDKs and sample applications
+
+For those looking to easily integrate USDC to Polygon, we have two options below: **Native USDC integration** or crosschain USDC using Circle’s **Gateway integration**
+
+### Native USDC integration:
+
+USDC is an ERC-20 contract with the standard `approve`/`transfer` process
+
+```ts
+// pnpm add viem
+import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
+import { polygon } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Native USDC on Polygon PoS (NOT the old bridged USDC.e)
+// Source: Circle "USDC Contract Addresses"
+const USDC = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
+
+// Testnet USDC on Amoy
+// const USDC = "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582";
+
+const erc20 = [
+  { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+  { type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ type: "address" }], outputs: [{ type: "uint256" }] },
+  { type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ type: "address" }, { type: "uint256" }], outputs: [{ type: "bool" }] },
+  { type: "function", name: "transfer", stateMutability: "nonpayable", inputs: [{ type: "address" }, { type: "uint256" }], outputs: [{ type: "bool" }] },
+];
+
+const account = privateKeyToAccount(process.env.PRIV_KEY as `0x${string}`);
+
+const rpc = http(process.env.POLYGON_RPC_URL); // e.g. https://polygon-rpc.com
+const pub = createPublicClient({ chain: polygon, transport: rpc });
+const wallet = createWalletClient({ chain: polygon, transport: rpc, account });
+
+async function main() {
+  const me = account.address as `0x${string}`;
+  const decimals = await pub.readContract({ address: USDC, abi: erc20, functionName: "decimals" });
+  const bal = await pub.readContract({ address: USDC, abi: erc20, functionName: "balanceOf", args: [me] });
+  console.log("USDC balance:", Number(bal) / 10 ** Number(decimals));
+
+  // Transfer 1 USDC
+  const amount = parseUnits("1", Number(decimals));
+  const hash = await wallet.writeContract({ address: USDC, abi: erc20, functionName: "transfer", args: ["0xRecipient...", amount] });
+  console.log("tx:", hash);
+}
+main();
+```
+
+### Gateway integration:
+
+Gateway collects USDC balances across any chain with USDC. Users need to send USDC to the Gateway Wallet (not an ERC-20), [more details here.](https://developers.circle.com/gateway#setting-up-a-balance)     
+
+Once the users have a balance, they can send USDC to any chain using the Gateway implementation.
+
+## Prerequisites
+
+The follow example requires a Circle API key, which you can create through [the Circle Developer dashboard.](https://console.circle.com/) (You do not need a Cirlce  license to get a sandbox API key).
+
+```ts
+
+import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
+import { polygon } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { fetch } from "undici";
+
+const USDC = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
+const GATEWAY_WALLET = "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE";
+const GATEWAY_MINTER = "0x2222222d7164433c4C09B0b0D809a9b52C04C205";
+
+const erc20 = [
+  { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+  { type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ type: "address" }, { type: "uint256" }], outputs: [{ type: "bool" }] },
+];
+
+const gatewayWalletAbi = [
+  { type: "function", name: "deposit", stateMutability: "nonpayable", inputs: [{ type: "address" }, { type: "uint256" }], outputs: [] },
+];
+
+const gatewayMinterAbi = [
+  { type: "function", name: "gatewayMint", stateMutability: "nonpayable", inputs: [{ type: "bytes" }, { type: "bytes" }], outputs: [] },
+];
+
+const account = privateKeyToAccount(process.env.PRIV_KEY as `0x${string}`);
+const rpc = http(process.env.POLYGON_RPC_URL);
+const pub = createPublicClient({ chain: polygon, transport: rpc });
+const wallet = createWalletClient({ chain: polygon, transport: rpc, account });
+
+async function gatewayTransfer() {
+  // 1) Approve + deposit into GatewayWallet on Polygon
+  const decimals = await pub.readContract({ address: USDC, abi: erc20, functionName: "decimals" });
+  const amount = parseUnits("25", Number(decimals)); // example
+
+  await wallet.writeContract({ address: USDC, abi: erc20, functionName: "approve", args: [GATEWAY_WALLET, amount] });
+  await wallet.writeContract({ address: GATEWAY_WALLET, abi: gatewayWalletAbi, functionName: "deposit", args: [USDC, amount] });
+
+  // 2) Request attestation from Circle Gateway API
+  // Build and sign a BurnIntent (EIP-712 typed data) for source=Polygon, destination=Polygon (same-chain "withdraw") or another chain.
+  // For brevity, assume you already produced `burnIntent` and EIP-712 signature with your EOA.
+  const res = await fetch("https://gateway-api.circle.com/v1/transfer", {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${process.env.CIRCLE_API_KEY}` },
+    body: JSON.stringify({
+      burnIntent: {
+        maxBlockHeight: "999999999999",
+        maxFee: "0",
+        spec: {
+          version: 1,
+          sourceDomain: 7,          // Polygon PoS domain id (per Circle docs)
+          destinationDomain: 7,     // or another supported domain id
+          sourceContract: GATEWAY_WALLET,
+          destinationContract: GATEWAY_MINTER,
+          sourceToken: USDC,
+          destinationToken: USDC,
+          sourceDepositor: account.address,
+          destinationRecipient: "0xRecipient...", // who receives on destination
+          sourceSigner: account.address,
+          destinationCaller: "0x0000000000000000000000000000000000000000",
+          value: amount.toString(),
+        },
+      },
+      // include your EIP-712 signature of BurnIntent here if required by your flow
+    }),
+  });
+  const { attestationPayload, signature } = await res.json();
+
+  // 3) Submit attestation to GatewayMinter on destination chain
+  const tx = await wallet.writeContract({
+    address: GATEWAY_MINTER,
+    abi: gatewayMinterAbi,
+    functionName: "gatewayMint",
+    args: [attestationPayload as `0x${string}`, signature as `0x${string}`],
+  });
+  console.log("gatewayMint tx:", tx);
+}
+
+gatewayTransfer();
+```

mkdocs.yml

@@ -61,6 +61,12 @@ nav:
           - PoS to Ethereum: pos/how-to/bridging/ethereum-polygon/matic-to-ethereum.md
           - Submit mapping request: pos/how-to/bridging/ethereum-polygon/submit-mapping-request.md
         - Becoming a validator: pos/get-started/becoming-a-validator.md
+      - Payments:
+        - Overview: pos/payments/overview.md
+        - Onramps:
+          - Stripe: pos/payments/onramps/onramps-stripe.md
+        - Transfers: 
+          - USDC: pos/transfers/transfers-usdc.md
       - Node how-tos:
         - Prerequisites: pos/how-to/prerequisites.md
         - Sync node using snapshots: pos/how-to/snapshots.md