Skip to main content

​
Overview

Allows store employees to verify UPI payments and update the payment status of an order. This is a critical step in the order lifecycle where the store confirms they received payment before accepting the order. When payment status is updated to success, the order automatically transitions to accepted status and the customer receives a notification.

​
Authentication

Requires authentication with JWT token. Only available to store_employee role.

​
Endpoint

PATCH /api/orders/:id/payment-status

​
Path parameters

​
id
string
required
The unique order ID (MongoDB ObjectId)

​
Request body

​
paymentStatus
string
required
The updated payment statusValid values: pending, success, failed
​
transactionId
string
The UPI transaction ID verified by the store (8-40 alphanumeric characters). Will be converted to uppercase.

​
Response

​
success
boolean
Indicates if the payment status was updated successfully
​
message
string
Human-readable status message
​
data
object

​
Payment verification flow

  1. Customer completes UPI payment to store’s UPI ID
  2. Customer submits order with optional transaction ID
  3. Store checks their UPI payment history
  4. Store verifies payment amount matches totalAmount
  5. Store calls this endpoint to mark payment as success
  6. Order automatically transitions to accepted status
  7. Customer receives email and push notification
If payment status is set to failed, the order is automatically cancelled with cancellation reason payment_failed.

​
Example request

curl -X PATCH https://api.campusbite.com/api/orders/65f7a8b9c1234567890abcde/payment-status \
  -H "Authorization: Bearer STORE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentStatus": "success",
    "transactionId": "UPI12345678"
  }'

​
Example response

{
  "success": true,
  "message": "Payment confirmed. Waiting for customer commitment before preparation.",
  "data": {
    "order": {
      "id": "65f7a8b9c1234567890abcde",
      "orderNumber": "ORD-20240318-001",
      "paymentReference": "CBPAY1A2B3C4D5E",
      "orderStatus": "placed",
      "paymentStatus": "success",
      "paymentMethod": "direct_store_upi",
      "transactionId": "UPI12345678",
      "totalAmount": 249.50,
      "items": [
        {
          "menuItemId": "65f7a8b9c1234567890abcdf",
          "name": "Paneer Burger",
          "price": 120,
          "quantity": 1,
          "total": 120
        },
        {
          "menuItemId": "65f7a8b9c1234567890abce0",
          "name": "French Fries",
          "price": 80,
          "quantity": 1,
          "total": 80
        }
      ],
      "isCommitmentConfirmed": false,
      "commitmentDeadlineAt": "2024-03-18T14:34:00.000Z",
      "customer": {
        "id": "65f7a8b9c1234567890abce6",
        "name": "Rahul Sharma",
        "email": "[email protected]",
        "phoneNumber": "+919876543210",
        "registerNumber": "21CS001",
        "noShowCount": 1,
        "trustTier": "good"
      },
      "store": {
        "id": "65f7a8b9c1234567890abce2",
        "name": "Campus Cafe"
      },
      "createdAt": "2024-03-18T14:30:00.000Z",
      "updatedAt": "2024-03-18T14:31:00.000Z"
    }
  }
}

​
Error responses

​
Commitment requirement

After payment is confirmed, customers with a no-show history must confirm their commitment before the store can accept the order: The response message indicates if commitment is still needed.
Transaction IDs are automatically converted to uppercase and validated to be 8-40 alphanumeric characters. Duplicate transaction IDs across different orders are not allowed.

​
Automatic cancellation

Orders with pending payment status are automatically cancelled if:
  • Payment not verified within 8 minutes of order creation
  • Store marks payment status as failed

Build docs developers (and LLMs) love

Get started for freeTalk to us