> ## Documentation Index
> Fetch the complete documentation index at: https://whatsapp-docs.kap.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Pg guide billdesk
# 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](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](https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-in/upi-intent#paramobject) 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 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 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](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/upi#step-7--update-order-status) via the WhatsApp API.
Did you find this page helpful?
ON THIS PAGE
Billdesk payment integration
Setup
Initiate Payment API
Sample request to POST to [https://pguat.billdesk.io/payments/ve1\_2/transactions/create](https://pguat.billdesk.io/payments/ve1_2/transactions/create)
Sample response
Parse the response
Status webhook
Parsing the response
***