Click and Collect

Update Collection Status API

Note - {API-GATEWAY} base URL changes for every tenant, for the NI tenant in production it is https://api-gateway.ngenius-payments.com

URL: /transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/collection-status

Method: POST

Headers: Add these headers to your request

Request Body:

{
  "collectionStatus": "COLLECTED"
}

Response Body:

{
  "collectionStatus" : "COLLECTED",
  "timestamp" : "2023-06-06T12:25:00.961Z"
}

GET Collection Status Using Order Details API

URL: {API-GATEWAY}/reporting/outlets/{outletRef}/orders/{orderRef}

Method: GET

Headers: Add these headers to your request

Response Body:

Sample response shown below, _embedded.events has events sorted based on timestamp. Find the collectionStatus in event payload of latest COLLECTION_STATUS_UPDATED event.

{
    "reference": "1a286f02-6e37-421f-aa81-85791837b588",
    "action": "SALE",
    "language": "en",
    "amount": {
        "currencyCode": "AED",
        "value": 10500,
        "formattedValue": "AED105.00"
    },
   ...
    "captureStatus": "CAPTURED",
    "_embedded": {
        "events": [
            {
                "metaData": {},
                "eventGroupType": "COLLECTION_STATUS",
                "eventName": "COLLECTION_STATUS_UPDATED",
                "status": "SUCCESS",
                "timestamp": "2023-11-02T15:43:00.242Z",
                "payload": {
                    "reference": "1a286f02-6e37-421f-aa81-85791837b588",
                    "orderResource": "http://transaction-service/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/1a286f02-6e37-421f-aa81-85791837b588",
                    "collectionStatus": "COLLECTED",
                    "outletId": "935936e6-cf5c-4e06-b8d4-6a58a808ea5c",
                    "paymentReference": "bfc72564-032a-474e-ab69-43229fd5a500",
                    "orderStatus": "CLOSE",
                    "userName": "Arjun A",
                    "userRole": "MERCHANT_ADMIN"
                },
                "outletId": "935936e6-cf5c-4e06-b8d4-6a58a808ea5c",
                "outletName": "Casterly Rock",
                "reversedAmountValue": 0
            },
            {
                "metaData": {},
                "eventGroupType": "CAPTURE",
                "eventName": "CAPTURED",
                "status": "SUCCESS",
                "timestamp": "2023-11-02T13:50:54.531Z",
                "payload": {
                    "reference": "1a286f02-6e37-421f-aa81-85791837b588",
                    "amount": {
                        "currencyCode": "AED",
                        "value": 10500
                    },
                    "orderResource": "http://transaction-service/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/1a286f02-6e37-421f-aa81-85791837b588",
                    "outletId": "935936e6-cf5c-4e06-b8d4-6a58a808ea5c",
                    "paymentReference": "bfc72564-032a-474e-ab69-43229fd5a500",
                    "capture": "98ca9d9d-e56d-4080-bdbb-5e237647a1dd",
                    "orderStatus": "CLOSE",
                    "paymentProcessor": "NETWORK_INTERNATIONAL"
                },
                "outletId": "935936e6-cf5c-4e06-b8d4-6a58a808ea5c",
                "outletName": "Casterly Rock",
                "settleAt": 1698908130000,
                "reversedAmountValue": 0,
                "action": "VOID_CAPTURE"
            },
            ...
            {
                "metaData": {},
                "eventGroupType": "Order Created",
                "eventName": "ORDER_CREATED",
                "status": "Initiated",
                "timestamp": "2023-11-02T13:50:32.468Z",
                "payload": {
                    "amount": {
                        "currencyCode": "AED",
                        "value": 10500,
                        "formattedValue": "د.إ.‏ 105"
                    }
                },
                "reversedAmountValue": 0
            }
        ]
    },
    "_id": "urn:order:1a286f02-6e37-421f-aa81-85791837b588"
}

More details on backend implementation

Transaction service validates whether payment is in the captured state then it will allow the user to update the collection status else throws a business validation error.

Transaction service publishes an event called COLLECTION_STATUS_UPDATED with data paymentReference, orderReference, createdDateTime , collectionStatus.

Reporting service consumes this event.
Also, enhance reporting service order details API response to include collection-status information.

Add collection status as part of Portal-frontend-service Get order details API response.

Add a field called collection-status-editable to the API response, which allows the user to mark it as collected only when payment is in CAPTURED or PURCHASED state from the UI.

Show the Delivery check box only when the user has permission and click-and-collect proposition is enabled.
Allow user to update status only when a collection-status-editable field is true