Skip to main content

Financial Endpoints

Complete reference for subscription, billing, and credit management endpoints.

Base URLs​

https://api.govalid.org/api/v1/financial/
https://api.govalid.org/api/v1/credits/

Plans​

List Available Plans​

GET /api/v1/financial/plans/

Response​

{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price": 0,
      "currency": "USD",
      "billing_period": "monthly",
      "features": ["Smart QR", "Basic analytics"],
      "limits": {
        "qr_codes_per_month": 10,
        "api_requests_per_hour": 100
      }
    },
    {
      "id": "pro",
      "name": "Pro",
      "price": 9.99,
      "currency": "USD",
      "billing_period": "monthly",
      "features": ["Smart QR", "Secure QR", "Full analytics", "Bulk generation"],
      "limits": {
        "qr_codes_per_month": 500,
        "api_requests_per_hour": 1000
      }
    }
  ]
}

Subscription​

Get Subscription Status​

GET /api/v1/financial/subscription/

Response​

{
  "plan": "pro",
  "status": "active",
  "billing_period": "monthly",
  "next_billing_date": "2025-02-28",
  "amount": 9.99,
  "currency": "USD",
  "usage": {
    "qr_codes": {
      "used": 150,
      "limit": 500
    },
    "api_calls": {
      "used": 4521,
      "limit": 1000,
      "reset_at": "2025-02-01T00:00:00Z"
    }
  }
}

Subscribe to Plan​

POST /api/v1/financial/subscribe/

Request Body​

{
  "plan_id": "pro",
  "payment_method": "stripe",
  "billing_period": "monthly"
}

Invoices​

List Invoices​

GET /api/v1/financial/invoices/

Response​

{
  "count": 5,
  "results": [
    {
      "id": "INV-2025-001",
      "amount": 9.99,
      "currency": "USD",
      "status": "paid",
      "date": "2025-01-28",
      "pdf_url": "https://api.govalid.org/api/v1/financial/invoices/INV-2025-001/pdf/"
    }
  ]
}

Download Invoice PDF​

GET /api/v1/financial/invoices/{id}/pdf/

Credits​

Get Credit Balance​

GET /api/v1/credits/balance/

Response​

{
  "balance": 500,
  "currency": "USD",
  "last_topup": "2025-01-15T10:00:00Z"
}

List Credit Packages​

GET /api/v1/credits/packages/

Top Up Credits​

POST /api/v1/credits/topup/

Request Body​

{
  "package_id": "business",
  "payment_method": "stripe"
}

Verify Coupon​

POST /api/v1/credits/coupon/verify/

Request Body​

{
  "code": "SAVE20"
}

Transactions​

List Transactions​

GET /api/v1/financial/transactions/

Response​

{
  "count": 10,
  "results": [
    {
      "id": "TXN-001",
      "type": "subscription",
      "amount": 9.99,
      "currency": "USD",
      "status": "completed",
      "date": "2025-01-28T00:00:00Z",
      "description": "Pro Plan - Monthly"
    },
    {
      "id": "TXN-002",
      "type": "credit_topup",
      "amount": 50.00,
      "currency": "USD",
      "status": "completed",
      "date": "2025-01-15T10:00:00Z",
      "description": "Credit Top-up - Business Package"
    }
  ]
}

Pricing​

Get Pricing Info​

GET /api/v1/financial/pricing/

Response​

{
  "qr_pricing": {
    "smart": {"base_cost": 1, "currency": "credits"},
    "verified": {"base_cost": 1.5, "currency": "credits"},
    "secure": {"base_cost": 2, "currency": "credits"},
    "enterprise": {"base_cost": 3, "currency": "credits"}
  },
  "bulk_discounts": [
    {"min_quantity": 100, "discount": 0.10},
    {"min_quantity": 500, "discount": 0.20},
    {"min_quantity": 1000, "discount": 0.30}
  ]
}

Payment Callbacks​

Payment gateways send callbacks to confirm transactions:

  • Stripe: /api/v1/financial/stripe/callback/
  • PayPal: /api/v1/financial/paypal/callback/
  • iPaymu: /api/v1/financial/ipaymu/callback/