Skip to main content

Billdesk Payment Gateway Integration Guide | Developer Documentation

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 BilldeskDetails from the payment configuration you already configured on the WhatsApp Business Account
      Merchant category codeMerchant’s VPAMerchant 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
      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 intentDecoding 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&malORSThe 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 generation by BillDesk for the transaction
        orderid
        string
        Unique orderid generated by merchant to 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
        txn_process_type
        string
        Indicates transaction processing type.
        Intent for payment_method_type is upi and the method of payment is UPI intent.
        ru
        string
        Merchant return url
        additional_info
        object
        Array 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.
        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 successful0002 - transaction is pending for authorization0399 - 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.
          
    
                  
          
        
          
    
          
        
          
            
          
                
                
          
                    
                    
                
          
            
          
            
            
          
                                            
          
        
          
    
          

    

          
    
          

    
            
          
            
          

    
          
        
          
            
            
        
          
            
          

    
          
        
          
                    
          

        
          No comments to display
          

            
          

    

    

                      
          
        
          
                
          
        
          
    
          

    
          

    
    
          
        
          
             Back to top