Reward Redemption API Documentation

graph TB
    subgraph Client["Client System (Source of Truth)"]
        CS[Client Server]
        CDB[(Client Database
Points Master)]
    end
    
    subgraph BigCity["BigCity Platform"]
        Portal[Redemption Portal
Web/Mobile]
        BCAPI[BigCity API Server]
        BCDB[(BigCity Database
Orders & Catalog)]
    end
    
    subgraph Vendor["Vendor Systems"]
        V1[Vendor 1
E-Gift Cards]
        V2[Vendor 2
Physical Products]
        V3[Vendor 3
Services]
    end
    
    User[Customer] -->|1. Redirect with Token| Portal
    Portal -->|2. Validate Token| CS
    CS -->|3. Profile + Points| Portal
    Portal -->|4. Browse Catalog| BCAPI
    Portal -->|5. Place Order| BCAPI
    BCAPI -->|6. Deduct Points| CS
    CS -->|7. Confirm Deduction| BCAPI
    BCAPI -->|8. Fulfill Order| V1
    BCAPI -->|8. Fulfill Order| V2
    BCAPI -->|8. Fulfill Order| V3
    V1 -->|9. Voucher/Product| BCAPI
    BCAPI -->|10. Update Status| CS
    CS -->|11. Points Reversal
if Rejected| CDB
    BCAPI -->|12. Voucher Details| CS
    CS -->|13. SMS/WhatsApp| User
    
    CS -.->|Points Balance| CDB
    BCAPI -.->|Store Orders| BCDB
    
    style Client fill:#e3f2fd
    style BigCity fill:#fff3e0
    style Vendor fill:#f3e5f5
    style User fill:#c8e6c9
                    

sequenceDiagram
    autonumber
    participant Customer
    participant ClientApp as Client App
    participant ClientAPI as Client API
    participant Portal as BigCity Portal
    participant BigCityAPI as BigCity API
    participant Vendor
    
    Note over Customer,Vendor: Payment & Points Credit Flow
    Customer->>ClientApp: Makes Digital Payment
    ClientApp->>ClientAPI: Trigger Payment Event
    ClientAPI->>BigCityAPI: Credit Points API
    BigCityAPI-->>ClientAPI: Points Credited
    ClientAPI-->>Customer: Payment Confirmed
    
    Note over Customer,Vendor: Redemption Flow
    Customer->>ClientApp: Opens Reward Portal
    ClientApp->>Portal: Redirect (token, uid)
    Portal->>ClientAPI: POST /getProfileAndPoints?uid=
    ClientAPI-->>Portal: Profile + Points Data
    Portal-->>Customer: Display Catalog
    
    Note over Customer,Vendor: Order Placement Flow
    Customer->>Portal: Select Product & Place Order
    Portal->>BigCityAPI: Create Order
    BigCityAPI->>ClientAPI: POST /saveRedeemDetails
    ClientAPI->>ClientAPI: Validate & Deduct Points
    ClientAPI-->>BigCityAPI: Success (200)
    BigCityAPI-->>Portal: Order Confirmed
    Portal-->>Customer: Order Confirmation
    
    Note over Customer,Vendor: Fulfillment Flow
    BigCityAPI->>Vendor: Fulfill Order
    Vendor-->>BigCityAPI: Voucher/Product Details
    BigCityAPI->>ClientAPI: POST /updateRedeemStatus (Delivered)
    ClientAPI-->>BigCityAPI: Status Updated (200)
    
    Note over Customer,Vendor: Voucher Delivery Flow
    ClientAPI->>ClientAPI: GET /getwalletdetail?uid=
    ClientAPI->>ClientAPI: SMS/WhatsApp Gateway
    ClientAPI-->>Customer: Voucher via SMS/WhatsApp
    
    Note over Customer,Vendor: Failure & Reversal Flow
    alt Order Rejected
        Vendor-->>BigCityAPI: Order Failed
        BigCityAPI->>ClientAPI: POST /updateRedeemStatus (Rejected)
        ClientAPI->>ClientAPI: Reverse Points
        ClientAPI-->>BigCityAPI: Status Updated (200)
    end
                    

flowchart TD
    Start([Customer Action]) --> Payment{Digital Payment?}
    
    Payment -->|Yes| CalcPoints[Calculate Reward Points]
    CalcPoints --> CreditAPI[Credit Points API Call]
    CreditAPI --> UpdateBalance[(Update Points Balance
in Client DB)]
    UpdateBalance --> Earned[Points Earned ✓]
    
    Payment -->|No| Portal[Open Redemption Portal]
    Earned --> Portal
    
    Portal --> Validate[Validate Token & Fetch
Profile + Points]
    Validate --> ShowCatalog[Display Reward Catalog]
    
    ShowCatalog --> CustomerSelect{Customer
Selects Product?}
    CustomerSelect -->|No| End1([Exit])
    CustomerSelect -->|Yes| CheckBalance{Sufficient
Balance?}
    
    CheckBalance -->|No| InsufficientMsg[Show Insufficient Balance]
    InsufficientMsg --> End1
    
    CheckBalance -->|Yes| PlaceOrder[Place Order]
    PlaceOrder --> SaveRedeem[saveRedeemDetails API]
    SaveRedeem --> DeductPoints[Deduct Points from Balance]
    DeductPoints --> OrderPending[Order Status: Pending]
    
    OrderPending --> ProcessOrder[BigCity Processes Order]
    ProcessOrder --> VendorFulfill{Vendor
Fulfillment}
    
    VendorFulfill -->|Success| Delivered[Status: Delivered]
    Delivered --> NotifyCustomer[Send Voucher via
SMS/WhatsApp]
    NotifyCustomer --> Complete[Points Deducted ✓]
    Complete --> End2([Transaction Complete])
    
    VendorFulfill -->|Failed| Rejected[Status: Rejected]
    Rejected --> ReversePoints[Reverse Points
Credit Back to Customer]
    ReversePoints --> LogReversal[(Log Reversal
in Client DB)]
    LogReversal --> NotifyFail[Notify Customer
Order Failed]
    NotifyFail --> PointsRestored[Points Restored ✓]
    PointsRestored --> End3([Transaction Reversed])
    
    style Start fill:#c8e6c9
    style Payment fill:#fff9c4
    style Earned fill:#81c784
    style Complete fill:#81c784
    style PointsRestored fill:#81c784
    style Rejected fill:#ef5350
    style ReversePoints fill:#ffb74d
    style End2 fill:#66bb6a
    style End3 fill:#ffa726