Payments & Subscriptions API Endpoints

Overview

Endpoints for payment processing, subscription management, and billing.

Endpoint Summary

Endpoint	Method	Auth	Description
`/v1/subscriptions/plans`	GET	None	Get subscription plans
`/v1/subscriptions`	GET	JWT	Get user subscription
`/v1/subscriptions`	POST	JWT	Create subscription
`/v1/subscriptions/{subscriptionId}`	DELETE	JWT	Cancel subscription
`/v1/subscriptions/upgrade`	POST	JWT	Upgrade subscription
`/v1/subscriptions/billing-history`	GET	JWT	Get billing history
`/v1/payment/process`	POST	JWT	Process payment
`/v1/payment/methods`	GET	JWT	Get payment methods
`/v1/payment/methods`	POST	JWT	Add payment method
`/v1/payment/methods/{methodId}`	DELETE	JWT	Remove payment method
`/v1/payment/webhook`	POST	System	Payment webhook

Subscription Plans

GET `/v1/subscriptions/plans`

Description: Retrieves available subscription plans.

Response: SubscriptionPlansResponse

{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "description": "Basic access to picks and analytics",
      "price": 0,
      "currency": "USD",
      "interval": "month",
      "features": [
        "View public picks",
        "Basic analytics",
        "Limited game data"
      ],
      "limits": {
        "picksPerMonth": 10,
        "systemsAllowed": 1,
        "apiCalls": 100
      }
    },
    {
      "id": "pro",
      "name": "Pro",
      "description": "Full access to all features",
      "price": 19.99,
      "currency": "USD",
      "interval": "month",
      "features": [
        "Unlimited picks",
        "Advanced analytics",
        "Real-time odds",
        "Priority support"
      ],
      "limits": {
        "picksPerMonth": -1,
        "systemsAllowed": 10,
        "apiCalls": 10000
      },
      "popular": true
    },
    {
      "id": "enterprise",
      "name": "Enterprise",
      "description": "For professional bettors and teams",
      "price": 99.99,
      "currency": "USD",
      "interval": "month",
      "features": [
        "Everything in Pro",
        "API access",
        "Custom integrations",
        "Dedicated support"
      ],
      "limits": {
        "picksPerMonth": -1,
        "systemsAllowed": -1,
        "apiCalls": -1
      }
    }
  ],
  "annualDiscount": 20
}

User Subscription

GET `/v1/subscriptions`

Description: Retrieves user's current subscription.

Authentication: JWT required

Response: UserSubscriptionResponse

{
  "subscription": {
    "id": "sub_123abc",
    "planId": "pro",
    "planName": "Pro",
    "status": "active",
    "currentPeriodStart": "2025-11-01T00:00:00Z",
    "currentPeriodEnd": "2025-12-01T00:00:00Z",
    "cancelAtPeriodEnd": false,
    "autoRenew": true
  },
  "usage": {
    "picksThisMonth": 45,
    "picksLimit": -1,
    "systemsActive": 5,
    "systemsLimit": 10,
    "apiCallsThisMonth": 2500,
    "apiCallsLimit": 10000
  },
  "paymentMethod": {
    "type": "card",
    "last4": "4242",
    "brand": "visa",
    "expiryMonth": 12,
    "expiryYear": 2027
  }
}

Subscription Status Values:

active - Currently active
trialing - In trial period
past_due - Payment failed
canceled - Canceled but active until period end
expired - No longer active

POST `/v1/subscriptions`

Description: Creates a new subscription.

Authentication: JWT required

Request Body:

{
  "planId": "pro",
  "paymentMethodId": "pm_123abc",
  "interval": "month",
  "couponCode": "SAVE20"
}

Response: CreateSubscriptionResponse

{
  "subscription": {
    "id": "sub_123abc",
    "planId": "pro",
    "status": "active",
    "currentPeriodStart": "2025-11-29T00:00:00Z",
    "currentPeriodEnd": "2025-12-29T00:00:00Z"
  },
  "invoice": {
    "id": "inv_456def",
    "amount": 19.99,
    "currency": "USD",
    "status": "paid",
    "paidAt": "2025-11-29T12:00:00Z"
  }
}

DELETE `/v1/subscriptions/{subscriptionId}`

Description: Cancels a subscription.

Authentication: JWT required

Path Parameters:

subscriptionId (string) - Subscription identifier

Query Parameters:

Parameter	Type	Default	Description
`immediate`	bool	false	Cancel immediately vs end of period

Response:

{
  "subscription": {
    "id": "sub_123abc",
    "status": "canceled",
    "cancelAtPeriodEnd": true,
    "currentPeriodEnd": "2025-12-29T00:00:00Z"
  },
  "message": "Subscription will remain active until Dec 29, 2025"
}

POST `/v1/subscriptions/upgrade`

Description: Upgrades subscription to a higher plan.

Authentication: JWT required

Request Body:

{
  "newPlanId": "enterprise",
  "prorate": true
}

Response:

{
  "subscription": {
    "id": "sub_123abc",
    "planId": "enterprise",
    "status": "active"
  },
  "prorationCredit": 12.50,
  "amountDue": 87.49,
  "effectiveDate": "2025-11-29T12:00:00Z"
}

GET `/v1/subscriptions/billing-history`

Description: Retrieves billing history.

Authentication: JWT required

Query Parameters:

Parameter	Type	Default	Description
`page`	int	1	Page number
`pageSize`	int	20	Items per page

Response:

{
  "invoices": [
    {
      "id": "inv_456def",
      "date": "2025-11-29T00:00:00Z",
      "amount": 19.99,
      "currency": "USD",
      "status": "paid",
      "description": "Pro subscription - Monthly",
      "receiptUrl": "https://..."
    },
    {
      "id": "inv_789ghi",
      "date": "2025-10-29T00:00:00Z",
      "amount": 19.99,
      "currency": "USD",
      "status": "paid",
      "description": "Pro subscription - Monthly",
      "receiptUrl": "https://..."
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 12,
    "totalPages": 1
  }
}

Payment Methods

GET `/v1/payment/methods`

Description: Retrieves user's saved payment methods.

Authentication: JWT required

Response:

{
  "paymentMethods": [
    {
      "id": "pm_123abc",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "expiryMonth": 12,
        "expiryYear": 2027
      },
      "isDefault": true,
      "createdAt": "2024-06-15T00:00:00Z"
    },
    {
      "id": "pm_456def",
      "type": "card",
      "card": {
        "brand": "mastercard",
        "last4": "5555",
        "expiryMonth": 6,
        "expiryYear": 2026
      },
      "isDefault": false,
      "createdAt": "2025-01-10T00:00:00Z"
    }
  ]
}

POST `/v1/payment/methods`

Description: Adds a new payment method.

Authentication: JWT required

Request Body:

{
  "paymentMethodId": "pm_stripe_token_from_client",
  "setAsDefault": true
}

Note: Payment method tokens are obtained from Stripe.js on the client side.

Response:

{
  "paymentMethod": {
    "id": "pm_789ghi",
    "type": "card",
    "card": {
      "brand": "amex",
      "last4": "0005",
      "expiryMonth": 3,
      "expiryYear": 2028
    },
    "isDefault": true
  }
}

DELETE `/v1/payment/methods/{methodId}`

Description: Removes a payment method.

Authentication: JWT required

Path Parameters:

methodId (string) - Payment method identifier

Response: 204 No Content

Payment Processing

POST `/v1/payment/process`

Description: Processes a one-time payment.

Authentication: JWT required

Request Body:

{
  "amount": 49.99,
  "currency": "USD",
  "paymentMethodId": "pm_123abc",
  "description": "Contest entry fee",
  "metadata": {
    "contestId": 12345
  }
}

Response:

{
  "payment": {
    "id": "pay_abc123",
    "amount": 49.99,
    "currency": "USD",
    "status": "succeeded",
    "description": "Contest entry fee",
    "receiptUrl": "https://..."
  }
}

Payment Status Values:

succeeded - Payment completed
pending - Processing
failed - Payment failed
refunded - Refunded

Webhooks

POST `/v1/payment/webhook`

Description: Handles payment provider webhooks.

Authentication: Signature verification (Stripe webhook signature)

Headers:

Stripe-Signature: Webhook signature

Request Body: Stripe webhook event

Handled Events:

invoice.paid - Invoice payment successful
invoice.payment_failed - Invoice payment failed
customer.subscription.updated - Subscription changed
customer.subscription.deleted - Subscription canceled

Response: 200 OK

Examples

Get Subscription Plans

curl -X GET "https://api.example.com/v1/subscriptions/plans"

Get User Subscription

curl -X GET "https://api.example.com/v1/subscriptions" \
  -H "Authorization: Bearer eyJ..."

Create Subscription

curl -X POST "https://api.example.com/v1/subscriptions" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "pro",
    "paymentMethodId": "pm_123abc"
  }'

Cancel Subscription

curl -X DELETE "https://api.example.com/v1/subscriptions/sub_123abc" \
  -H "Authorization: Bearer eyJ..."

Add Payment Method

curl -X POST "https://api.example.com/v1/payment/methods" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId": "pm_from_stripe", "setAsDefault": true}'

Get Billing History

curl -X GET "https://api.example.com/v1/subscriptions/billing-history" \
  -H "Authorization: Bearer eyJ..."

Related Endpoints

User Management - User accounts
Contests - Contest entry fees

Payments & Subscriptions API Endpoints

Overview

Endpoint Summary

Subscription Plans

GET /v1/subscriptions/plans

User Subscription

GET /v1/subscriptions

POST /v1/subscriptions

DELETE /v1/subscriptions/{subscriptionId}

POST /v1/subscriptions/upgrade

GET /v1/subscriptions/billing-history

Payment Methods

GET /v1/payment/methods

POST /v1/payment/methods

DELETE /v1/payment/methods/{methodId}

Payment Processing

POST /v1/payment/process

Webhooks

POST /v1/payment/webhook

Examples

Get Subscription Plans

Get User Subscription

Create Subscription

Cancel Subscription

Add Payment Method

Get Billing History

Related Endpoints

GET `/v1/subscriptions/plans`

GET `/v1/subscriptions`

POST `/v1/subscriptions`

DELETE `/v1/subscriptions/{subscriptionId}`

POST `/v1/subscriptions/upgrade`

GET `/v1/subscriptions/billing-history`

GET `/v1/payment/methods`

POST `/v1/payment/methods`

DELETE `/v1/payment/methods/{methodId}`

POST `/v1/payment/process`

POST `/v1/payment/webhook`