Skip to main content

​
Billdesk Payment Gateway Integration Guide

Updated: Nov 14, 2025 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"
  }
}
ParametersDescription
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
devic (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.
KeyData typeDescription
objectid (Mandatory)stringString representing the object’s type. This value will be fixed as transaction
transactionidstringUnique transaction ID generation by BillDesk for the transaction
orderidstringUnique orderid generated by merchant to for the transaction
mercidstringUnique identifier as defined by BillDesk for each merchant
transaction_datetimestampBillDesk transaction date and time in YYYY-MM DDThh:mm:ssTZD format
amountstringTransaction amount in two decimals
surchargestringCustomer surcharge in two decimals applied to the transaction amount, if any
discountstringCustomer discount in two decimals applied to the transaction amount, if any
charge_amountstringTotal charge to the customer
currencyintegerISO currency of the transaction amount
txn_process_typestringIndicates transaction processing type.
Intent for payment_method_type is upi and the method of payment is UPI intent
bankidstringBillDesk defined unique identifier for bank or acquirer
txn_process_typestringIndicates transaction processing type.
Intent for payment_method_type is upi and the method of payment is UPI intent.
rustringMerchant return url
additional_infoobjectArray of 10 additional_info values that can be attached to the transaction. Note: Merchant is advised to not pass customer PII information in additional info fields.
itemcodestringItemcode value provided by BillDesk, with a default value of DIRECT
bank_ref_nostringTransaction reference number generated by bank or acquirer
auth_statusstringRepresents the authorization status of the transaction with the possible values:
0300 - transaction is successful
0002 - transaction is pending for authorization
0399 - transaction failed
settlement_lobstringSettlement line of business pre-configured by BillDesk for funds settlement to merchant account
customerobjectCustomer object
deviceobjectDevice object
transaction_error_codestringRepresents the error code for a transaction with 0399 status
transaction_error_typestringRepresents the standard error category for a transaction with 0399 status
transaction_error_descstringRepresents the description of the error code for a transaction with 0399 status
authcodestringAuthorization code received from the acquirer for a successfully authorized card transaction
ecistringeci value for the authentication taken for the card transaction
payment_method_typestringRepresents the method of payment e.g. upi
cardObjectPayment method object (applicable when payment method is card)
customer_refidstringUnique customer identifier as per merchant
linksobjectAssociated 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. Did you find this page helpful? Thumbs up icon Thumbs down icon ON THIS PAGE Billdesk payment integration Setup Initiate Payment API Sample request to POST to https://pguat.billdesk.io/payments/ve1_2/transactions/create Sample response Parse the response Status webhook Parsing the response