BORIS – Buy Online and Return In-Store

Flow

Perform Refund: Portal-app → Portal-Frontend-service → Transaction-service

Get Order details (Refund information, History): Portal-app → Portal-Frontend-service → Reporting-service

API (Existing refund APIs)

1. Accept Refund reason API

Refund Reason	URI
Refund on a capture transaction	{API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/captures/{captureRef}/refund
Refund on a purchase transaction	{API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/purchases/{purchaseId}/refund
Refund on a capture transaction for a Tabby transaction	{API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/tabby/captures/{captureId}/refund
Refund on a purchase transaction for a Tabby transaction	{API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/tabby/purchases/{purchaseId}/refund

Below Details are same for all the 4 APIs

METHOD: POST

Header	Value
Accept	application/vnd.ni-payment.v2+json
Content-Type	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

{
    "amount": {
        "currencyCode": "GBP",
        "value": 12392
    },
    "reason": "Not happy with the product"
}

Response Body:

{
    "reference": "76e318f3-4b08-483c-bdfb-c30bf7fa3a9d",
    "state": "CAPTURED",
    ...
    "_embedded": {
        "cnp:refund": [
            {
                "amount": {
                    "currencyCode": "GBP",
                    "value": 5
                },
                "createdTime": "2022-10-10T05:52:00.870Z",
                "state": "VOID"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/46bdcd64-f9a9-4068-8fbe-d78e83b72683/orders/6ba1996d-67d7-44fa-bb3c-5452703f71e3/payments/76e318f3-4b08-483c-bdfb-c30bf7fa3a9d/refund/1d2382ec-3664-42e6-babb-410deba77323"
                    }
                },
                "amount": {
                    "currencyCode": "GBP",
                    "value": 12
                },
                "reason": "Not happy with the product"
                "createdTime": "2023-05-25T08:38:33.753Z",
                "state": "SUCCESS"
            }
        ]
    }
}

2. To know the updated refund reason.

Any of the below existing APIs can be hit to know the refund reason.

2.1 GET Refund reason for a capture transaction

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/captures/{captureRef}/refund/{refundId}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

2.2 GET Refund reason for a purchase transaction

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/purchases/{purchaseId}/refund/{refundId}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

2.3 GET Refund reason for a Tabby capture

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/tabby/captures/{captureId}/refund/{refundId}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

2.4 GET Refund reason for a Tabby purchase

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}/tabby/purchases/{purchaseId}/refund/{refundId}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

RESPONSE BODY: For all of the above GET calls (Sample)

{
    "_links": {
        "self": {
            "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737/refund/2554d42d-43db-40c7-a4c1-4a664493f8f5"
        }
    },
    "amount": {
        "currencyCode": "AED",
        "value": 12
    },
    "reason": "Not happy",
    "createdTime": "2023-11-02T16:00:54.671Z",
    "state": "SUCCESS"
}

3. GET Order Details

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

RESPONSE BODY (Sample):

{
    "_id": "urn:order:80dfca8b-2fd6-4d85-bebd-448852512028",
    ...
    "_embedded": {
        "payment": [
            {
                "_id": "urn:payment:8698116d-2584-4d66-92ad-fd164a697737",
                "_links": {
                    "self": {
                        "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737"
                    },
                    "curies": [
                        {
                            "name": "cnp",
                            "href": "https://api-gateway-dev.ngenius-payments.com/docs/rels/{rel}",
                            "templated": true
                        }
                    ]
                },
                "reference": "8698116d-2584-4d66-92ad-fd164a697737",
                ...
                "state": "PARTIALLY_REFUNDED",
                "amount": {
                    "currencyCode": "AED",
                    "value": 150000
                },
                ...
                "_embedded": {
                    "cnp:capture": [
                        {
                            "_links": {
                                "cnp:refund": {
                                    "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737/captures/5e0bcfc9-6d62-49f2-8829-2cf00730ea07/refund"
                                }
                            },
                            "amount": {
                                "currencyCode": "AED",
                                "value": 150000
                            },
                            "createdTime": "2023-10-31T11:47:28.371Z",
                            "state": "SUCCESS"
                        }
                    ],
                    "cnp:refund": [
                        {
                            "_links": {
                                "self": {
                                    "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737/refund/2554d42d-43db-40c7-a4c1-4a664493f8f5"
                                }
                            },
                            "amount": {
                                "currencyCode": "AED",
                                "value": 12
                            },
                            "reason": "Not happy",
                            "createdTime": "2023-11-02T16:00:54.671Z",
                            "state": "SUCCESS"
                        }
                    ]
                }
            }
        ]
    }
}

4. GET Payment Details API

URI: {API-GATEWAY}/transactions/outlets/{outletRef}/orders/{orderRef}/payments/{paymentRef}

METHOD: GET

Header	Value
Accept	application/vnd.ni-payment.v2+json
Authorisation	Bearer {{token}}

RESPONSE BODY (Sample):

{
    "_id": "urn:payment:8698116d-2584-4d66-92ad-fd164a697737",
   ...
    "_embedded": {
        "cnp:capture": [
            {
                "_links": {
                    "cnp:refund": {
                        "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737/captures/5e0bcfc9-6d62-49f2-8829-2cf00730ea07/refund"
                    }
                },
                "amount": {
                    "currencyCode": "AED",
                    "value": 150000
                },
                "createdTime": "2023-10-31T11:47:28.371Z",
                "state": "SUCCESS"
            }
        ],
        "cnp:refund": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/935936e6-cf5c-4e06-b8d4-6a58a808ea5c/orders/80dfca8b-2fd6-4d85-bebd-448852512028/payments/8698116d-2584-4d66-92ad-fd164a697737/refund/2554d42d-43db-40c7-a4c1-4a664493f8f5"
                    }
                },
                "amount": {
                    "currencyCode": "AED",
                    "value": 12
                },
                "reason": "Not happy",
                "createdTime": "2023-11-02T16:00:54.671Z",
                "state": "SUCCESS"
            }
        ]
    }
}

Tech Details

GET Payment, GET order, and GET Refund API responses are updated with the refund reason in the _embedded block.

{
......
"_embedded": {
        "cnp:refund": [
            {
                "amount": {
                    "currencyCode": "GBP",
                    "value": 5
                },
                "createdTime": "2022-10-10T05:52:00.870Z",
                "state": "VOID"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-gateway-dev.ngenius-payments.com/transactions/outlets/46bdcd64-f9a9-4068-8fbe-d78e83b72683/orders/6ba1996d-67d7-44fa-bb3c-5452703f71e3/payments/76e318f3-4b08-483c-bdfb-c30bf7fa3a9d/refund/1d2382ec-3664-42e6-babb-410deba77323"
                    }
                },
                "amount": {
                    "currencyCode": "GBP",
                    "value": 12
                },
                "reason": "Not happy with the product"
                "createdTime": "2023-05-25T08:38:33.753Z",
                "state": "SUCCESS"
            }
        ]
    }
}

Add Validations - reason is optional field and if it is provided there would be length restriction.

Persist the refund reason in transaction service Mongo db as part of the Refund Event (OrderEventStream collection)

Publish the reason in the refund events
Sample Refund Event published from transaction-service

{
    "reference": "946c9439-a85f-4c76-9fe0-1f6ef8493c61",
    "amount": {
        "currencyCode": "AED",
        "value": 1200
    },
    "orderResource": "http://transaction-service/transactions/outlets/9dd13e0b-1aaa-4474-88cb-d4158daf72e3/orders/946c9439-a85f-4c76-9fe0-1f6ef8493c61",
    "tabbyRefundId": "e8625aa2-fff0-4410-adf2-b2c7e636aac1",
    "outletId": "9dd13e0b-1aaa-4474-88cb-d4158daf72e3",
    "paymentReference": "cbc1bb05-914e-4607-b938-a5ce852b88e0",
    "refund": "dd3afca2-7f41-4a54-9248-b4a27c9d8b0c",
    "reason": "Not happy with the product"
}

Reporting service will consume this event and save the information in reporting service Mongo db (Existing behavior).

Update Collection Status

If the payment is fully refunded and BORIS & Click and Collect proposition services are enabled, then update the collection status as Returned.