Order Recharges
This guide explains how to interact with the Order Recharge API in the Sumaya369 web application. The API provides endpoints for recharging orders using various payment methods.
Recharge Order with Credit Card
Recharge an existing order using credit card payment method.
Endpoint
- Method: POST
- URL:
/v1/customer/orders/{id}/recharge
Request Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/json | Yes |
| Accept | application/json | Yes |
| Authorization | Bearer token | Yes |
Success Response
{
"success": true,
"message": "Payment URL generated successfully.",
"data": {
"payment_url": "https://payment-gateway.com/checkout/xyz"
},
"status_code": 200
}
Recharge Order with Spotii
Recharge an existing order using Spotii payment method.
Endpoint
- Method: POST
- URL:
/v1/customer/orders/{id}/recharge/spotii
Request Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/json | Yes |
| Accept | application/json | Yes |
| Authorization | Bearer token | Yes |
Success Response
{
"success": true,
"message": "Spotii checkout URL generated successfully.",
"data": {
"checkout_url": "https://spotii.com/checkout/xyz"
},
"status_code": 200
}
Recharge Order with Tamara
Recharge an existing order using Tamara payment method.
Endpoint
- Method: POST
- URL:
/v1/customer/orders/{id}/tamara/checkout
Request Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/json | Yes |
| Accept | application/json | Yes |
| Authorization | Bearer token | Yes |
Success Response
{
"success": true,
"message": "تم جلب البيانات بنجاح.",
"data": {
"order_id": "5c4c4386-b72f-41f3-a5b8-9e276406f0f1",
"checkout_id": "1c790d02-5ea4-4d36-b8bd-99930c21a4ed",
"checkout_url": "https://checkout-sandbox.tamara.co/checkout/1c790d02-5ea4-4d36-b8bd-99930c21a4ed?locale=ar_SA&orderId=5c4c4386-b72f-41f3-a5b8-9e276406f0f1",
"status": "new"
},
"status_code": 200
}
Recharge Order with Tabby
Recharge an existing order using Tabby payment method.
Endpoint
- Method: POST
- URL:
/v1/customer/orders/{id}/recharge/tabby
Request Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/json | Yes |
| Accept | application/json | Yes |
| Authorization | Bearer token | Yes |
Success Response
{
"success": true,
"message": "تم جلب البيانات بنجاح.",
"data": {
"id": "28cb6256-9b9c-40db-9928-5d0c8ac37b04",
"warnings": null,
"configuration": {
"currency": "SAR",
"app_type": "one_click",
"new_customer": true,
"available_limit": null,
"min_limit": null,
"available_products": {
"installments": [
{
"downpayment": "40.25",
"downpayment_percent": "25",
"downpayment_increased_reason": null,
"amount_to_pay": "120.75",
"downpayment_total": "40.25",
"order_amount": "161.00",
"next_payment_date": "2022-11-18T00:00:00Z",
"installments": [
{
"due_date": "2022-11-18",
"amount": "40.25",
"principal": "40.25",
"service_fee": "0.00"
},
{
"due_date": "2022-12-18",
"amount": "40.25",
"principal": "40.25",
"service_fee": "0.00"
},
{
"due_date": "2023-01-18",
"amount": "40.25",
"principal": "40.25",
"service_fee": "0.00"
}
],
"pay_after_delivery": false,
"pay_per_installment": "40.25",
"web_url": "https://checkout.tabby.ai/?sessionId=28cb6256-9b9c-40db-9928-5d0c8ac37b04&apiKey=pk_test_32ab530b-c6bb-4731-851d-b46c02dc2082&product=installments&merchantCode=Sumaya",
"id": 54581,
"installments_count": 3,
"installment_period": "P1M",
"service_fee": "0.00"
}
]
},
"country": "SAU",
"expires_at": "2022-10-18T13:56:49Z",
"is_bank_card_required": false,
"blocked_until": null,
"hide_closing_icon": false,
"pos_provider": null,
"is_tokenized": false,
"products": {
"installments": {
"type": "installments",
"is_available": true,
"rejection_reason": null
}
}
},
"api_url": "https://tabby.ai/s/11ho9uw",
"token": null,
"flow": "web",
"payment": {
"id": "bb75fe9a-f9cb-432b-8756-4751ce3025f6",
"created_at": "2022-10-18T13:36:49Z",
"expires_at": "2022-10-18T13:56:49Z",
"test": true,
"is_expired": false,
"status": "CREATED",
"cancelable": false,
"currency": "SAR",
"amount": "161",
"description": "",
"buyer": {
"id": "",
"name": "بيتر النشاشيبي",
"email": "card.success@tabby.ai",
"phone": "+966500000001",
"dob": null
},
"product": {
"type": "",
"installments_count": 0,
"installment_period": "P0D"
},
"shipping_address": {
"city": "السعودية",
"address": "السعودية",
"zip": "1234"
},
"order": {
"reference_id": "b13a6430-4ee8-11ed-8db6-4d547e9f6809",
"updated_at": "0001-01-01T00:00:00Z",
"tax_amount": "21",
"shipping_amount": "0",
"discount_amount": "125",
"items": [
{
"reference_id": "ce186850-4d48-11ed-970c-91a70ebb26ff",
"title": "سول ديتوكس",
"description": "",
"quantity": 1,
"unit_price": "140",
"image_url": "",
"product_url": "https://sumaya-lms-backend-testing.s3.us-east-2.amazonaws.com/front-end/images/plsXZh3njeoQMsTU7MyMmVqKrt6GYxdfKNEfHN0c.jpg",
"category": "course"
}
]
},
"captures": [],
"refunds": [],
"buyer_history": {
"registered_since": "2022-06-27T09:00:35+03:00",
"loyalty_level": 0,
"wishlist_count": 0,
"is_social_networks_connected": null,
"is_phone_number_verified": null,
"is_email_verified": null
},
"order_history": [
{
"purchased_at": "2022-10-18T16:28:03+03:00",
"amount": "286",
"payment_method": "",
"status": "new",
"buyer": {
"name": "",
"email": "",
"phone": null,
"dob": null
},
"shipping_address": {
"city": "",
"address": "",
"zip": ""
},
"items": null
}
],
"meta": null
},
"status": "created",
"customer": {
"id": null,
"phone": "+966500000001",
"email": "card.success@tabby.ai"
},
"juicyscore": {
"session_id": "",
"referrer": "",
"time_zone": "",
"useragent": ""
},
"merchant_urls": {
"success": "https://your-store/success",
"cancel": "https://your-store/cancel",
"failure": "https://your-store/failure"
},
"product_type": null,
"lang": "ara",
"locale": "ar-SA",
"seon_session_id": null,
"merchant": {
"name": "Sumaya369",
"address": "a, a",
"logo": ""
},
"merchant_code": "",
"terms_accepted": false
},
"status_code": 200
}
Example Implementation Flow
- Recharge Order
- User selects payment method
- Application sends authenticated POST request to appropriate recharge endpoint
- Redirect user to payment gateway checkout URL
- Handle success/failure callback from payment gateway
Key Considerations
- Authentication is required for all recharge endpoints
- Order must exist and belong to the authenticated customer
- Payment method availability may vary by customer's location
- Handle payment gateway callbacks appropriately