Revolutionary payment processing through Motr Vaults that implement W3C Payment Handler API and DWN protocols for seamless, programmable transactions

Universal Payments System

Scope

This document covers Sonr's payment system architecture using W3C Payment Handler API and DWN protocols. It includes Vault payment processing, cross-chain abstraction, programmable logic, and integration patterns. This document does not cover low-level blockchain transaction details—see the Bank module reference for protocol specifications.

Audience

Developers integrating payment features. Merchants accepting crypto payments. System architects designing payment flows. Prerequisites: Understanding of web payments, basic blockchain concepts, and familiarity with JavaScript/HTML.

Summary

Sonr combines the W3C Payment Handler API with DWN protocols through Motr Vaults. This creates programmable, user-controlled payment infrastructure. Vaults process payments across multiple blockchains using standard web APIs. Users maintain sovereignty over payment data and authorization through UCAN capabilities.

Universal Payments System

W3C Payment Handler: Standard browser API for payment processing
DWN Protocol: Decentralized storage for payment records
UCAN Authorization: Capability-based payment permissions
Cross-Chain Engine: Unified interface for multiple blockchains

W3C Payment Handler

Implementation

Vaults register as payment handlers:

// Register vault as payment handler
await registration.paymentManager.userHint = 'Sonr Vault Payment Handler';

// Handle payment requests
self.addEventListener('paymentrequest', event => {
  event.respondWith(handlePayment(event.data));
});

async function handlePayment(paymentRequest) {
  const { methodData, total, displayItems } = paymentRequest;

  // Request user authorization
  const authorization = await vault.requestCapability({
    action: 'bank/send',
    amount: total.amount,
    recipient: methodData.data.merchantId
  });

  // Execute if approved
  if (authorization.approved) {
    return await vault.executePayment(paymentRequest);
  }
}

Merchant Integration

Standard Payment Request API usage:

<button onclick="requestPayment()">Pay with Sonr</button>

<script>
  async function requestPayment() {
    const request = new PaymentRequest(
      [
        {
          supportedMethods: "https://sonr.io/pay",
          data: {
            merchantId: "shop.sonr",
            acceptedCurrencies: ["USDC", "SNR", "ETH"],
          },
        },
      ],
      {
        total: {
          label: "Total",
          amount: { currency: "USD", value: "29.99" },
        },
      },
    );

    const response = await request.show();
    console.log("Payment complete:", response.details);
  }
</script>

DWN Payment Records

Protocol Schema

Payments follow DWN protocol structure:

{
  "protocol": "https://sonr.io/protocols/payments/v1",
  "types": {
    "paymentRecord": {
      "schema": "https://sonr.io/schemas/payment",
      "dataFormats": ["application/json"]
    },
    "subscription": {
      "schema": "https://sonr.io/schemas/recurring-payment",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "paymentRecord": {
      "actions": [
        {
          "who": "author",
          "can": ["create", "read"]
        },
        {
          "who": "recipient",
          "can": ["read"]
        }
      ]
    }
  }
}

Payment Record Storage

Records store in user's DWN:

{
  "recordId": "bafyreig...",
  "schema": "https://sonr.io/schemas/payment",
  "data": {
    "amount": "29.99",
    "currency": "USDC",
    "merchant": "netflix.sonr",
    "timestamp": "2024-12-25T10:00:00Z",
    "txHash": "0xabc123...",
    "chain": "polygon"
  },
  "encryption": "jwe",
  "published": false
}

Programmable Payments

Recurring Subscriptions

Automated recurring payment capabilities:

// Request subscription authorization
const subscription = {
  action: "bank/send",
  constraints: {
    amount: { max: "9.99", currency: "USDC" },
    frequency: "monthly",
    recipient: "spotify.sonr",
    expiresAt: Date.now() + 365 * 24 * 60 * 60 * 1000,
    totalLimit: "119.88",
  },
};

// Vault executes automatically each month
// User maintains full control and visibility

Conditional Payments

Execute payments based on conditions:

// Weather-triggered payment
const conditionalPayment = {
  action: "bank/send",
  conditions: [
    {
      type: "oracle",
      source: "weather.sonr",
      condition: "temperature > 80°F",
    },
  ],
  amount: "5.00",
  recipient: "ice-cream-vendor.sonr",
};

Cross-Chain Abstraction

Unified Interface

Single API for multi-chain payments:

const payment = await vault.pay({
  amount: "100",
  currency: "USDC",
  recipient: "merchant.sonr",
  preferences: {
    speed: "fast",
    cost: "medium",
    privacy: "high",
  },
});

// Vault automatically:
// - Selects optimal chain
// - Handles bridging if needed
// - Optimizes gas costs
// - Protects against MEV

Chain Selection Logic

Vault optimizes based on:

Transaction fees
Confirmation times
Liquidity availability
User preferences
Merchant requirements

Security Features

Zero-Knowledge Proofs

Prove payment ability without revealing balance:

// Generate proof of funds
const proof = await vault.generateProof({
  type: "sufficient_funds",
  amount: "1000",
  currency: "USDC",
  merchant: "luxury-store.sonr",
});

// Merchant verifies without seeing balance
const verified = await verifyProof(proof);

MPC Key Security

Vault keys use threshold cryptography:

Keys split across multiple nodes
No single point of failure
Disaster recovery built-in
Hardware security module support

Integration Patterns

E-commerce

Simple checkout integration:

// Check Sonr availability
const canMakePayment = await new PaymentRequest(
  [
    {
      supportedMethods: "https://sonr.io/pay",
    },
  ],
  {
    total: { label: "test", amount: { value: "0", currency: "USD" } },
  },
).canMakePayment();

if (canMakePayment) {
  showSonrPaymentOption();
}

Mobile SDK

Native mobile support:

// iOS Swift
import SonrPayments

let payment = SonrPayment(
  amount: 29.99,
  currency: "USDC",
  merchant: "app.sonr"
)

try await SonrVault.shared.requestPayment(payment) { result in
  switch result {
  case .success(let receipt):
    processReceipt(receipt)
  case .failure(let error):
    handleError(error)
  }
}

Backend Verification

Server-side payment validation:

app.post("/verify-payment", async (req, res) => {
  const { paymentId, signature } = req.body;

  const payment = await SonrPayments.verify({
    paymentId,
    signature,
    merchantId: "my-store.sonr",
  });

  if (payment.status === "confirmed") {
    await fulfillOrder(payment.orderId);
    res.json({ success: true });
  }
});