Debit Mobikwik Balance API

This API allows merchants to debit a specified amount from a user's Mobikwik wallet for transaction processing.

Environment

Environment	URL
Test	`https://test.mobikwik.com/debitwallet`
Production	`https://walletapi.mobikwik.com/debitwallet`

Method: GET

Request parameters

Parameter	Description	Example
mid `mandatory`	`String` Unique parent merchant ID	`MBK9006`
cell `mandatory`	`String` Mobile number of the user	`9311032820`
amount `mandatory`	`Decimal` Amount to be debited from wallet	`150.50`
orderid `mandatory`	`String` Unique order identifier	`ORDER_123456`
token `mandatory`	`String` Valid wallet token for the user	`MBK_TOKEN_123456789`
merchantname `mandatory`	`String` Alias for the merchant	`TestMerchant`
msgcode `mandatory`	`String` Message code	`504`
comment `optional`	`String` Transaction description/comment	`Payment for order`
txntype `mandatory`	`String` Transaction type	`DEBIT`
checksum `mandatory`	`String` Calculated checksum for validation	`calculated_hash`
aggregatedMerchantId `optional`	`String` Unique ID for aggregated merchants (For Aggregators Only)	`AGG123`
couponcode `optional`	`String` Coupon code for cashback	`SAVE20`

📘 Important: Ensure the token is valid and the user has sufficient balance before initiating the debit request.

Checksum Generation

For Aggregators

Format: 'amount''cell''comment''merchantname''mid''msgcode''orderid''token''txntype''aggregatedMerchantId'

For Direct Merchants

Format: 'amount''cell''comment''merchantname''mid''msgcode''orderid''token''txntype'

Algorithm: HMAC SHA256
Secret Key: Provided by Mobikwik during merchant onboarding

📘 Note: For merchant MBK9006, the secret key is ju6tygh7u7tdg554k098ujd5468o. Each merchant will receive their unique secret key.

Sample Request

GET https://test.mobikwik.com/debitwallet?mid=MBK9006&cell=9311032820&amount=150.50&orderid=ORDER_123456&token=MBK_TOKEN_123456789&merchantname=TestMerchant&msgcode=504&comment=Payment%20for%20order&txntype=DEBIT&checksum=calculated_hash_value

With Coupon Code

GET https://test.mobikwik.com/debitwallet?mid=MBK9006&cell=9311032820&amount=150.50&orderid=ORDER_123456&token=MBK_TOKEN_123456789&merchantname=TestMerchant&msgcode=504&comment=Payment%20for%20order&txntype=DEBIT&couponcode=SAVE20&checksum=calculated_hash_value

Response Parameters

Field	Description	Example
messagecode	`String` Message code from request	`504`
status	`String` Transaction status	`SUCCESS`
statuscode	`String` Numeric status code	`0`
statusdescription	`String` Description of the status	`Transaction completed successfully`
orderid	`String` Order identifier from request	`ORDER_123456`
txnid	`String` Mobikwik transaction ID	`MBK_TXN_789012345`
amount	`String` Transaction amount	`150.50`
cashback	`String` Cashback amount applied	`5.00`
checksum	`String` Response checksum for validation	`8feac7700a4efd1ef08ea0ec5bf5921c3f1fc3398944421978794b9ada1c2c47`

Response Attributes

The response checksum that will be returned to the users will have the following format:

📘 Note: Always validate the response checksum to ensure data integrity and security.

Sample Responses

📘 Notes:

Always validate the response checksum for security
Use unique order IDs to prevent duplicate transactions
Implement proper error handling and retry mechanisms
Store transaction details for reconciliation purposes
Consider using webhooks for real-time transaction status updates

Success Response

{
  "messagecode": "504",
  "status": "SUCCESS",
  "statuscode": "0",
  "statusdescription": "Transaction completed successfully",
  "orderid": "ORDER_123456",
  "txnid": "MBK_TXN_789012345",
  "amount": "150.50",
  "cashback": "5.00",
  "checksum": "8feac7700a4efd1ef08ea0ec5bf5921c3f1fc3398944421978794b9ada1c2c47"
}

Failure Scenarios

Insufficient Balance

{
  "messagecode": "504",
  "status": "FAILURE",
  "statuscode": "301",
  "statusdescription": "Insufficient wallet balance",
  "orderid": "ORDER_123456",
  "checksum": "f25ac916fe4806591e16269fc912771456437b784fa144a77fa9842d154920cc"
}

Invalid Token

{
  "messagecode": "504",
  "status": "FAILURE",
  "statuscode": "302",
  "statusdescription": "Invalid or expired token",
  "orderid": "ORDER_123456",
  "checksum": "e35bc916fe4806591e16269fc912771456437b784fa144a77fa9842d154920dd"
}

Status Codes

Status	Status Code	Description
SUCCESS	0	Transaction completed successfully
FAILURE	301	Insufficient wallet balance
FAILURE	302	Invalid or expired token
FAILURE	303	Transaction limit exceeded
FAILURE	304	Duplicate order ID
FAILURE	305	Wallet temporarily blocked
FAILURE	Various	Other validation errors

Coupon Integration

Cashback Processing

Include couponcode parameter for real-time cashback calculation
Cashback amount is applied during transaction processing
Final debit amount = Original amount - Cashback amount
Response includes both original amount and cashback details

Example with Coupon

# Request with 20% cashback coupon
amount=100.00&couponcode=SAVE20

# Response shows:
"amount": "100.00",
"cashback": "20.00",
"net_debit": "80.00"