Skip to main content
Record payments and link them to visitors for revenue attribution.

​
Endpoint

POST /api/v1/payment

​
Authentication

Requires API key authentication.

​
Request body

FieldTypeRequiredDescription
providerstringYesPayment provider (e.g., “stripe”, “lemonsqueezy”, “custom”)
providerPaymentIdstringYesPayment ID from the provider
amountnumberYesPayment amount (in dollars, e.g., 99.99)
currencystringNoCurrency code (defaults to “USD”)
customerEmailstringNoCustomer email address
customerIdstringNoCustomer ID from provider
visitorIdstringNoVisitor ID (for linking)
sessionIdstringNoSession ID (for linking)
metadataobjectNoAdditional metadata

​
Request example

curl -X POST "https://your-domain.com/api/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "stripe",
    "providerPaymentId": "pi_1234567890",
    "amount": 99.99,
    "currency": "USD",
    "customerEmail": "customer@example.com",
    "visitorId": "visitor_123",
    "sessionId": "session_456",
    "metadata": {
      "orderId": "order_789"
    }
  }'

​
Response

​
Success response (200)

{
  "status": "success",
  "data": {
    "paymentId": "payment_abc123",
    "message": "Payment recorded successfully"
  }
}

​
Error responses

​
Missing required fields (400)

{
  "status": "error",
  "error": {
    "code": 400,
    "message": "provider, providerPaymentId, and amount are required"
  }
}

​
Unauthorized (401)

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized. Invalid or missing API key."
  }
}

​
Linking payments to visitors

Payments are automatically linked to visitors using:
  1. Visitor/Session IDs (most reliable) - Include visitorId and sessionId in the request
  2. Email matching - If user identification is enabled, payments are linked via customerEmail
  3. Timestamp correlation - Fallback method using payment timestamp

​
Use cases

  • Custom payment providers - Record payments from providers not supported by webhooks
  • Manual payment entry - Record payments manually
  • Payment reconciliation - Sync payments from external systems
  • Testing - Test revenue attribution

​
Examples

​
Stripe payment

curl -X POST "https://your-domain.com/api/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "stripe",
    "providerPaymentId": "pi_1234567890",
    "amount": 99.99,
    "currency": "USD",
    "customerEmail": "customer@example.com",
    "visitorId": "visitor_123"
  }'

​
Custom provider

curl -X POST "https://your-domain.com/api/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "custom",
    "providerPaymentId": "payment_789",
    "amount": 49.99,
    "currency": "EUR",
    "customerEmail": "customer@example.com",
    "metadata": {
      "orderNumber": "ORD-12345"
    }
  }'

​
Next steps

Revenue attribution guide

Learn more about revenue attribution