5CRSE5CRSEDocumentation
← Back to site

#5CRSE Payment Processing API Documentation

This document provides detailed information about the payment processing API endpoints for the 5CRSE platform.

#Payment Service Providers

The platform supports two payment service providers:

  1. Stripe - For credit/debit card payments
  2. Square - For Square payments

#API Endpoints

#Stripe Endpoints

Create Checkout Session

Create a Stripe checkout session for a booking.

  • URL: /api/stripe/create-checkout-session
  • Method: POST
  • Request Body: 
    {
  "bookingId": "BK-123456-7890",
  "amount": 99.99,
  "currency": "usd",
  "eventName": "Event Name",
  "customerEmail": "customer@example.com",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel"
}
  • Response: 
    {
  "url": "https://checkout.stripe.com/...",
  "sessionId": "cs_test_..."
}

Process Refund

Process a refund for a Stripe payment.

  • URL: /api/stripe/refund
  • Method: POST
  • Request Body: 
    {
  "paymentId": "pi_1234567890",
  "bookingId": "123456",
  "amount": 99.99,
  "reason": "Customer requested"
}
  • Response: 
    {
  "message": "Refund processed successfully",
  "refund": { /* refund details */ }
}

Webhook

Handle Stripe webhook events.

  • URL: /api/stripe/webhook
  • Method: POST
  • Headers:
    • stripe-signature: Webhook signature
  • Request Body: Raw webhook event payload
  • Response: 
    {
  "received": true,
  "status": "success",
  "message": "Webhook handled: payment_intent.succeeded"
}

Session Details

Get details for a Stripe checkout session.

  • URL: /api/stripe/session-details
  • Method: GET
  • Query Parameters:
    • session_id: Stripe checkout session ID
  • Response: 
    {
  "session_id": "cs_test_...",
  "payment_intent_id": "pi_...",
  "booking_id": "BK-1234",
  "payment_id": "pay_123",
  "payment_status": "paid",
  "amount": 99.99,
  "currency": "USD",
  "customer_email": "customer@example.com"
}

#Square Endpoints

Create Payment Link

Create a Square payment link for a booking.

  • URL: /api/square/create-payment-link
  • Method: POST
  • Request Body: 
    {
  "bookingId": "BK-123456-7890",
  "amount": 99.99,
  "currency": "USD",
  "eventName": "Event Name",
  "redirectUrl": "https://example.com/success"
}
  • Response: 
    {
  "url": "https://square.link/...",
  "paymentLinkId": "link_..."
}

Process Refund

Process a refund for a Square payment.

  • URL: /api/square/refund
  • Method: POST
  • Request Body: 
    {
  "paymentId": "sqr_1234567890",
  "bookingId": "123456",
  "amount": 99.99,
  "reason": "Customer requested"
}

Webhook

Handle Square webhook events.

  • URL: /api/square/webhook
  • Method: POST
  • Headers:
    • x-square-hmacsha256-signature: Webhook signature
  • Request Body: Raw webhook event payload
  • Response: 
    {
  "received": true,
  "status": "success",
  "message": "Webhook handled: payment.updated"
}

#Payment Management Endpoints

Get Payment Status

Check the status of a payment.

  • URL: /api/payments/:paymentId/status
  • Method: GET
  • Response: 
    {
  "success": true,
  "message": "Payment status retrieved successfully",
  "paymentId": "pay_123",
  "bookingId": "book_123",
  "amount": 99.99,
  "currency": "usd",
  "status": "completed",
  "providerStatus": "succeeded",
  "receiptUrl": "/api/receipts/pay_123",
  "paymentDate": "2025-04-01T12:00:00Z"
}

Generate Receipt

Generate an HTML receipt for a payment.

  • URL: /api/payments/:paymentId/generate-receipt
  • Method: POST
  • Response: 
    {
  "message": "Receipt generated successfully",
  "receiptUrl": "/api/receipts/pay_123?receipt_number=STRP-1712345678-001",
  "receiptNumber": "STRP-1712345678-001"
}

Get Receipt

Retrieve an HTML receipt for a payment.

  • URL: /api/receipts/:paymentId
  • Method: GET
  • Query Parameters:
    • receipt_number: (Optional) Receipt number
  • Response: HTML receipt document

Generate PDF Receipt

Generate a PDF receipt for a payment.

  • URL: /api/payments/:paymentId/pdf-receipt
  • Method: POST
  • Response: 
    {
  "message": "PDF receipt generated successfully",
  "pdfUrl": "/media/receipts/receipt-STRP-1712345678-001.pdf",
  "receiptNumber": "STRP-1712345678-001"
}

Payment Statistics

Get payment statistics.

  • URL: /api/payments/stats
  • Method: GET
  • Query Parameters:
    • from: Start date (YYYY-MM-DD)
    • to: End date (YYYY-MM-DD)
    • provider: Payment provider filter (stripe, square, all)
  • Response: 
    {
  "total_payments": 100,
  "total_amount": 9999.99,
  "completed_payments": 80,
  "completed_amount": 8888.88,
  "refunded_payments": 5,
  "refunded_amount": 555.55,
  "failed_payments": 10,
  "pending_payments": 5,
  "by_provider": {
    "stripe": {
      "count": 60,
      "amount": 6666.66
    },
    "square": {
      "count": 40,
      "amount": 3333.33
    }
  },
  "by_payment_method": {
    "credit_card": 70,
    "debit_card": 10,
    "bank_transfer": 5,
    "digital_wallet": 15
  },
  "by_month": [
    {
      "month": "2025-01",
      "count": 30,
      "amount": 3000.00
    },
    {
      "month": "2025-02",
      "count": 25,
      "amount": 2500.00
    }
  ],
  "recent_payments": [
    {
      "id": "pay_123",
      "transaction_id": "tx_123",
      "amount": 99.99,
      "currency": "usd",
      "status": "completed",
      "payment_provider": "stripe",
      "created_at": "2025-04-01T12:00:00Z"
    }
  ]
}

#Data Models

#Payment Object

interface Payment {
  id: string;
  booking: string | { id: string };
  payment_provider: 'stripe' | 'square';
  transaction_id: string;
  amount: number;
  currency: string;
  status: 'pending' | 'completed' | 'failed' | 'refunded' | 'partially_refunded';
  payment_method?: 'credit_card' | 'debit_card' | 'bank_transfer' | 'digital_wallet';
  payment_metadata?: string; // JSON string with provider-specific data
  receipt_url?: string;
  pdf_receipt_url?: string;
  customer_email?: string;
  refund_id?: string;
  notes?: string;
  createdAt: string;
  updatedAt: string;
}

#Error Handling

All endpoints return error responses in the following format:

{
  "message": "Error message",
  "error": "Detailed error description"
}

HTTP status codes:

  • 200: Success
  • 400: Bad request (missing parameters)
  • 404: Resource not found
  • 500: Server error

#Authentication

All payment endpoints require authentication. Requests must include a valid authentication token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

#Environment Variables

The following environment variables are required:

  • STRIPE_SECRET_KEY: Stripe API secret key
  • STRIPE_WEBHOOK_SECRET: Stripe webhook signing secret
  • SQUARE_ACCESS_TOKEN: Square API access token
  • SQUARE_LOCATION_ID: Square location ID
  • SQUARE_WEBHOOK_SIGNATURE_KEY: Square webhook signature key