BillDesk Payment Gateway Integration Guide

Updated: May 21, 2026

The purpose of this document is to lay down the payment integration with BillDesk that is required for a merchant, or a Solution Partner, that has implemented a chatbot using WhatsApp Business APIs and needs to accept payments from WhatsApp users.

This document outlines the necessary APIs that must be integrated and how the integration works in conjunction with the WhatsApp Business API integration. While not a comprehensive guide, it serves as a general overview to assist in understanding the payment gateway integration process. Any specific or unique details related to the payment gateway must be determined by the merchant or Solution Partner.

In terms of integrating with the WA P2M product, this document covers the requests and responses highlighted in red in the flow diagram.

BillDesk payment integration

Setup

To authenticate with BillDesk's API, a client must be created and an authentication method must be selected between HMAC and JavaScript Object Signing and Encryption (JOSE) with JOSE being the preferred method. These methods are used to encrypt/decrypt the request/response from BillDesk's APIs.

To simplify the explanation, the following examples will only address the body of final payload that will ultimately be included in the final object required for successful authentication with their API. It is important to consult BillDesk's documentation for guidance on how this final object must be structured.

You must have the following details before you can proceed:

• Client ID and secret key from BillDesk
• Details from the payment configuration you already configured on the WhatsApp Business Account
  • Merchant category code
  • Merchant's VPA
• Merchant Name

Initiate payment API

Sample request to POST to https://pguat.billdesk.io/payments/ve1\_2/transactions/create

{  
  "mercid": "BDMERCHANTID",  
  "orderid": "UPIODR00000004",  
  "amount": "2.00",  
  "currency": "356",  
  "bankid": "ICW",  
  "txn_process_type": "intent",  
  "itemcode": "DIRECT",  
  "payment_method_type": "upi",  
  "wa_mc": "0743",  
  "wa_vpa": "billdesk@hdfcbank",  
  "wa_txnid": "H477676443",  
  "wa_mercname": "SIDDHIVINK",  
  "additional_info": {  
    "additional_info1": "Details1",  
    "additional_info2": "Details2"  
  },  
  "device": {  
    "init_channel": "app",  
    "ip": "124.124.1.1",  
    "user_agent": "App/22.6.74 Platform/19.5.0"  
  }  
}

Parameters	Description
order id (Mandatory)	string Unique order id generated by the merchant to identify the transaction
mercid (Mandatory)	string Unique identifier as defined by BillDesk for each merchant
amount (Mandatory)	string Transaction amount in two decimals
currency (Mandatory)	string ISO currency of the transaction amount
txn_process_type (Optional)	string Value must be set to intent
bankid (Optional)	string BillDesk defined unique identifier for bank or acquirer
ru (Optional)	string Merchant return url
itemcode (Mandatory)	string Itemcode value as provided by BillDesk, with a default value DIRECT
device (Mandatory)	object Device object. Refer to BillDesk doc for more details.
payment_method_type (Mandatory)	string This must be set to upi
wa_mc (Mandatory)	string Merchant category
wa_vpa (Mandatory)	string Payee VPA
wa_txnid (Mandatory)	string Unique txnid generated by the bank for the transaction
wa_mercname (Mandatory)	string Merchant Name

Sample response

{  
  "objectid": "transaction",  
  "transactionid": "X7890477676443",  
  "orderid": "UPIODR00000004",  
  "mercid": "BDMERCID",  
  "transaction_date": "2022-03-18T11:50:27+05:30",  
  "amount": "2.00",  
  "surcharge": "0.00",  
  "discount": "0.00",  
  "charge_amount": "2.00",  
  "currency": "356",  
  "additional_info": {  
    "additional_info1": "Details1",  
    "additional_info2": "Details2"  
  },  
  "txn_process_type": "intent",  
  "bankid": "ICW",  
  "itemcode": "DIRECT",  
  "auth_status": "0002",  
  "transaction_error_code": "TRP0000",  
  "transaction_error_desc": "Transaction Pending ",  
  "transaction_error_type": "pending",  
  "payment_method_type": "upi",  
  "wa_mc": "7399",  
  "wa_vpa": "billdesk@hdfcbank",  
  "wa_txnid": "H477676443",  
  "wa_mercname": "SIDDHIVINK",  
  "intent": "dXBpOi8vcGF5P3BhPWJpbGxkZXNrQGhkZmNiYW5rJnBuPVNJRERISVZJTksmbWM9NjMwMCZ0cj1YSEQ1MDQ3NzY3NjQ0MyZ0bj1QYXkmYW09Mi4wMCZtYWwMCZjdT1JTlI="  
}

Parse the response

Use the value of wa_txnid on the response and pass it as the reference_id while setting up the parameters object to send for the order details message using the API.

Make sure to verify the values in the intent you receive:

• The intent key has the base64 encoded value of the intent
• Decoding the intent should give a value that should be similar to this: upi://pay?pa=billdesk@hdfcbank&pn=SIDDHIVINKamp;mc=6300&tr=XHD50477676443&tn=Pay&am=2.00&malORS
• The value of pa is the merchant VPA. This value must match the VPA on the payment_configuration you send in the parameters object

Status webhook

BillDesk will post a transaction object to the return URL (ru) you specified in the initiate payment API.

Key	Data type	Description
objectid (Mandatory)	string	String representing the object's type. This value will be fixed as transaction
transactionid	string	Unique transaction ID generated by BillDesk for the transaction
orderid	string	Unique orderid generated by the merchant for the transaction
mercid	string	Unique identifier as defined by BillDesk for each merchant
transaction_date	timestamp	BillDesk transaction date and time in YYYY-MM DDThh:mm:ssTZD format
amount	string	Transaction amount in two decimals
surcharge	string	Customer surcharge in two decimals applied to the transaction amount, if any
discount	string	Customer discount in two decimals applied to the transaction amount, if any
charge_amount	string	Total charge to the customer
currency	integer	ISO currency of the transaction amount
txn_process_type	string	Indicates transaction processing type. Intent for payment_method_type is upi and the method of payment is UPI intent
bankid	string	BillDesk defined unique identifier for bank or acquirer
ru	string	Merchant return url
additional_info	object	Array of 10 additional_info values that can be attached to the transaction. Note: Do not pass customer PII information in additional info fields.
itemcode	string	Itemcode value provided by BillDesk, with a default value of DIRECT
bank_ref_no	string	Transaction reference number generated by bank or acquirer
auth_status	string	Represents the authorization status of the transaction with the possible values: * 0300 - transaction is successful * 0002 - transaction is pending for authorization * 0399 - transaction failed
settlement_lob	string	Settlement line of business pre-configured by BillDesk for funds settlement to merchant account
customer	object	Customer object
device	object	Device object
transaction_error_code	string	Represents the error code for a transaction with 0399 status
transaction_error_type	string	Represents the standard error category for a transaction with 0399 status
transaction_error_desc	string	Represents the description of the error code for a transaction with 0399 status
authcode	string	Authorization code received from the acquirer for a successfully authorized card transaction
eci	string	eci value for the authentication taken for the card transaction
payment_method_type	string	Represents the method of payment e.g. upi
card	Object	Payment method object (applicable when payment method is card)
customer_refid	string	Unique customer identifier as per merchant
links	object	Associated links with the object

Parsing the response

Use the auth_status retrieved from the response above and transmit the corresponding status message via the WhatsApp API.