Bkash Documentation

Type: Technical
Developer: Md. Sagar Ali

Summary: This Bkash integration provides three main APIs: Beneficiary Validation, Remit
Transfer, and Remit Status Check. Each endpoint reads the incoming data, saves it to a
specified file location, deserializes it into a model, and saves it to the database via the
corresponding method. Each operation logs success or failure, returning a structured
success response or an error code if it fails. These APIs enable efficient tracking and
management of Bkash transaction statuses, validation, and transfers within the system.

API Documentation Summary for Bkash Integration

1. Bkash Beneficiary Validation
Endpoint: POST /bkashBeneficiaryValidation
Flow:
• Reads the request body (beneficiary validation data).
• Saves the raw data to a file at _appConfig.BkashValidateFilelocation.
• Deserializes the request into ValidationResultModel.
• Saves the validation data via _bkashService.SaveValidation().
Success Response:
{
"responseCode": 200,
"responseDescription": "Success",
"conversionID": "123456",
"countryCode": "BD",
"msisdn": "017xxxxxxxx",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe"
}
2. Bkash Remit Transfer
Endpoint: POST /bkashRemitTransfer
Flow:
• Reads the request body (remit transfer data).
• Saves the raw data to a file at _appConfig.BkashRemitTransferFilelocation.
• Deserializes the request into RemitResultModel.
• Saves the transfer data via _bkashService.SaveTransfer().

Success Response:

1|Pa ge
 {

"responseCode": 200,

"responseDescription": "Success",

"conversionID": "123456",

"txnId": "TXN123456",

"approvalCode": "APRV123",

"processedTimestamp": "2024-10-24T12:34:56Z"

3. Bkash Remit Status Check

Endpoint: POST /bkashRemitStatusCheck

Flow:

• Reads the request body (remit status data).

• Saves the raw data to a file at _appConfig.BkashRemitStatusFilelocation.
• Deserializes the request into StatusQueryResultModel.
• Saves the status data via _bkashService.SaveStatus().

Success Response:

"responseCode": 200,

"responseDescription": "Success",

"conversionID": "123456",

"txnId": "TXN123456",

"approvalCode": "APRV123",

"processedTimestamp": "2024-10-24T12:34:56Z"

Error Response (for all endpoints):

"responseCode": 500,

"responseDescription": "Failed"

2|Pa ge
 }

# SaveValidation, SaveTransfer, SaveStatus Methods Summary

1. SaveValidation

• Purpose: Saves validation result from Bkash to the database.

• Stored Procedure: InsertBKValidatonResponse
• Key Parameters:

I. @ConversationID: from TransactionInfo.ConversationID.

II. @ResponseDetail: entire notificationData.

• Return:

I. true if @ResultStatus = 1 (success).

II. false otherwise.

2. SaveTransfer

1) Purpose: Saves remit transfer result to the database.

2) Stored Procedure: InsertBKTransferResponse
3) Key Parameters:
• @ResponseCode, @TxnId, @DateTime, @Time, @ApprovalCode, @ResponseDescription,
@ResponseDetail.
4) Return:

I. true if @ResultStatus = 1 (success).

II. false otherwise.

3. SaveStatus

• Purpose: Saves remit status result to the database.

• Stored Procedure: InsertBKStatusResponse
• Key Parameters:

• @ConversationID, @ResponseCode, @TxnId, @ResponseDetail.

• Return:

I. true if @ResultStatus = 1 (success).

II. false otherwise.

Each method:

• Starts a transaction.
• Calls a stored procedure.
• Logs the result.
• Commits or rolls back the transaction based on success or failure.

3|Pa ge
Bkash Internal Call Methods Summary

1. CreateBkashValidate (POST: /bkashValidateBeneficiaryInternal)

• Purpose: Validates the beneficiary with Bkash.

• Key Steps:

I. Converts the model into a JSON string.

II. Sends a POST request to the Bkash Validate Beneficiary endpoint
(BkashSettings:ValidateBeneficiary).
III. Adds interface_id from the configuration in headers.
IV. Returns validation results based on Bkash's response, handling success and failure cases
(e.g., 400 Bad Request, 401 Unauthorized, etc.).

2. BkashRemitTransferInternal (POST: /bkashRemitTransferInternal)

• Purpose: Processes a Bkash remit transfer request.

• Key Steps:

I. Logs the conversationID from the request model.

II. Sends a POST request to the Bkash Remit Transfer endpoint
(BkashSettings:bkashRemitTransfer).
III. Adds interface_id from the configuration in headers.
IV. Handles and logs response, including success and various HTTP error codes.

3.BkashRemitTransferInternalWithResponse(POST:/bkashRemitTransferInternalWithResponse)

• Purpose: Processes a Bkash remit transfer request and performs additional checks based on the
response.
• Key Steps:
▪ Similar to the previous method but includes additional logic for processing the
response based on the response code (3050 in this case).
▪ Calls a service method (CheckTransferRespone) to further process the
transaction based on conversationID.

1. BkashRemitStatusCheckInternal (POST: /bkashRemitStatusCheckInternal)

• Purpose: Checks the status of a Bkash remit transfer.

• Key Steps:

I. Logs the action call initiation.

II. Retrieves the conversationID using the txnId if not provided in the request body.
III. Sends a POST request to Bkash's Remit Status Check endpoint
(BkashSettings:BkashRemitStatus) if both conversationID and txnId are valid.
IV. Adds interface_id from the configuration in headers.
V. Handles Bkash's response and returns the result. If the ResponseCode is "0000," further
status response is fetched using _bkashService.CheckStatusRespone(conversationID).
VI. Handles various HTTP status codes and returns appropriate responses.

4|Pa ge
2. CheckbkashRemitResultCallbackInternal (POST: /CheckbkashRemitResultCallbackInternal)

• Purpose: Checks the result of a Bkash remit transfer using the transaction ID.
• Key Steps:

I. Calls the _bkashService.CheckTransferResponeWithTnxId(model.TxnId) service method to

retrieve the response based on the transaction ID.
II. Handles exceptions and logs errors if any occur during the process.
III. Returns the result or an error if the process fails.

Each method handles its respective functionality by:

• Sending HTTP requests to Bkash API endpoints.

• Logging information during the process.
• Handling responses based on status codes or specific response codes.

Bkash Service Methods Summary

1. CheckvalidateRespone

• Purpose: Fetches and returns the validation response for a Bkash transaction using the conversation
ID.
• Key Steps:

I. Executes a SQL query on the BKResponseHistories table to retrieve the validation response
(ResponseType = 1) for the given ConversationID.
II. If a valid response is found, deserializes the response into a ValidationResultModel and
returns it.
III. Implements retry logic with a delay between retries (up to 15 retries).

2. CheckTransferRespone

• Purpose: Fetches and returns the transfer response for a Bkash transaction using the conversation
ID.
• Key Steps:

I. Executes a SQL query on the BKResponseHistories table to retrieve the transfer response
(ResponseType = 2) for the given ConversationID.
II. If a valid response is found, deserializes the response into a RemitResultModel and returns
it.
III. Implements retry logic with a delay between retries (up to 15 retries).

5|Pa ge
3. CheckTransferResponeWithTnxId

• Purpose: Fetches and returns the transfer response for a Bkash transaction using the transaction ID.
• Key Steps:

I. Executes a SQL query on the BKResponseHistories table to retrieve the transfer response
(ResponseType = 2) for the given TxnId.
II. If a valid response is found, deserializes the response into a RemitResultModel and returns
it.

4. CheckStatusRespone

• Purpose: Fetches and returns the status query response for a Bkash transaction using the
conversation ID.
• Key Steps:

I. Executes a SQL query on the BKResponseHistories table to retrieve the status response
(ResponseType = 3) for the given ConversationID.
II. Ensures the response has not been marked as read (IsRead = 0).
III. Implements retry logic with a delay between retries (up to 15 retries).
IV. If a valid response is found, deserializes the response into a StatusQueryResultModel.

5. GetCnversionId

• Purpose: Fetches and returns the conversation ID for a given transaction ID.
• Key Steps:

I. Executes the stored procedure GetBKConversationID using the transaction ID (TxnId) as a

parameter.
II. If a valid ConversationID is found, returns it.

BKResponseHistories Table Overview

• Table: BKResponseHistories
• Purpose: Logs Bkash transaction responses.

Columns

1. HistoryId (int, PK) - Unique, auto-increment ID.

2. TTOf (smallint) - Transaction type.
3. ConversationID (nvarchar(50)) - Unique conversation ID.
4. TxnId (nvarchar(50), Nullable) - Transaction ID.
5. ResponseDetail (nvarchar(max)) - Serialized response data.
6. ResponseType (smallint) - Type of response (e.g., validation, status).

6|Pa ge
 7. IsRead (smallint, Nullable) - Processed status.
8. ResponseTime (datetime) - Timestamp of response.

Stored Procedures Summary

1. [GetBKConversationID]

Purpose: Retrieves ConversationID for a given TxnId and marks it as read.

Parameters:

▪ @TxnId (Input) - Transaction ID.

Operations:

▪ Selects ConversationID from BKResponseHistories where ResponseType is 2.

▪ Updates IsRead to 1 for the provided TxnId.

2. [InsertBKStatusResponse]

Purpose: Inserts status response details for a transaction.

Parameters:

▪ @ConversationID, @TxnId, @ResponseCode, @ResponseDetail (Input).

▪ @ResultStatus (Output) - Success or failure status.

Operations:

▪ Inserts data into BKResponseHistories with ResponseType set to 3.

3. [InsertBKTransferResponse]

Purpose: Inserts transfer response details.

Parameters:

▪ @ConversationID, @TxnId, @ResponseCode, @ResponseDetail, @DateTime,

@Time, @ApprovalCode, @ResponseDescription (Input).
▪ @ResultStatus (Output) - Success or failure status.

Operations:

▪ Inserts data with ResponseType set to 2.

7|Pa ge
 4. [InsertBKValidatonResponse]

Purpose: Inserts validation response details.

Parameters:

▪ @ConversationID, @ResponseDetail (Input).

▪ @ResultStatus (Output) - Success or failure status.

Operations:

▪ Inserts data with ResponseType set to 1.

Each stored procedure performs specific data handling tasks, including retrieval or insertion into
BKResponseHistories with appropriate response types and error handling.

8|Pa ge