Skip to main content

PayTabs Payment Flow

Flow Overview​

These diagrams outline the process for handling VIP subscription purchases using the PayTabs payment gateway.

1. Purchase Initiation

2. Payment Execution, Callback & Subscription Update

Process Description​

  1. Purchase Initiation:

    • User selects a VipPackage on the frontend and chooses to pay via Credit Card (PayTabs).
    • Frontend calls the backend's createOrder endpoint, passing the vip_package_id.
    • PayTabsService::createOrder calculates totals and creates an Order record with status = PENDING and payment_method = CREDIT_CARD.
    • It then calls Initiating, which validates config and calls createPayPage.
    • createPayPage uses the PayTabs SDK Facade (paypage) to configure the payment request (cart details, customer info, URLs, language, framing).
    • The service returns configuration details (like cart ID, amount, description) needed by the frontend Flutter SDK to initiate the PayTabs payment UI.

  2. Payment Execution:

    • The user interacts with the PayTabs payment interface within the mobile app (using the Flutter SDK) and enters their payment details.
    • PayTabs processes the payment.

  3. PayTabs Callback Handling:

    • Upon completion (success or failure), PayTabs sends a callback request to the backend endpoint (/paytabs/callback), including the cart_id (Order ID) and tran_ref (PayTabs transaction reference).
    • The backend route invokes PayTabsService::callback with these parameters.
    • PayTabsService::callback calls getTransactionResponse (which uses Paypage::queryTransaction) to get the final status of the transaction from PayTabs using the tran_ref.
    • The service checks isPaymentSuccessful based on the response status ('A'), cart ID match, transaction type ('Sale'), and overall success flag.
    • If Successful:
      • It checks if the User already hasSubscription.
      • Renewal: If a subscription exists, it updates the Order status to COMPLETED quietly (to prevent the observer from firing immediately) and stores the payment_reference_id and payment_card_type. It then calls its own renewSubscription method, which in turn calls VipSubscriptionService::renewVipSubscription to update the existing VipSubscription. (See VIP Subscriptions Flow for details).
      • New Subscription: If no subscription exists, it updates the Order status to COMPLETED normally, storing the payment_reference_id and payment_card_type. This update triggers the OrderObserver, which calls the VipSubscriptionService to create a new VipSubscription. (See VIP Subscriptions Flow for details).
    • If Failed:
      • The service checks isPaymentFailed.
      • It updates the Order status to FAILED and stores the payment_reference_id and payment_card_type.

Key Models & Services​

  • PayTabsService: Handles the creation of PayTabs payment requests and processes the callbacks.
  • Order: Tracks the purchase transaction, status, payment method, and PayTabs transaction reference.
  • VipPackage: Defines the subscription plan being purchased.
  • User: The customer account making the purchase.
  • VipSubscriptionService: Handles the creation and renewal logic for VipSubscription records, triggered after successful payment confirmation by PayTabsService or the OrderObserver. (See VIP Subscriptions Flow).
  • OrderObserver: Listens for Order updates to trigger VipSubscriptionService for new subscriptions.
  • Paytabscom\Laravel_paytabs\Facades\paypage: The PayTabs SDK Facade used for interacting with the PayTabs API.