POST Payment

Record payments and link them to visitors for revenue attribution.

Endpoint

POST /api/v1/payment

Authentication

Requires API key authentication.

Request body

Field	Type	Required	Description
`provider`	string	Yes	Payment provider (e.g., “stripe”, “lemonsqueezy”, “custom”)
`providerPaymentId`	string	Yes	Payment ID from the provider
`amount`	number	Yes	Payment amount (in dollars, e.g., 99.99)
`currency`	string	No	Currency code (defaults to “USD”)
`customerEmail`	string	No	Customer email address
`customerId`	string	No	Customer ID from provider
`visitorId`	string	No	Visitor ID (for linking)
`sessionId`	string	No	Session ID (for linking)
`metadata`	object	No	Additional 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:

Visitor/Session IDs (most reliable) - Include visitorId and sessionId in the request
Email matching - If user identification is enabled, payments are linked via customerEmail
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

Get started

Endpoints

Endpoint

Authentication

Request body

Request example

Response

Success response (200)

Error responses

Missing required fields (400)

Unauthorized (401)

Linking payments to visitors

Use cases

Examples

Stripe payment

Custom provider

Next steps

Revenue attribution guide

​Endpoint

​Authentication

​Request body

​Request example

​Response

​Success response (200)

​Error responses

​Missing required fields (400)

​Unauthorized (401)

​Linking payments to visitors

​Use cases

​Examples

​Stripe payment

​Custom provider

​Next steps

Revenue attribution guide

Endpoint

Authentication

Request body

Request example

Response

Success response (200)

Error responses

Missing required fields (400)

Unauthorized (401)

Linking payments to visitors

Use cases

Examples

Stripe payment

Custom provider

Next steps