PortalPay Developer Documentation#

Build payments that move at the speed of your ideas.

You’re not just integrating a gateway — you’re composing a business. With PortalPay, you can accept crypto anywhere, split revenue automatically, generate itemized receipts instantly, and see live analytics the moment value moves. Secure by design. Simple to launch. Made to scale.

Why PortalPay#

Ship fast: APIs and UI built to get you live in minutes, not months
Secure by default: APIM-first gateway with optional AFD fallback
Automatic revenue sharing: split payouts to recipients the moment funds settle
Real-time clarity: live receipts, inventory, tax, and analytics in one place
Built for teams: developer keys for builds, JWT + CSRF for admin operations

What you’ll accomplish in the next 10 minutes#

Get your developer keys (APIM subscription)
Configure payout splits in the Admin UI
Create your first product via API
Generate an order and open its payment page
Watch receipts and analytics update live

Start here: Quick Start Guide

Who this is for#

Builders who ship value quickly
Teams that need secure crypto payments with clear receipts
Platforms that split revenue across merchants, partners, and the network

Prerequisites#

APIM subscription key for developer APIs
Base API URL:
markup
```
https://api.pay.ledger1.ai/portalpay
```
Optional: a merchant wallet address for certain public GET reads (see endpoint docs)
Tools: curl or Postman, and a modern browser

How this documentation is organized#

Getting Started: Introduction · Quick Start · Core Concepts · Authentication
API Reference: Endpoints for split, inventory, orders, receipts, billing, tax, users, health
Integration Guides: E‑commerce, payment gateway, POS, Shopify
Developer Resources: Examples, error handling, rate limits, pricing, changelog

Tip: Many API pages include interactive “Try It” blocks that proxy requests through the server when CORS is restricted. Use the checkbox in the block to toggle server-side proxy if your local environment is blocking direct calls.

Technical Overview#

PortalPay enables crypto payments with automatic payment splitting, protected by Azure API Management (APIM). Azure Front Door (AFD) is optional and documented as a fallback.

Developer-facing APIs require an APIM subscription key (
markup
```
Ocp-Apim-Subscription-Key
```
)
Wallet identity is resolved at the gateway based on your subscription; clients do not manage wallet identity for writes
Client-supplied wallet headers are stripped by APIM policy; the backend resolves wallet using the stamped subscription identity
Admin-only operations in the PortalPay web app use JWT cookies (
markup
```
cb_auth_token
```
) with CSRF protections and role checks

Base URL and Paths#

Base API:
markup
```
https://api.pay.ledger1.ai/portalpay
```
Health:
markup
```
GET /portalpay/healthz
```
(no subscription required)
API routes:
markup
```
/portalpay/api/*
```
(APIM rewrites to backend
markup
```
/api/*
```
)

AFD Fallback (Optional)#

If AFD is used, it injects an internal header

markup

x-edge-secret

which APIM validates. Clients should not send this header themselves. See AFD Fallback Plan.

Rate Limiting#

Gateway/backend quotas and rate limits apply per subscription. Responses may include:

markup
```
X-RateLimit-Limit
```
markup
```
X-RateLimit-Remaining
```
markup
```
X-RateLimit-Reset
```

markup

429 Too Many Requests

, implement exponential backoff. See Rate Limits.

Security Model (Summary)#

Defense-in-depth:

Azure API Management (APIM)
- Products, subscriptions, scopes, quotas, rate limits
- Diagnostics to Log Analytics/Sentinel
- Managed identity for secure certificate/secret access
Optional Azure Front Door + WAF
- OWASP rules, TLS, header normalization
- Injects
  markup
```
x-edge-secret
```
  for APIM validation when enabled
Backend
- Private endpoints/VNet isolation depending on environment
- Trust anchored on APIM-stamped subscription identity

See the full Authentication & Security Guide.

Ocp-Apim-Subscription-Key: {your-subscription-key}

on all developer API requests

Gateway resolves your merchant wallet from the subscription and propagates identity to the backend; clients do not manage wallet identity

Admin Authentication (PortalPay UI)#

Sensitive operations (e.g., shop config updates, subscription lifecycle, certain receipts actions) use JWT cookies (
markup
```
cb_auth_token
```
)
CSRF protections and role checks apply
Perform these operations inside the PortalPay admin UI

Split Contracts#

Before accepting payments, configure the split recipients for your merchant wallet:

Merchant receives 99.5% (baseline)
Platform receives 0.5% (baseline)
Configure via PortalPay Admin UI (Settings → Payments → Split)
Orders cannot be created until split is configured (returns
markup
```
split_required
```
)

Required Setup Flow#

Configure split (Admin UI)
Set up inventory (Developer API)
Configure shop settings (Admin UI)
Generate orders (Developer API)
Accept payments via QR or payment link

Quick Example (Developer APIs)#

bash# Create a product
curl -X POST "https://api.pay.ledger1.ai/portalpay/api/inventory" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $APIM_SUBSCRIPTION_KEY" \
  -d '{
    "sku": "ITEM-001",
    "name": "Sample Product",
    "priceUsd": 25.00,
    "stockQty": 100,
    "taxable": true
  }'

# Generate an order
curl -X POST "https://api.pay.ledger1.ai/portalpay/api/orders" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $APIM_SUBSCRIPTION_KEY" \
  -d '{
    "items": [{ "sku": "ITEM-001", "qty": 1 }],
    "jurisdictionCode": "US-CA"
  }'

# List receipts
curl -X GET "https://api.pay.ledger1.ai/portalpay/api/receipts?limit=10" \
  -H "Ocp-Apim-Subscription-Key: $APIM_SUBSCRIPTION_KEY"

Payment page:

markuphttps://pay.ledger1.ai/pay/{receiptId}

Support#

Issues: Report bugs via GitHub Issues
Questions: Use /reportbug or contact support
Enterprise: Contact enterprise@portalpay.com

License#

This documentation is licensed under MIT License.

Next: Start with the Quick Start Guide to make your first API call.

Introduction