Order Checkout

Processes payment for an existing unpaid order.

HTTP Request

POST/api/shop/checkout/order/:key

Authorization

Authorization

• Required: No
• Permission: Order key access or Authenticated users
• Authentication: None required (uses order key for access) or Token-based authentication

Query Parameters

Parameter	Type	Default	Description
key	String	—	Order tracking key

Request Body

Field	Type	Required	Description
payment_method	Integer	Yes	Active payment method ID

Example Requests

🐍 Python

1import requests
2
3# Checkout existing order
4response = requests.post('http://www.example.com/api/shop/checkout/order/ORD-2024-001', 
5  json={
6      'payment_method': 1
7  }
8)
9print(response.json())
10
11# Example responses:
12# For redirect-based payments:
13{
14  "next_step": "https://payment-gateway.com/pay?token=xyz789"
15}
16
17# For direct payments:
18{
19  "order_key": "ORD-2024-001"
20}

🌐 Curl

1# Checkout existing order
2curl -X POST "http://www.example.com/api/shop/checkout/order/ORD-2024-001" -H "Content-Type: application/json" -d '{
3  "payment_method": 1
4}'

Status Codes

Code	Description
200	Order successful
400	Bad request — validation errors
404	Order not found
503	Service unavailable — payment service error
500	Internal server error

Response Fields

Success Response (Direct Payment):

Field	Type	Description
order_key	String	Order tracking key for the new order

Success Response (Redirect Payment):

Field	Type	Description
next_step	String	URL to redirect user for payment

Error Response:

Field	Type	Description
error	String	Error message

Payable Order Statuses

An order is considered payable only when it has one of the following statuses:

• hold - Order is on hold awaiting payment
• processing - Order is being processed and can accept payment
• shipped - Order has been shipped but payment may still be pending

Response Scenarios

Success Response (Order is Payable)

When the order status is hold, processing, or shipped:

Status Code: 200 OK

{
  "order_key": "ABCDEFG12345"
}

Error Response (Order is Not Payable)

When the order status is new, failed, cancelled, completed, refunded, or deleted:

Status Code: 400 Bad Request

{
  "non_field_errors": [
    "Order is not payable."
  ]
}

Validation Rules

• Order Status: Order must not be fully paid
• Payment Method: Must be active and support the order
• Outstanding Amount: Payment processes the remaining unpaid amount
• Order Key: Must be valid and accessible by the user

Checkout Process Flow

1. Order Retrieval: Fetches order using the provided key
2. Payment Method Validation: Checks if the payment method is active and compatible with the order
3. Payment Processing:
   • For redirect payments: Returns next_step URL for external gateway (For example PayPal, Stripe, Zarinpal, etc.)
     • User must complete payment on the gateway site
     • After payment, user is redirected back to the site with order key
   • For direct payments: Processes immediately and returns order_key (For example pay on delivery)
4. Order Status Update:
   • Updates order status to "PROCESSING" after successful payment
   • Creates payment record with transaction details
5. Cart Cleanup: Deletes associated cart after successful payment

Frontend Developer Notes

Important Implementation Points:

1. Status Code Handling: Always check the HTTP status code first

   • 200 = Order can proceed to payment
   • 400 = Order cannot be paid (show error message)
   • 404 = Order not found with this key

2. Response Structure:

   • Success responses contain only the order_key field
   • Error responses contain non_field_errors array with error messages

3. Error Handling: When receiving a 400 error, display the error message from non_field_errors[0] to the user

4. User Experience:

   • If order is not payable, inform the user that payment is not available for this order
   • Consider redirecting to order tracking page to show current status
   • For completed orders, show "Order already completed" message
   • For cancelled/failed orders, suggest contacting support