Integration Guide

Integrate Paratro Checkout using Hosted Page, Embed Widget, or API Direct

Integration Guide

Paratro Checkout offers three integration methods, ranging from zero frontend code to full custom UI control.

Method	Effort	Best For
Hosted Payment Page	Minimal — redirect only	Quick launch, no frontend changes
Embed Widget	Low — add a script tag	Inline payment experience on your site
API Direct	Moderate — full API calls	Custom UIs, mobile apps, advanced flows

Authentication

All API calls require a JWT token. Obtain one by exchanging your API Key and API Secret:

cURL

curl -X POST https://api.paratro.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

---

Hosted Payment Page

The simplest integration. Create a payment order via API, then redirect the customer to the returned URL. Paratro handles the entire payment UI.

1. Create a payment order

   Call the API from your server to create a payment order.

   cURL

   curl -X POST https://api.paratro.com/api/v1/checkout/orders \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": "50.00",
       "currency": "USDC",
       "merchant_reference": "INV-2026-0412",
       "description": "Pro Plan — Monthly",
       "success_url": "https://yoursite.com/payment/success",
       "cancel_url": "https://yoursite.com/payment/cancel",
       "metadata": {
         "customer_id": "cust_123",
         "plan": "pro_monthly"
       }
     }'
   

   Response:

   {
     "order_id": "ord_01HXZ...",
     "status": "created",
     "payment_url": "https://pay.paratro.com/ord_01HXZ...",
     "expires_at": "2026-04-12T11:00:00Z"
   }
   
2. Redirect the customer

   Redirect the customer to payment_url. They will see the payment page with amount, supported chains, and wallet address.

   // Server-side redirect
   res.redirect(order.payment_url);
   
3. Handle the result

   After payment, the customer is redirected to your success_url or cancel_url. Use webhooks to confirm the payment status server-side — do not rely on the redirect alone.

---

Embed Widget

Drop a JavaScript widget into your page for an inline payment experience. The widget renders a payment form inside an iframe on your site.

1. Create a payment order

   Create a payment order via API (same as Hosted Page above). Use the returned order_id.

2. Add the widget script

   Include the Paratro widget script and mount it to a container element.

   <div id="paratro-checkout"></div>
   
   <script src="https://js.paratro.com/checkout.js"></script>
   <script>
     ParatroCheckout.mount({
       container: "#paratro-checkout",
       orderId: "ord_01HXZ...",
       theme: "light", // "light" or "dark"
       onSuccess: function (result) {
         console.log("Payment successful:", result.order_id);
         // Update your UI or redirect
       },
       onCancel: function () {
         console.log("Payment cancelled");
       },
       onError: function (error) {
         console.error("Payment error:", error.message);
       },
     });
   </script>
   
3. Handle callbacks

   The onSuccess callback fires when the payment reaches confirmed status. Always verify the final status via webhook on your server.

The Embed Widget is served from js.paratro.com and renders inside an iframe, so it does not access your page’s DOM or cookies.

---

API Direct

For full control over the payment UI, use the API directly. Your frontend collects the customer’s chain preference and displays the payment address.

1. Create a payment order

   Same API call as above.

2. Retrieve payment details

   Fetch the payment address for the customer’s selected chain.

   cURL

   curl https://api.paratro.com/api/v1/checkout/orders/ord_01HXZ.../address?chain=base \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"
   

   Response:

   {
     "chain": "base",
     "address": "0x1234...abcd",
     "token": "USDC",
     "amount": "50.00",
     "expires_at": "2026-04-12T11:00:00Z"
   }
   
3. Display payment instructions

   Show the address and amount in your custom UI. Optionally render a QR code for mobile wallet scanning.

4. Poll for status or use webhooks

   Poll the order status endpoint or rely on webhooks to detect when the payment is confirmed.

   cURL

   curl https://api.paratro.com/api/v1/checkout/orders/ord_01HXZ... \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"
   

   Response:

   {
     "order_id": "ord_01HXZ...",
     "status": "settled",
     "amount": "50.00",
     "currency": "USDC",
     "chain": "base",
     "tx_hash": "0xabc123...",
     "settled_at": "2026-04-12T10:35:00Z"
   }
   

---

Sandbox Testing

Use the sandbox environment to test your integration with testnet tokens.

	Production	Sandbox
API base URL	https://api.paratro.com/api/v1	https://api-sandbox.paratro.com/api/v1
Payment page	https://pay.paratro.com	https://pay-sandbox.paratro.com
Dashboard	https://app.paratro.com	https://app-sandbox.paratro.com
Tokens	Real USDC / USDT	Testnet USDC / USDT

1. Get sandbox credentials

   Log in to the Sandbox Dashboard and generate API credentials.

2. Use sandbox base URL

   Point all API calls to https://api-sandbox.paratro.com/api/v1.

3. Get testnet tokens

   Use the chain’s testnet faucet to obtain testnet USDC for payment testing.

4. Test the full flow

   Create an order, send a testnet payment, and verify webhook delivery.

Never use production API credentials in your sandbox or development environment. Always use separate credentials per environment.