Skip to main content

PayTabs Payment Callback

Handle payment completion callback from PayTabs.

Endpoint​

  • Method: POST
  • URL: /api/paytabs/callback

Request Parameters​

ParameterTypeRequiredDescription
cart_idstringYesThe order ID in our system
tran_refstringYesPayTabs transaction reference

PayTabs Response Data​

The transaction response from PayTabs includes:

{
    "success": true,
    "payment_result": {
        "response_status": "A",  // A = Approved
        "response_message": "Authorised"
    },
    "payment_info": {
        "payment_method": "credit_card",
        "card_type": "Credit",
        "card_scheme": "Visa"
    },
    "tran_type": "Sale",
    "cart_id": "123",
    "cart_amount": 99.99
}

Success Response​

{
    "success": true,
    "message": "ok",
    "data": null,
    "status_code": 204
}

Implementation Flow​

  1. Callback Reception

    • Receives callback data from PayTabs server
    • Extracts cart_id and tran_ref
    • Validates request authenticity using PayTabs signature

  2. Asynchronous Processing

    • Dispatches ProcessPaytabsPaymentJob to handle payment
    • Runs on 'high' priority queue
    • Prevents timeout issues for long-running operations

  3. Payment Verification

    • Retrieves order using cart_id
    • Fetches transaction details from PayTabs using tran_ref
    • Validates payment status:
      • Success flag must be true
      • Response status must be 'A' (Approved)
      • Transaction type must be 'Sale'
      • Cart ID must match order ID

  4. Data Integrity

    • Uses database transactions for atomic updates
    • Rollback on any failure to maintain consistency
    • Handles duplicate payment notifications

Security Measures​

  1. Request Validation

    • Validates PayTabs server IP address
    • Verifies digital signature
    • Validates required parameters

  2. Data Protection

    • Secure storage of payment details
    • PCI-compliant card data handling
    • Encrypted communication

Error Handling​

  • Invalid signature: Returns 401 Unauthorized
  • Missing parameters: Returns 422 Unprocessable Entity
  • Server errors: Returns 500 Internal Server Error

VIP Subscription Process​

  1. New Subscription Creation

    • Triggered when a new user completes their first payment
    • Creates a VIP subscription record with:
      • Start date: Current time
      • Expire date: Current time + package duration
      • Status: ONGOING
      • Duration: Package duration (or trial days if applicable)
    • Handles free trial logic if user is eligible
      • Sets is_free = true
      • Uses trial duration instead of package duration
      • Sets type to FREE_TRIAL

  2. Subscription Renewal

    • Triggered when existing subscriber makes a new payment
    • Updates the existing subscription with:
      • New start date: Current time
      • New expire date: Current time + package duration
      • Status remains ONGOING
      • Duration: Package duration + any remaining days
      • Type: RENEWAL
    • Records renewal timestamp
    • Maintains subscription history

  3. Duration Calculation

    • For new subscriptions: Uses package duration directly
    • For renewals: Adds remaining days from old subscription
    • For free trials: Uses trial period duration

  4. Status Management

    • ONGOING: Active subscription
    • ENDED: Expired or cancelled subscription
    • Tracks is_active flag separately
    • Records expiration time if subscription ends

Implementation Notes​

  • High-priority queue ensures quick payment processing
  • Asynchronous processing prevents timeout issues
  • Transaction logging for audit and debugging
  • Idempotent processing prevents duplicate payments