Order Confirmation Endpoint

This endpoint handles the final step of the checkout process, confirming the order and processing the payment for authenticated users.

Endpoint

POST /v1/customer/cart/checkout

Request Parameters

Parameter	Type	Required	Description
products	array	Yes	Array of products to be processed
products.*.with_certificate	boolean	No	Whether to include certificate with the product
products.*.with_summary	boolean	No	Whether to include summary with the product
payment	boolean	Yes	Must be set to true for order confirmation
order_confirmed	boolean	Yes	Must be set to true for order confirmation
coupon	string	No	Coupon code to apply discount
use_new_customer_discount	boolean	No	Whether to apply new customer discount
use_wallet	boolean	No	Whether to use wallet balance for payment
payment_method	string	Yes	The selected payment method (paytabs_credit_card, tabby, tamara, bank_transfer, apple_pay, wallet)
bank_id	string	Conditional	Required when payment_method is bank_transfer. ID of the bank account
bank_transfer_source	string	Conditional	Required for bank_transfer. Source country of the transfer (Saudi Arabia, Libya, Sudan, Iraq, Algeria, Syria, Lebanon, Morocco, Tunisia, Egypt, Jordan, Palestine, Kuwait, Turkey, Yemen, PayPal, Other)
transfers	array	Conditional	Required for bank_transfer. Array of transfer receipt images

Response

Paytabs Credit Card

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "cart_items": {
            "payment_url": "https://secure.paytabs.sa/payment/wr/5D29DC4982E637EAD9D368AD3FCB07A26BE4B88CCD7FDA13EAD9D401"
        },
        "discounts": [
            {
                "amount": "100.00",
                "code": "ITdept",
                "method": "percentage"
            }
        ],
        "related_products": []
    },
    "status_code": 200
}

Tamara

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "order_id": "b2400dd8-8a09-43b1-a63a-9de3c7a9b380",
        "checkout_id": "304bac65-f55d-4c3e-9612-32ff3fd65a8a",
        "checkout_url": "https://checkout-sandbox.tamara.co/checkout/304bac65-f55d-4c3e-9612-32ff3fd65a8a?locale=ar_SA&orderId=b2400dd8-8a09-43b1-a63a-9de3c7a9b380",
        "status": "new"
    },
    "status_code": 200
}

Tabby

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "cart_items": {
            "payment_id": "8fccc3fa-c8c8-4726-91d1-ff9547a9417f",
            "payment_status": "CREATED",
            "order_reference_id": "d8a2d440-0459-11f0-b191-697848f9f3c2",
            "checkout_url": "https://checkout.tabby.ai/?apiKey=pk_test_32ab530b-c6bb-4731-851d-b46c02dc2082&lang=ara&merchantCode=Sumaya&product=installments&sessionId=1cb54337-b21b-4a48-b8ce-e8bb8295e258"
        },
        "discounts": [
            {
                "amount": "100.00",
                "code": "ITdept",
                "method": "percentage"
            }
        ],
        "related_products": []
    },
    "status_code": 200
}

Bank Transfer

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "cart_items": {
            "id": "6db34390-045a-11f0-a5ca-f7316389e866",
            "payment_method": "bank_transfer",
            "number": 2503156942,
            "is_free": false
        },
        "discounts": [
            {
                "amount": "100.00",
                "code": "ITdept",
                "method": "percentage"
            }
        ],
        "related_products": []
    },
    "status_code": 200
}

Apple Pay

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "cart_items": {
            "payment_url": "https://secure.paytabs.sa/payment/wr/5D29D1F782E608849EEDF7DF1F39F45D75ED88858CC28F2FB5659650"
        },
        "discounts": [],
        "related_products": []
    },
    "status_code": 200
}

Implementation Details

Flow

1. Validates the incoming request parameters
2. Verifies cart items availability
3. Validates payment method selection
4. Creates order record in the database
5. Processes payment through selected payment gateway
6. Returns order details and payment URL if applicable

Special Cases

Payment Method Validation

• Selected payment method must be one of: paytabs_credit_card, tabby, tamara, bank_transfer, apple_pay, wallet
• Bank transfer requires additional fields (bank_id, bank_transfer_source, transfers)
• Some payment methods may have minimum/maximum amount restrictions
• Wallet payment requires sufficient balance

Order Creation

• Generates unique order number
• Locks product inventory during order creation
• Records all applied discounts
• Stores payment method details

Payment Processing

• Different flows for different payment methods
• Handles payment gateway redirections
• Records payment attempts and status
• For bank transfers, stores receipt images

Common error cases:

• Invalid payment method
• Missing required fields for bank transfer
• Payment gateway errors
• Insufficient wallet balance
• Product became unavailable

Notes

• Order confirmation is final and cannot be modified
• Payment URL validity may vary by payment method
• Some payment methods may require additional verification steps
• Bank transfer receipts must be image files
• All referral and promo calclations are finalized at this point