Create Order

This API can be used to initiate a payment or to set up a mandate along with a payment in the BillDesk Hosted Payment Page or BillDesk Web SDK workflow

BD-Traceidstring required

Example:20201203182838

BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.

BD-Timestampstring required

Example:20201203182838

Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.

Content-Typestring required

Example:application/json

Request Content-Type to take the values application/jose

Acceptstring required

Example:application/jose

Accept Response Content-Type to take the values application/jose

Request body

orderidstring required

Unique ID generated by the merchant for each request

mercidstring required

Unique identifier as defined by BillDesk for each merchant

order_datestring date-time required

Merchant order generation date and time in YYYY-MM-DDThh:mm:ssTZD format

amountstring required

Transaction amount in two decimals, eg. 299.28

currencystring required

ISO currency of the transaction amount, for INR this value will be 356

rustring required

Merchants URL where the customer will be redirected after a transaction is completed

itemcodestring required

Itemcode value as provided by BillDesk, with a default value DIRECT

settlement_lobstring

Settlement line of business preconfigured by BillDesk for funds settlement to merchant account

mandate_required'Y' | 'N'

Value which represents if the customer is to be givrn the option to not set a mandate on the BillDesk Hosted Payment Page or Web SDK. Applicable for the One time payment & Mandate workflow

Y- Represents that setting the Mandate is mandatory and the customer does not have an option to turn off the mandate

N- Represents that setting the Mandate is optional and the customer has an option to turn off the mandate. In this case, a one time payment will be made without the mandate

Example request

{
  "orderid": "TEST0000009005",
  "mercid": "BDMERCID",
  "order_date": "2023-03-14T15:14:39+05:30",
  "amount": "299.28",
  "ru": "https://www.merchant.com",
  "itemcode": "DIRECT",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "9022979988",
    "email": "abc@xyz.com"
  },
  "avs": {
    "bankaccounts": [
      {
        "number": "12233445566",
        "ifsc": "IDBK10000002",
        "name": "John Doe"
      }
    ]
  },
  "device": {
    "user_agent": "Mozilla/5.0(WindowsNT10.0;WOW64;rv: 51.0)Gecko/20100101Firefox/51.0",
    "accept_header": "application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9"
  },
  "invoice": {
    "invoice_number": "MEINVU111111221133",
    "invoice_display_number": "11221133",
    "customer_name": "John Doe",
    "invoice_date": "2021-09-03",
    "gst_details": {
      "cgst": "100.00",
      "sgst": "100.00",
      "igst": "200.00",
      "cess": "50.00",
      "gstin": "29GGGGG1314R9Z6"
    }
  },
  "split_payment": {
    "mercid": "BDMERCID",
    "amount": "299.28"
  },
  "mandate": {
    "mercid": "BDMERCID",
    "customer_refid": "CUSTREF00A00011",
    "subscription_refid": "SUBREF00A00011",
    "start_date": "2021-05-08",
    "end_date": "2059-12-31",
    "amount": "200.28",
    "currency": "356",
    "frequency": "adho",
    "debit_day": "1"
  },
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  }
}

Response

OK

String representing the object's type. Objects of the same type share the same value.

mercidstring

Unique identifier as defined by BillDesk for each merchant

amountstring

Transaction amount in two decimals, eg. 299.28

rustring

Merchants URL where the customer will be redirected after a transaction is completed

orderidstring

Unique ID generated by the merchant for each request

order_datestring date-time

Merchant order generation date and time in YYYY-MM-DDThh:mm:ssTZD format

bdorderidstring

Unique value generated by BillDesk for each order id generated using Create Order API

next_step'redirect' | 'capture_otp' | '3ds2_challenge' | '3ds2_frictionless'

Refers to the action to be taken by the merchant, for eg. redirect or capture_otp

itemcodestring

Itemcode value as provided by BillDesk, with a default value DIRECT

createdonstring date-time

object creation timestamp

currencystring

ISO currency of the transaction amount, for INR this value will be 356

status'ACTIVE'

Represents the status of the order, with the following possible values: • ACTIVE

Example response

{
  "mercid": "BDMERCID",
  "amount": "299.28",
  "ru": "https://www.merchant.com",
  "orderid": "TEST0000009005",
  "order_date": "2023-03-14T15:14:39+05:30",
  "itemcode": "DIRECT",
  "links": [
    {
      "parameters": {
        "mercid": "BDMERCID"
      }
    }
  ],
  "invoice": {
    "invoice_number": "MEINVU111111221133",
    "invoice_display_number": "11221133",
    "customer_name": "John Doe",
    "invoice_date": "2021-09-03",
    "gst_details": {
      "cgst": "100.00",
      "sgst": "100.00",
      "igst": "200.00",
      "cess": "50.00",
      "gstin": "29GGGGG1314R9Z6"
    }
  },
  "split_payment": {
    "mercid": "BDMERCID",
    "amount": "299.28"
  },
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  }
}

v1

Create Order

Headers

Request body

Example request

Response

Example response