Payment Gateway Callback

Handles payment gateway callbacks for both GET and POST requests. These endpoints are used in the configuration of payment gateways like PayPal, Stripe, Zarinpal, etc. and are not called directly by the user. (For example, when a user completes payment on the gateway site, the gateway redirects back to this endpoint with the payment status. Frontend applications should not call these endpoints directly.)

HTTP Request

GET METHOD

GET/api/shop/checkout/callback/:bill_pk

POST METHOD

POST/api/shop/checkout/callback/:bill_pk

Authorization

Authorization

• Required: No
• Permission: No (called by payment gateways). Public endpoint
• Authentication: None required (uses bill_pk for verification)

Parameter	Type	Required	Description
bill_pk	Integer	No	Bill/transaction ID

Request Parameters

Payment gateway specific parameters are passed in query string (GET) or request body (POST).

Example Requests

🐍 Python

1import requests
2
3# This endpoint is typically called by payment gateways
4# GET callback example:
5response = requests.get(
6  'http://www.example.com/api/shop/checkout/callback/123',
7  params={
8      'transaction_id': 'TXN-123456',
9      'status': 'success',
10      'amount': '5000'
11  }
12)
13
14# POST callback example:
15response = requests.post(
16  'http://www.example.com/api/shop/checkout/callback/123',
17  json={
18      'transaction_id': 'TXN-123456',
19      'status': 'success',
20      'amount': '5000'
21  }
22)

🌐 Curl

1# GET callback (typically from payment gateway redirect)
2curl "http://www.example.com/api/shop/checkout/callback/123?transaction_id=TXN-123456&status=success&amount=5000"
3
4# POST callback (webhook from payment gateway)
5curl -X POST "http://www.example.com/api/shop/checkout/callback/123" -H "Content-Type: application/json" -d '{
6  "transaction_id": "TXN-123456",
7  "status": "success",
8  "amount": "5000"
9}'

Response

The callback endpoint returns HTTP redirects to the web client:

Successful Payment:

• Redirects to: {web_client_successful_payment_url}?key={order_key}
• Order status: Updated to "PROCESSING"
• Cart: Deleted after successful payment
• Payment record: Created with transaction details

Failed Payment:

• Redirects to: {web_client_failed_payment_url}
• Order status: Updated to "FAILED"

Callback Processing Flow

1. Bill Retrieval: Fetches bill using bill_pk
2. Order Lookup: Gets associated order from bill extra data
3. Payment Method: Retrieves payment method from bill extra data
4. Verification: Calls payment method's verify function with callback data
5. Success Handling:
   • Deletes associated cart
   • Updates order status to "PROCESSING"
   • Creates payment record
   • Redirects to success URL with order key
6. Failure Handling:
   • Updates order status to "FAILED"
   • Redirects to failure URL