BillDesk

This documentation is provided for testing purposes and is subject to change in the future.

With the Adyen connection to BillDesk, you can support ecommerce and recurring transactions for all local credit cards in India, as well as a subset of local debit cards.

Follow the instructions below to connect to BillDesk with Adyen.

Ecommerce transactions with 3D Secure

In India, for all regular ecommerce transactions 3D Secure is mandated. Therefore, to process credit and debit cards through BillDesk, perform the following steps.

Step 1: Authorise with the return URL

Send the /authorise request with returnUrl added to additionalData.

Make sure that you include shopperIP and browserInfo.userAgent fields in the request, as they are always required for creating a mandate.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
            <ns1:paymentRequest>
                <amount xmlns="http://payment.services.adyen.com">
                    <currency xmlns="http://common.services.adyen.com">INR</currency>
                    <value xmlns="http://common.services.adyen.com">0</value>
                </amount>
                <browserInfo xmlns="http://payment.services.adyen.com">
                    <acceptHeader xmlns="http://common.services.adyen.com">text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5</acceptHeader>
                    <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6</userAgent>
                </browserInfo>
                <card xmlns="http://payment.services.adyen.com">
                    <expiryMonth>12</expiryMonth>
                    <expiryYear>2020</expiryYear>
                    <holderName>Shopper Name</holderName>
                    <number>4242420100058007</number>
                    <cvc>123</cvc>
                </card>
                <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchantAccount</merchantAccount>
                <reference xmlns="http://payment.services.adyen.com">init-12345</reference>
                <shopperReference xmlns="http://payment.services.adyen.com">test-123^456#789</shopperReference>
                <shopperEmail xmlns="http://payment.services.adyen.com">shopper@example.com</shopperEmail>
                <shopperIP xmlns="http://payment.services.adyen.com">127.0.0.1</shopperIP>
                <recurring xmlns="http://payment.services.adyen.com">
                    <contract>RECURRING</contract>
                </recurring>
                <additionalData xmlns="http://payment.services.adyen.com">
                    <entry>
                        <key xsi:type="xsd:string">returnUrl</key>
                        <value xsi:type="xsd:string">http://www.example.com/complete3d.shtml</value>
                    </entry>
                </additionalData>
            </ns1:paymentRequest>
        </ns1:authorise>
    </soap:Body>
</soap:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://payment.services.adyen.com">
    <soap:Body>
        <ns1:authoriseResponse>
            <ns1:paymentResult>
                <ns1:additionalData>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">mpiImplementationType</ns1:key>
                        <ns1:value xsi:type="xsd:string">BillDesk</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">BillDesk.TermUrl</ns1:key>
                        <ns1:value xsi:type="xsd:string">http://www.example.com/complete3d.shtml</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">BillDesk.MD</ns1:key>
                        <ns1:value xsi:type="xsd:string">U4560000777690</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">BillDesk.PaReq</ns1:key>
                        <ns1:value xsi:type="xsd:string">eJxVUU1TgzAQ...NEPSH8q0h8Us3+H/gHZpK+a</ns1:value>
                    </ns1:entry>
                </ns1:additionalData>
                <ns1:pspReference>9915361385272010</ns1:pspReference>
                <ns1:resultCode>RedirectShopper</ns1:resultCode>
                <ns1:issuerUrl>https://uat.billdesk.com/pgidsk/PGIDummyProcessor?reqid=BDDM001</ns1:issuerUrl>
                <ns1:md>djIhYlFBSHEvVHFZbFBQbXVoaVRB...e6J1uiJgfAmtfe2H/givDx2BlQZNY=</ns1:md>
            </ns1:paymentResult>
        </ns1:authoriseResponse>
    </soap:Body>
</soap:Envelope>

Step 2: Redirect to the issuer URL

Make an HTTP POST request to the issuerUrl with all the cleaned additional data entries as inputs (i.e. pass BillDesk.MD as MDBillDesk.PaReq as PaReq, and BillDesk.TermUrl as TermUrl).

<form action="https://uat.billdesk.com/pgidsk/PGIDummyProcessor?reqid=BDDM001" method="post">
    <input type="hidden" name="MD" value="U4560000777690">
    <input type="hidden" name="PaReq" value="eJxVUU1TgzAQ...NEPSH8q0h8Us3+H/gHZpK+a">
    <input type="hidden" name="TermUrl" value="http://www.example.com/complete3d.shtml">
    <input type="submit">
</form>

Step 3: Return to the merchant site

On your return URL (that you provided as TermUrl), process the HTTP POST request coming from the issuer. This request will contain MD and PaRes parameters, which you'll need to submit to Adyen on Step 4.

Step 4: Complete the payment

Send the /authorise3d request with the md from the original /authorise response and together with all the prefixed parameters received from the issuer, e.g. send PaRes as BillDesk.PaRes.

Make sure that you include shopperIP and browserInfo.userAgent fields in the request, as they are always required for creating a mandate.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <ns1:authorise3d xmlns:ns1="http://payment.services.adyen.com">
            <ns1:paymentRequest3d>
                <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchantAccount</merchantAccount>
                <md xmlns="http://payment.services.adyen.com">djIhT20xNzlmVE8xNzQ2Ykh6VEZ0aFVZUT09...5eMlYf3JyuzKkg=</md>
                <additionalData xmlns="http://payment.services.adyen.com">
                    <entry>
                        <key xsi:type="xsd:string">mpiImplementationType</key>
                        <value xsi:type="xsd:string">BillDesk</value>
                    </entry>
                    <entry>
                        <key xsi:type="xsd:string">BillDesk.MD</key>
                        <value xsi:type="xsd:string">U4560000777690</value>
                    </entry>
                    <entry>
                        <key xsi:type="xsd:string">BillDesk.PaRes</key>
                        <value xsi:type="xsd:string">eJydl9mum0oahe/9FFHOJUqYbGyOHEv...7ab5urT8egP9N0/Ayn0=</value>
                    </entry>
                </additionalData>
                <shopperIP xmlns="http://payment.services.adyen.com">127.0.0.1</shopperIP>
                <browserInfo xmlns="http://payment.services.adyen.com">
                    <acceptHeader xmlns="http://common.services.adyen.com">text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5</acceptHeader>
                    <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6</userAgent>
                </browserInfo>
            </ns1:paymentRequest3d>
        </ns1:authorise3d>
    </soap:Body>
</soap:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://payment.services.adyen.com">
    <soap:Body>
        <ns1:authorise3dResponse>
            <ns1:paymentResult>
                <ns1:additionalData>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">billdesk.recurringMandate</ns1:key>
                        <ns1:value xsi:type="xsd:string">MN24C200000506</ns1:value>
                    </ns1:entry>
                </ns1:additionalData>
                <ns1:pspReference>9915361385272010</ns1:pspReference>
                <ns1:resultCode>Authorised</ns1:resultCode>
            </ns1:paymentResult>
        </ns1:authorise3dResponse>
    </soap:Body>
</soap:Envelope>

Recurring payments

To establish a recurring contract for BillDesk, you need to provide the following data to Adyen:

  • Recurring mandate frequency.
  • Recurring mandate maximum amount.

Initially, these values can be configured on the acquirer account. However, to have full control over these values, you can provide them along with your API request to Adyen.

Request

The table below lists the BillDesk-specific properties, which you can submit in additionalData:

Field Type Description

BillDesk.recurringMaxAmount

String

Represented in minor units ("INR" for BillDesk).

BillDesk.recurringFrequency

String

Allowed values:

  • WEEKLY
  • BI_MONTHLY
  • MONTHLY
  • QUARTERLY
  • BI_ANNUALLY
  • ANNUALLY
  • AD_HOC


The following example demonstrates a request with the BillDesk data provided in additionalData:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <sale xmlns="http://acm.services.adyen.com">
      <authRequest>
        <acquirerAccountCode>BillDeskAcquirerAccount</acquirerAccountCode>
        <additionalData>
          <entry>
            <key xsi:type="xsd:string">mpiImplementationType</key>
            <value xsi:type="xsd:string">BillDesk</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">BillDesk.txnrefno</key>
            <value xsi:type="xsd:string">U4560000742100</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">BillDesk.PaRes</key>
            <value xsi:type="xsd:string">eJydl2mv2joext/zKarel6jNSsJJC...em9vzdej5dc36L8Bp9LHtg==</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">BillDesk.Status</key>
            <value xsi:type="xsd:string">null</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">BillDesk.sessionId</key>
            <value xsi:type="xsd:string">8A9XmT8MoVHhvmbzC0P1cuVmjfo=</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">BillDesk.MD</key>
            <value xsi:type="xsd:string">U4560000742100</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">attemptnumber</key>
            <value xsi:type="xsd:string">0</value>
          </entry>
        </additionalData>
        <amount>
          <currency xmlns="http://common.services.adyen.com">INR</currency>
          <value xmlns="http://common.services.adyen.com">865044</value>
        </amount>
        <browserInfo>
          <acceptHeader xmlns="http://common.services.adyen.com">text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</acceptHeader>
          <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.1.1 Safari/605.1.15</userAgent>
        </browserInfo>
        <card>
          <cvc xmlns="http://payment.services.adyen.com">***</cvc>
          <expiryMonth xmlns="http://payment.services.adyen.com">12</expiryMonth>
          <expiryYear xmlns="http://payment.services.adyen.com">2020</expiryYear>
          <holderName xmlns="http://payment.services.adyen.com">Foo Bar</holderName>
          <number xmlns="http://payment.services.adyen.com">************8007</number>
        </card>
        <merchantAccount>TestMerchant</merchantAccount>
        <merchantReference>TMRef1234</merchantReference>
        <pspReference>9915303444752996</pspReference>
        <recurring>
          <contract xmlns="http://payment.services.adyen.com">RECURRING</contract>
        </recurring>
        <shopperEmail>shopper@example.com</shopperEmail>
        <shopperIP>0:0:0:0:0:0:0:1</shopperIP>
        <shopperInteraction>Ecommerce</shopperInteraction>
        <shopperReference>ref321</shopperReference>
        <variant>visa</variant>
      </authRequest>
    </sale>
  </soap:Body>
</soap:Envelope>

Response

Adyen returns the following additionalData in the response to indicate whether a recurring mandate was created:

Field Type Description
billdesk.recurringMandate String Contains the mandateId from BillDesk (possibly masked). If this field is not returned, this means that the card does not support recurring.

The following example demonstrates a response with the BillDesk data included into additionalData:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:saleResponse xmlns:ns1="http://acm.services.adyen.com">
      <ns1:authResponse>
        <acmReference xmlns="http://acm.services.adyen.com">9915302784752996</acmReference>
        <acquirerResponseCode xmlns="http://acm.services.adyen.com">0300 : Success (PGS10001-Success)</acquirerResponseCode>
        <additionalData xmlns="http://acm.services.adyen.com">
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.recurringMandate</key>
            <value xsi:type="xsd:string">MN1C1E00000178</value>
          </entry>
        </additionalData>
        <responseCode xmlns="http://acm.services.adyen.com">1</responseCode>
        <authorisationData xmlns="http://acm.services.adyen.com">
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.MANDATE_ID</key>
            <value xsi:type="xsd:string">MN1C1E00000178</value>
          </entry>
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.VARIANT</key>
            <value xsi:type="xsd:string">visa</value>
          </entry>
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.MANDATE_FREQUENCY</key>
            <value xsi:type="xsd:string">bimn</value>
          </entry>
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.TXN_REFERENCE_NO</key>
            <value xsi:type="xsd:string">U4560000742100</value>
          </entry>
          <entry xmlns="null">
            <key xsi:type="xsd:string">billdesk.MANDATE_MAX_AMOUNT</key>
            <value xsi:type="xsd:string">1000.00</value>
          </entry>
        </authorisationData>
        <authorisationDataType xmlns="http://acm.services.adyen.com">BillDesk</authorisationDataType>
        <avsResponseCode xmlns="http://acm.services.adyen.com">0</avsResponseCode>
        <cvcResponseCode xmlns="http://acm.services.adyen.com">*</cvcResponseCode>
        <externalReferences xmlns="http://acm.services.adyen.com">
          <ExternalReference>
            <externalReferenceTypeCode>AcquirerReference</externalReferenceTypeCode>
            <value>U4560000742100</value>
          </ExternalReference>
        </externalReferences>
        <responseTimeMs xmlns="http://acm.services.adyen.com">5152</responseTimeMs>
        <transactionDate xmlns="http://acm.services.adyen.com">2018-06-29T23:17:08+10:00</transactionDate>
      </ns1:authResponse>
    </ns1:saleResponse>
  </soap:Body>
</soap:Envelope>