Create Order (Checkout)

Create a new order for a VIP package.

Endpoint

• Method: POST
• URL: /api/orders/checkout

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Parameters

Parameter	Type	Required	Description
payment_method	string	Yes	Payment method (credit_card, in_app_purchase)
vip_package_id	integer	Yes*	ID of the VIP package (required for credit_card)
iap_product_id	string	Yes*	Product ID for in-app purchase (required for in_app_purchase)

*One of vip_package_id or iap_product_id is required based on the payment_method

Success Response

For Credit Card (PayTabs)

{
    "success": true,
    "message": "ok",
    "data": {
        "tran_type": "sale",
        "tran_class": "ecom",
        "cart_id": "123",
        "cart_currency": "SAR",
        "cart_amount": 99.99,
        "cart_description": "Payment for Subscription order number 123",
        "customer_details": {
            "name": "John Doe",
            "email": "john@example.com",
            "phone": "966500000000",
            "street1": "Saudi Arabia",
            "city": "Saudi Arabia",
            "state": "Saudi Arabia",
            "country": "SA",
            "zip": "1111",
            "ip": "127.0.0.1"
        },
        "order_number": "ORD-123",
        "tax": 15.00
    }
}

For In-App Purchase (iOS)

{
    "success": true,
    "message": "ok",
    "data": {
        "order_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

Implementation Flow

1. Request Validation

   • Validates required parameters (payment_method)
   • Validates vip_package_id for credit_card payment
   • Validates iap_product_id for in_app_purchase payment

2. Pre-checkout Validation

   • Verifies user has a phone number
   • Checks if user already has an active subscription

3. Payment Processing

   • For Credit Card:
     1. Validates if user can use free trial
     2. Creates PayTabs order with customer details
     3. Returns payment URL and transaction details
   • For In-App Purchase:
     1. Creates pending order with UUID
     2. Returns order_id for iOS validation

4. Error Handling

   • Handles missing phone number
   • Handles active subscription conflicts
   • Handles invalid payment methods

Error Responses

Missing Phone Number

{
    "success": false,
    "message": "User must have a phone number",
    "data": null,
    "status_code": 422
}

Active Subscription

{
    "success": false,
    "message": "User already has an active subscription",
    "data": null,
    "status_code": 422
}

Invalid Payment Method

{
    "success": false,
    "message": "Invalid payment method",
    "data": null,
    "status_code": 422
}