API Reference

API Reference

All endpoints are served from https://api.pay.l2.ippan.com/v1. Authenticate every request with a Bearer token in the Authorization header. All request and response bodies use JSON.

POST/payments

Create Payment

Initiate a new payment. Returns a deterministic payment object with a pending status and a proof URI that becomes active upon settlement.

terminal
curl -X POST https://api.pay.l2.ippan.com/v1/payments \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_abc123" \
  -d '{
    "amount": 50000,
    "currency": "USDC",
    "merchant_id": "mer_9x8kLm2nQp",
    "description": "Invoice #1042",
    "metadata": {
      "order_id": "ord_abc123",
      "customer_email": "buyer@example.com"
    }
  }'

# Response 201 Created
{
  "id": "pay_7f3dKz1mNv",
  "object": "payment",
  "amount": 50000,
  "currency": "USDC",
  "status": "pending",
  "merchant_id": "mer_9x8kLm2nQp",
  "proof_url": "https://proofs.l2.ippan.com/pay_7f3dKz1mNv",
  "created_at": "2026-03-28T14:22:07Z"
}
POST/invoices

Create Invoice

Generate a hosted invoice with automatic payment tracking and settlement. Invoices support line items, tax calculations, and due-date enforcement.

terminal
curl -X POST https://api.pay.l2.ippan.com/v1/invoices \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "accounts@acme.co",
    "currency": "USDC",
    "due_date": "2026-04-15",
    "line_items": [
      { "description": "SaaS license - April 2026", "amount": 129900 },
      { "description": "Priority support add-on", "amount": 29900 }
    ]
  }'

# Response 201 Created
{
  "id": "inv_Qp3rTx8mNv",
  "object": "invoice",
  "status": "open",
  "total": 159800,
  "currency": "USDC",
  "hosted_url": "https://pay.l2.ippan.com/inv/inv_Qp3rTx8mNv",
  "due_date": "2026-04-15",
  "created_at": "2026-03-28T14:30:00Z"
}
POST/payment-links

Create Payment Link

Generate a reusable or single-use payment link. Ideal for no-code payment collection, social commerce, and email campaigns.

terminal
curl -X POST https://api.pay.l2.ippan.com/v1/payment-links \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "currency": "USDC",
    "description": "Early-bird conference ticket",
    "reusable": true,
    "expires_at": "2026-06-01T00:00:00Z"
  }'

# Response 201 Created
{
  "id": "plink_Nv3mTx8qRz",
  "object": "payment_link",
  "url": "https://pay.l2.ippan.com/l/plink_Nv3mTx8qRz",
  "amount": 9900,
  "currency": "USDC",
  "reusable": true,
  "expires_at": "2026-06-01T00:00:00Z",
  "created_at": "2026-03-28T15:00:00Z"
}
POST/payouts

Create Payout

Initiate a payout to a verified beneficiary. Payouts are routed through IPPAN L2 settlement and generate a verifiable proof once finalized.

terminal
curl -X POST https://api.pay.l2.ippan.com/v1/payouts \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "USDC",
    "beneficiary_id": "ben_Kx7mNv3pQr",
    "reference": "contractor-march-2026",
    "metadata": { "department": "engineering" }
  }'

# Response 201 Created
{
  "id": "po_Tx8mNv3qRz",
  "object": "payout",
  "amount": 250000,
  "currency": "USDC",
  "status": "processing",
  "beneficiary_id": "ben_Kx7mNv3pQr",
  "proof_url": "https://proofs.l2.ippan.com/po_Tx8mNv3qRz",
  "created_at": "2026-03-28T16:00:00Z"
}
GET/settlements/:id

Get Settlement

Retrieve the current state of a settlement batch. Includes finality status, constituent payment IDs, and the deterministic proof hash.

terminal
curl https://api.pay.l2.ippan.com/v1/settlements/stl_Nv3mTx8qRz \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..."

# Response 200 OK
{
  "id": "stl_Nv3mTx8qRz",
  "object": "settlement",
  "status": "finalized",
  "total": 459800,
  "currency": "USDC",
  "payment_ids": [
    "pay_7f3dKz1mNv",
    "pay_Qp3rTx8mNv"
  ],
  "proof_hash": "0x8a3f...c7d1",
  "finalized_at": "2026-03-28T18:00:00Z",
  "created_at": "2026-03-28T17:55:00Z"
}
GET/proofs/:id

Get Proof

Retrieve a deterministic settlement proof. Proofs are immutable records anchored to IPPAN L2 and can be independently verified by any third party.

terminal
curl https://api.pay.l2.ippan.com/v1/proofs/prf_Kx7mNv3pQr \
  -H "Authorization: Bearer sk_live_9x8kLm2nQp..."

# Response 200 OK
{
  "id": "prf_Kx7mNv3pQr",
  "object": "proof",
  "type": "settlement",
  "settlement_id": "stl_Nv3mTx8qRz",
  "hash": "0x8a3f...c7d1",
  "block_height": 1482937,
  "verified": true,
  "verification_url": "https://explorer.l2.ippan.com/proof/prf_Kx7mNv3pQr",
  "created_at": "2026-03-28T18:00:01Z"
}