Payment Methods

This guide explains how to interact with the payments API endpoints in the Calwe application.

Show Payment Checkout

Endpoint

• Method: GET
• URL: /v1/customer/payments/checkout-show

Request Headers

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

Query Parameters

Parameter	Type	Description	Required	Default
revoking_discount	boolean	Whether to revoke current discount	No	false
coupon_code	string	Apply a new coupon code	No	null

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "id": "uuid",
        "duration": "60 دقيقة",
        "subtotal": "2500.00 ر.س",
        "totalDiscount": "0.00 ر.س",
        "totalTax": "375.00 ر.س",
        "totalPrice": "2875.00 ر.س",
        "coachName": "احمد محمد البيتي",
        "canPayByWallet": true,
        "walletBalance": "7000.00 ر.س",
        "category": "استشارة طبية",
        "availableCoupons": [
            "JYUT"
        ],
        "isUsingDiscount": false
    },
    "statusCode": 200
}

Error Responses

Order Not Found (301)

{
    "success": false,
    "message": "لم يتم العثور على اي طلب",
    "data": [],
    "statusCode": 301
}

Process Payment

Endpoint

• Method: POST
• URL: /v1/customer/payments/checkout-pay

Request Headers

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

Request Body

Parameter	Type	Description	Required	Default
payment_method	string	Payment method to use (WALLET, CREDIT_CARD, APPLE_PAY)	Yes	-

Success Response

Wallet Payment

{
    "success": true,
    "message": "تمت عملية الدفع بنجاح,بضع ثوانٍ حتى يتم تحديث حالة الطلب",
    "data": {
        "id": "uuid",
        "type": "INTERNAL",
        "amount": "2875.00",
        "notes": "تم تحويل المبلغ الخاص بالطلب إلى محفظة النظام إلى حين اكتمال الجلسة",
        "orderNumber": 000000000,
        "paymentMethod": "WALLET",
        "sessionType": "SCHEDULED"
    },
    "statusCode": 200
}

Credit Card/Apple Pay Payment

{
    "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
    }
}

Error Responses

Order Not Found (404)

{
    "success": false,
    "message": "لم يتم العثور على اي طلب",
    "data": [],
    "statusCode": 301
}

Invalid Payment Method (422)

{
    "success": false,
    "message": "حدث خطأ في البيانات المرسلة يرجى التحقق منها.",
    "errors": {
        "paymentMethod": "نوع الدفع غير صحيح"
    },
    "data": [],
    "statusCode": 422
}

Cancel Checkout

Endpoint

• Method: POST
• URL: /v1/customer/payments/checkout-cancel

Request Headers

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

Success Response

{
    "success": true,
    "message": "تم إلغاء الحجز بنجاح",
    "data": [],
    "statusCode": 200
}

Error Responses

Order Not Found (404)

{
    "success": false,
    "message": "لم يتم العثور على اي طلب",
    "data": [],
    "statusCode": 404
}

Appointment Not Found (422)

{
    "success": false,
    "message": "الموعد غير موجود",
    "data": [],
    "statusCode": 422
}

Important Notes

• All amounts are in Saudi Riyals (ر.س)
• Available payment methods:
  • Wallet (if balance is sufficient)
  • Credit Card
  • Apple Pay
• For credit card and Apple Pay payments, you'll receive a payment URL to redirect the user to
• Wallet payments are processed immediately
• Discounts can be applied or revoked during checkout
• The system automatically checks if the user has sufficient wallet balance for wallet payments
• Checkout cancellation will:
  • Release the booked appointment
  • Cancel any associated session requests
  • Revoke any applied discounts
  • Delete the order completely

Paytabs Payment Status

Check Payment Status

Endpoint

• Method: GET
• URL: /v1/customer/payments/check-paytabs-status/{id}

Request Headers

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

Path Parameters

Parameter	Type	Description	Required
id	string	Order ID	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح",
    "data": {
        "id": "uuid",
        "status": "PAID",
        "session_type": "SCHEDULED"
    },
    "statusCode": 200
}

Error Response

Order Not Found (404)

{
    "success": false,
    "message": "لم يتم العثور على اي طلب",
    "data": [],
    "statusCode": 404
}

Paytabs Callback

Endpoint

• Method: POST
• URL: /v1/customer/payments/paytabs-callback

Request Body

Parameter	Type	Description	Required
cart_id	string	Cart ID from Paytabs	Yes
tran_ref	string	Transaction reference from Paytabs	Yes

Success Response

{
    "success": true,
    "message": null,
    "data": null,
    "statusCode": 204
}

Important Notes

• The Paytabs callback endpoint is used internally by the payment gateway to notify the system about payment status changes
• The status check endpoint can be used to verify the current status of a Paytabs payment
• Payment statuses include:
  • PENDING_PAYMENT
  • PAID
  • FAILED
  • CANCELLED
• The callback endpoint processes the payment asynchronously through a queue job
• The session type in the response indicates whether the appointment is SCHEDULED or DIRECT