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.