API Endpoints Roles & Tiers Payment Integration

Payment Integration with checkout.gfavip.com

Status: ✅ Fully integrated and production-ready

Payment Flow Overview

Student clicks "Enroll" on a paid course
System checks membership eligibility (chapters/tickets/wallet)
System calculates price based on user's tier
Invoice created via checkout.gfavip.com API
Student redirected to payment page
Student pays with GFAVIP wallet balance
checkout.gfavip.com sends webhook to learning platform
Platform auto-enrolls student

Invoice Creation

POST https://checkout.gfavip.com/api/admin/invoices

Headers:

Authorization: Bearer {SSO_TOKEN}
Content-Type: application/json

Request Body:

{
  "recipient": "user@email.com",
  "amount": 25.00,
  "description": "Course Enrollment - Course Title",
  "dueInDays": 7,
  "currency": "USD",
  "metadata": {
    "course_id": 1,
    "user_id": "sso-user-id",
    "source": "learning.gfavip.com",
    "redirect_url": "https://learning.gfavip.com/student",
    "webhook_url": "https://learning.gfavip.com/webhooks/payment"
  }
}

Response:

{
  "success": true,
  "invoice": {
    "id": "uuid-here",
    "gfaInvoiceId": "GFA-INV123",
    "paymentUrl": "https://checkout.gfavip.com/pay/{uuid}",
    ...
  }
}

Webhook Integration

Security: All webhooks are verified using HMAC-SHA256 signatures with WEBHOOK_SECRET

POST /webhooks/payment

Headers:

X-Webhook-Signature: {HMAC_SHA256_SIGNATURE}
Content-Type: application/json

Payload Structure:

{
  "event": "invoice.paid",
  "invoice": {
    "id": "uuid",
    "amount": 25.00,
    "metadata": {
      "course_id": 1,
      "user_id": "sso-user-id",
      "source": "learning.gfavip.com"
    }
  }
}

Supported Events:

invoice.paid → Auto-enrolls student in course
invoice.failed → Cancels enrollment
invoice.expired → Cancels enrollment
invoice.cancelled → Cancels enrollment

Pricing Tiers

Membership Type	Check Via	Price Multiplier	Example (Base $100)
Chapter Member	chapters.gfavip.com API	0.5x (50% off)	$50.00
Ticket Holder	tickets.gfavip.com API	0.7x (30% off)	$70.00
Global Member	wallet.gfavip.com API	0.8x (20% off)	$80.00
Standard	-	1.0x (No discount)	$100.00

Security Features

Webhook Verification

HMAC-SHA256 signature validation
Timing-safe comparison
Requires WEBHOOK_SECRET env var
Rejects unsigned webhooks (401)

SSO ID Handling

All external APIs use SSO IDs
Webhook converts SSO → internal ID
Prevents enrollment mismatches
Returns 404 if user not found

Testing

How to Test Payment Flow:

Ensure WEBHOOK_SECRET is configured in environment
Create a test course with pricing tiers set
Login as a test student
Click "Enroll" on paid course
Verify redirect to checkout.gfavip.com
Complete payment (or simulate webhook)
Check student is auto-enrolled
Review server logs for debug output

Environment Variables

Required for Production:

WEBHOOK_SECRET - HMAC signature key (REQUIRED)
SESSION_SECRET - Flask session encryption
DATABASE_URL - PostgreSQL connection