Confirming a mobility service that requires payment before confirmation and receiving a confirmed booking (Java)
In this use case, the user confirms a booking of a mobility service after making the payment and receives a confirmed booking
Code snippets
Client calls the BAP server to trigger confirm:
@PostMapping("/mobility/confirm_order")
public ResponseEntity confirmOrder(
@RequestHeader HttpHeaders headers,
@RequestBody ClientConfirmOrderRequest request) {
var response = bapApplicationService.confirmOrder(request, headers);
return ResponseEntity.ok(response);
}
BAP server generates the protocol request body
/*
Example Request JSON:
{
"context": {
"domain": "nic2004:60221",
"country": "IND",
"city": "std:080",
"action": "confirm",
"core_version": "0.9.1",
"bap_id": "https://mock_bap.com/",
"bap_uri": "https://mock_bap.com/beckn/",
"bpp_id": "https://mock_bpp.com/",
"bpp_uri": "https://mock_bpp.com/beckn/",
"transaction_id": "1209849124",
"message_id": "12341242345",
"timestamp": "2021-03-23T10:00:40.065Z"
},
"message": {
"order": {
"items":[
{
"id": "sedan_spot",
"quantity": {
"count": 1
}
},
],
"billing": {
"name": "John Doe",
"address": {
"door": "21A",
"name": "ABC Apartments",
"locality": "HSR Layout",
"city": "Bengaluru",
"state": "Karnataka",
"country": "India",
"area_code": "560102"
},
"email": "[email protected]",
"phone": "+919876543210"
},
"fulfillment": {
"tracking": true,
"start": {
"location": {
"id": "user-location",
"descriptor": {
"name": "Current user location"
},
"gps": "12.9349377,77.6055586"
},
"instructions": {
"name": "pick up instructions",
"short_desc": "Ask doorman to ring 21A"
},
"time": {
"label": "ETA",
"duration": "P12M"
},
"contact": {
"phone": "+919999999999",
"email": "[email protected]"
}
},
"end": {
"location": {
"gps": "12.914028, 77.638698"
}
}
},
"quote": {
"price": {
"currency": "INR",
"value": "180"
},
"breakup": [
{
"title": "Sedan Spot Booking",
"price": {
"currency": "INR",
"value": "170"
}
},
{
"title": "Service Charge",
"price": {
"currency": "INR",
"value": "10"
}
}
]
},
"payment": {
"uri": "https://api.bpp.com/pay?amt=$640&mode=upi&vpa=bpp@upi",
"tl_method": "http/get",
"params": {
"amount": "180",
"mode": "upi",
"vpa": "bpp@upi"
},
"type": "ON-ORDER",
"status": "PAID"
}
}
}
}
*/
public ClientResponse confirmOrder(ClientConfirmOrderRequest request, HttpHeaders headers) {
// Generate message id
var messageId = UUID.randomUUID().toString();
// Check if transaction id exists in the request.
// Generate if not exists
var txnId = StringUtils.hasText(request.getTransactionId())
? request.getTransactionId()
: UUID.randomUUID().toString();
// Construct the Context based on the request parameters
var context = Context.builder().domain(request.getDomain())
.action(Context.ActionEnum.confirm)
.messageId(messageId)
.transactionId(txnId)
.transactionId(UUID.randomUUID().toString())
.timestamp(new Date().toString())
.build();
// Construct the protocol specific object to be passed to the BPP
// to confirm the order for the selected items with payment details
var items = ClientAssembler.of(request.getItems());
var billing = ClientAssembler.of(request.getBilling());
var fulfilmentDetails = ClientAssembler.of(request.getFulfilment());
var quotation = ClientAssembler.of(request.getQuote());
var payment = ClientAssembler.of(request.getPayment());
var confirmOrderRequest = ConfirmRequest.builder()
.context(context)
.message(Message.builder().order(Order.builder()
.billing(billing)
.items(items)
.quote(quotation)
.payment(payment)
.build()).build())
.build();
return invokeConfirm(confirmOrderRequest, headers);
}
}
BAP server calls protocol confirm to the network
public Response invokeConfirm(ConfirmRequest request, HttpHeaders headers) {
// Call to look up function which returns the the public key and BPP Endpoint to be called
var url = lookUp(headers);
// Call BPP Confirm api from the returned endpoint.
// Construct request headers with the public key
var responseEntity = apiClient.post(url[0] + Context.ActionEnum.confirm,
constructRequestHeaders(),
request,
Response.class);
// Validate the received response
if (responseEntity.getBody() == null || responseEntity.getBody().getError() != null ||
"NACK".equals(responseEntity.getBody().getMessage().getAck().getStatus())) {
// Return custom error to the client
return null;
}
return Response.of("ACK", null);
}
BAP receives protocol on_confirm
/*
Example Response JSON:
{
"context": {
"domain": "nic2004:60221",
"country": "IND",
"city": "std:080",
"action": "on_confirm",
"core_version": "0.9.1",
"bap_id": "https://mock_bap.com/",
"bap_uri": "https://mock_bap.com/beckn/",
"bpp_id": "https://mock_bpp.com/",
"bpp_uri": "https://mock_bpp.com/beckn/",
"transaction_id": "1209849124",
"message_id": "12341242345",
"timestamp": "2021-03-23T10:00:40.065Z"
},
"message": {
"order": {
"id":"trip_1",
"state":"Driver en route",
"items":[
{
"id": "sedan_spot",
"quantity": {
"count": 1
}
}
],
"billing": {
"name": "John Doe",
"address": {
"door": "21A",
"name": "ABC Apartments",
"locality": "HSR Layout",
"city": "Bengaluru",
"state": "Karnataka",
"country": "India",
"area_code": "560102"
},
"email": "[email protected]",
"phone": "+919876543210"
},
"fulfillment": {
"tracking": true,
"start": {
"location": {
"id": "user-location",
"descriptor": {
"name": "Current user location"
},
"gps": "12.9349377,77.6055586"
},
"instructions": {
"name": "pick up instructions",
"short_desc": "Ask doorman to ring 21A"
},
"time": {
"label": "ETA",
"duration": "P12M"
},
"contact": {
"phone": "+919999999999",
"email": "[email protected]"
}
},
"end": {
"location": {
"gps": "12.914028, 77.638698"
}
}
},
"quote": {
"price": {
"currency": "INR",
"value": "180"
},
"breakup": [
{
"title": "Sedan Spot Booking",
"price": {
"currency": "INR",
"value": "170"
}
},
{
"title": "Service Charge",
"price": {
"currency": "INR",
"value": "10"
}
}
]
},
"payment": {
"uri": "https://api.bpp.com/pay?amt=$180&mode=upi&vpa=bpp@upi",
"tl_method": "http/get",
"params": {
"amount": "180",
"mode": "upi",
"vpa": "bpp@upi"
},
"type": "ON-ORDER",
"status": "PAID"
}
}
}
}
*/
@PostMapping("/bap/on_confirm")
public ResponseEntity onConfirm(
@RequestHeader HttpHeaders headers,
@RequestBody OnConfirmRequest request) {
var response = bapCallbackApplicationService.onConfirm(request, headers);
return ResponseEntity.ok(response);
}
public Response onConfirm(OnConfirmRequest request, HttpHeaders headers) {
// Validate the headers received
var isHeadersValid = validateHeaders(headers);
// Construct and return error if the received headers are invalid
if (!isHeadersValid) return null;
// Store the data received based on message id for the client to poll
saveToDB(request);
return Response.of("ACK", null);
}
Client polls BAP to get the on_confirm results
// Endpoint for the client to poll the confirmed order based on the message id
@GetMapping("/mobility/on_confirm")
public ResponseEntity onConfirm(
@PathVariable(ClientRoutes.PARAM_MESSAGE_ID) String messageId,
@RequestHeader HttpHeaders headers) {
var data = bapApplicationService.get(messageId);
return ResponseEntity.ok(data);
}