Skip to main content

Pay REST API

Complete reference for all Pay wire REST endpoints.

Stripe​

POST /pay/stripe/checkout​

Create a Stripe Checkout session.

curl -X POST http://localhost:3000/pay/stripe/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "items": [
      { "name": "Pro Plan", "amount": 2999, "currency": "usd" }
    ],
    "successUrl": "https://myapp.com/success",
    "cancelUrl": "https://myapp.com/cancel"
  }'

Response (200):

{
  "sessionId": "cs_test_abc123",
  "url": "https://checkout.stripe.com/pay/cs_test_abc123"
}

POST /pay/stripe/refund​

Refund a Stripe payment.

curl -X POST http://localhost:3000/pay/stripe/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "transactionId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "amount": 1000
  }'

POST /pay/stripe/webhook​

Stripe webhook handler. Configure in Stripe Dashboard.

PayPal​

POST /pay/paypal/order​

Create a PayPal order.

curl -X POST http://localhost:3000/pay/paypal/order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "amount": 29.99,
    "currency": "USD",
    "description": "Pro Plan",
    "returnUrl": "https://myapp.com/paypal/success",
    "cancelUrl": "https://myapp.com/paypal/cancel"
  }'

Response (200):

{
  "orderId": "5O190127TN364715T",
  "approvalUrl": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
  "status": "CREATED"
}

POST /pay/paypal/capture/:orderId​

Capture an approved PayPal order.

curl -X POST http://localhost:3000/pay/paypal/capture/5O190127TN364715T \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "orderId": "5O190127TN364715T",
  "status": "COMPLETED",
  "transactionId": "65a1b2c3d4e5f6a7b8c9d0e1"
}

POST /pay/paypal/refund​

Refund a PayPal payment.

curl -X POST http://localhost:3000/pay/paypal/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "transactionId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "amount": 10.00
  }'

POST /pay/paypal/webhook​

PayPal webhook handler. Configure in PayPal Developer Dashboard.

On-Chain Payments​

POST /pay/onchain/payment​

Create an on-chain payment request.

curl -X POST http://localhost:3000/pay/onchain/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "amount": "29.99",
    "token": "USDC",
    "chain": "arbitrum"
  }'

Response (200):

{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "receiverAddress": "0x1234...5678",
  "amount": "29990000",
  "displayAmount": "29.99",
  "token": "USDC",
  "chain": "arbitrum",
  "status": "pending",
  "expiresAt": "2025-01-15T11:00:00.000Z"
}

GET /pay/onchain/payment/:id​

Check payment status.

curl http://localhost:3000/pay/onchain/payment/65a1b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer eyJhbGci..."

Transactions​

GET /pay/transactions​

List all transactions across all providers.

curl "http://localhost:3000/pay/transactions?provider=stripe&status=completed&limit=20" \
  -H "Authorization: Bearer eyJhbGci..."
ParamTypeDefaultDescription
providerstringallFilter by provider
statusstringallFilter by status
limitnumber20Results per page
offsetnumber0Pagination offset

Response (200):

{
  "transactions": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "provider": "stripe",
      "status": "completed",
      "amount": 2999,
      "currency": "usd",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

GET /pay/transactions/:id​

Get a single transaction.

curl http://localhost:3000/pay/transactions/65a1b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer eyJhbGci..."

Health​

GET /pay/health​

curl http://localhost:3000/pay/health

Response (200):

{
  "status": "healthy",
  "providers": {
    "stripe": "connected",
    "paypal": "connected",
    "onchain": "connected"
  }
}