Sessions API

Manage checkout sessions for payments.

Create Session

Create a new checkout session.

POST /api/checkout/sessions

Request

{
  "merchantId": "merch_abc123",
  "amountUsdc": "50.00",
  "destinationChainId": 8453,
  "destinationToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE71",
  "successUrl": "https://mystore.com/success",
  "cancelUrl": "https://mystore.com/cancel",
  "metadata": {
    "orderId": "order_123"
  }
}

Field	Type	Required	Description
merchantId	string	Yes	Your merchant ID
amountUsdc	string	Yes	Amount in USDC (e.g., "50.00")
destinationChainId	number	Yes	Target chain (8453 for Base)
destinationToken	string	Yes	Token address
recipientAddress	string	Yes	Wallet to receive funds
successUrl	string	No	Redirect after success
cancelUrl	string	No	Redirect on cancel
metadata	object	No	Custom key-value pairs

Response

{
  "success": true,
  "message": "Session created successfully",
  "responseObject": {
    "session": {
      "id": "sess_xyz789",
      "merchantId": "merch_abc123",
      "amountUsdc": "50.00",
      "destinationChainId": 8453,
      "destinationToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE71",
      "status": "CREATED",
      "successUrl": "https://mystore.com/success",
      "cancelUrl": "https://mystore.com/cancel",
      "metadata": { "orderId": "order_123" },
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    "checkoutUrl": "https://checkout.zkp2p-pay.xyz/checkout?session=sess_xyz789"
  }
}

---

Get Session

Retrieve a session by ID.

GET /api/checkout/sessions/:id

Response

{
  "success": true,
  "responseObject": {
    "id": "sess_xyz789",
    "merchantId": "merch_abc123",
    "amountUsdc": "50.00",
    "status": "ACTIVE",
    "selectedPaymentPlatform": "venmo",
    "selectedFiatCurrency": "USD",
    "activeOrderId": "ord_abc123",
    "merchant": {
      "id": "merch_abc123",
      "name": "my-store",
      "displayName": "My Store"
    },
    "activeOrder": {
      "id": "ord_abc123",
      "status": "SIGNAL_MINED",
      ...
    },
    ...
  }
}

---

Select Platform

Save the user's payment platform selection.

POST /api/checkout/sessions/:id/select-platform

Request

{
  "paymentPlatform": "venmo",
  "fiatCurrency": "USD"
}

Response

{
  "success": true,
  "responseObject": {
    "session": {
      "id": "sess_xyz789",
      "selectedPaymentPlatform": "venmo",
      "selectedFiatCurrency": "USD",
      ...
    }
  }
}

---

Start Session

Get a quote and create an order for the session.

POST /api/checkout/sessions/:id/start

Request

{
  "paymentPlatform": "venmo",
  "fiatCurrency": "USD"
}

Response

{
  "success": true,
  "responseObject": {
    "session": {
      "id": "sess_xyz789",
      "status": "ACTIVE",
      ...
    },
    "order": {
      "id": "ord_abc123",
      "status": "SIGNAL_MINED",
      "intentHash": "0x1234...",
      "signalTx": "0xabcd...",
      "paymentPlatform": "venmo",
      "recipient": "@merchant-venmo",
      ...
    },
    "quote": {
      "fiatAmount": "50.00",
      "fiatAmountFormatted": "$50.00",
      "tokenAmount": "50000000",
      "tokenAmountFormatted": "50.00 USDC",
      "paymentMethod": "venmo",
      "payeeAddress": "@merchant-venmo",
      "conversionRate": "1.00"
    },
    "intentHash": "0x1234...",
    "expiresAt": "2024-01-15T11:00:00.000Z"
  }
}

---

Get Active Order

Get the active order for a session.

GET /api/checkout/sessions/:id/order

Response

{
  "success": true,
  "responseObject": {
    "order": {
      "id": "ord_abc123",
      "sessionId": "sess_xyz789",
      "status": "SIGNAL_MINED",
      "intentHash": "0x1234...",
      ...
    }
  }
}

---

Mark Payment Sent

Indicate that the user has sent the fiat payment.

POST /api/checkout/sessions/:id/payment-sent

Response

{
  "success": true,
  "responseObject": {
    "order": {
      "id": "ord_abc123",
      "status": "PAYMENT_SENT",
      ...
    }
  }
}

---

Session Status Values

Status	Description
CREATED	Session created, awaiting user
ACTIVE	User started checkout, order created
COMPLETED	Payment successful
EXPIRED	Session expired (24 hours)
CANCELLED	User cancelled checkout