BIbilldesk
Order

Create Mandate Token

Changed on

This API is used to initate the process to Create a Mandate and is applicable for BillDesk Hosted Payments Page and BillDesk Web SDK workflows

post/pgsi/ve1_2/mandatetokens/create

Request

  • Base URL
    https://uat1.billdesk.com/u2
  • URL
    https://uat1.billdesk.com/u2/pgsi/ve1_2/mandatetokens/create
  • Auth
    none declared. Required headers: BD-Traceid, BD-Timestamp, Content-Type, Accept

Headers

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

mercidstring required

Unique identifier as defined by BillDesk for each merchant

customer_refidstring required

Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer Required for mandate and tokenization

subscription_refidstring required

Unique reference assigned by merchant for a subscription

subscription_descstring required

Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel

currencystring required

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

frequency'week' | 'mnth' | 'bimn' | 'qurt' | 'bian' | 'year' | 'adho' required

Frequency at which the subscription debits will be processed, possible values are: •week - weekly •mnth - monthly •bimn – bi-monthly •qurt - quarterly •bian – bi-annually •year - yearly •adho – adhoc

amount_type'maximum' | 'fixed' required

Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible • maximum - indicates the maximum amount that can be charged for the subscription • fixed – indicates the fixed amount to be charged for the subscription Please note: For upi, only "maximum" is allowed. This is required to allow for token debit (small value transaction)

amountstring required

Transaction amount in two decimals, eg. 299.28

start_datestring date required

Subscription start date in yyyy-mm-dd format Note: Should be greater than or equal to current date (IST timezone). Note for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date

end_datestring date required

Subscription end date in yyyy-mm-dd format Note: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years

recurrence_rule'after'

Note: Required only where payment_method_type = upi. Default value : 'after'

debit_day'1'

Required only where payment_method_type = upi. Default value "1" to be passed

rustring required

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

Example request

{
  "mercid": "BDMERCID",
  "customer_refid": "CSREF00001",
  "subscription_refid": "SUBREF101",
  "subscription_desc": "Unlimited Plan",
  "amount": "299.28",
  "start_date": "2021-05-08",
  "end_date": "2059-12-31",
  "debit_day": "1",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "9022979988",
    "mobile_alt": "9022979982",
    "email": "abc@xyz.com",
    "email_alt": "abc@xyz.com"
  },
  "ru": "https://www.merchant.com",
  "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"
  },
  "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

objectid'transaction' | 'authentication' | 'mandate' | 'invoice' | 'cardaccount' | 'validatevpa' | 'dispute' | 'settlement' | 'altid' | 'mandate_token' | 'accountvalidation' | 'refund'

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

mandate_tokenidstring

Unique value generated by BillDesk for each mandate_token created by the merchant

mercidstring

Unique identifier as defined by BillDesk for each merchant

customer_refidstring

Unique reference of the customer in the merchant system, and can be linked to different subscriptions of the same customer Required for mandate and tokenization

subscription_refidstring

Unique reference assigned by merchant for a subscription

subscription_descstring

Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel

start_datestring date

Subscription start date in yyyy-mm-dd format Note: Should be greater than or equal to current date (IST timezone). Note for UPI : Should be equal to mandate creation date for UPI. In UPI, an subsequent charge is created on a successful mandate. This includes the first charge as well along with mandate creation. Since first charge is done immediately, it is important that the mandate “start_date” should be today’s date

end_datestring date

Subscription end date in yyyy-mm-dd format Note: Should be greater than current date (IST timezone). For mandates that are valid ‘until cancelled’ by the customer, end_date year could be 2099, and for upi, maximum duration allowed for a mandate is 30 years

amountstring

Transaction amount in two decimals, eg. 299.28

amount_type'maximum' | 'fixed'

Indicates whether subscription amount is fixed or has a maximum limit. The following values are possible • maximum - indicates the maximum amount that can be charged for the subscription • fixed – indicates the fixed amount to be charged for the subscription Please note: For upi, only "maximum" is allowed. This is required to allow for token debit (small value transaction)

currencystring

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

frequency'week' | 'mnth' | 'bimn' | 'qurt' | 'bian' | 'year' | 'adho'

Frequency at which the subscription debits will be processed, possible values are: •week - weekly •mnth - monthly •bimn – bi-monthly •qurt - quarterly •bian – bi-annually •year - yearly •adho – adhoc

createdonstring date-time

object creation timestamp

rustring

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

status'0300' | '0002' | '0399'

Represents the authorization status of the transaction with the following possible values: • 0300 - transaction is successful • 0002 - transaction is pending for authorization • 0399 - transaction failed

recurrence_rule'after'

Note: Required only where payment_method_type = upi. Default value : 'after'

debit_day'1'

Required only where payment_method_type = upi. Default value "1" to be passed

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

Example response

{
  "mercid": "BDMERCID",
  "customer_refid": "CSREF00001",
  "subscription_refid": "SUBREF101",
  "subscription_desc": "Unlimited Plan",
  "start_date": "2021-05-08",
  "end_date": "2059-12-31",
  "amount": "299.28",
  "ru": "https://www.merchant.com",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "9022979988",
    "mobile_alt": "9022979982",
    "email": "abc@xyz.com",
    "email_alt": "abc@xyz.com"
  },
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  },
  "debit_day": "1",
  "links": [
    {
      "parameters": {
        "mercid": "BDMERCID"
      }
    }
  ]
}

Changes

  • ae8f82399027Revision changes
    • breaking

      the request property / became required

    • breaking

      the request property / became required

    • warning

      changed the pattern of the request property / from ^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9\-]+)*(\.[A-Za-z]{2,6})$ to ^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9\\-]+)*(\\.[A-Za-z]{2,6})$

    • warning

      changed the pattern of the request property / from ^[\+]{0,1}[0-9]{5,15}$ to ^[\\+]{0,1}[0-9]{5,15}$

    • warning

      added the new refund enum value to the response property for the response status

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      removed the pattern ^[A-Za-z0-9]{1,15}$ from the request property /

    • info

      removed the pattern ^[A-Za-z0-9]{1,15}$ from the request property /

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      the response property / became required for the status

    • info

      the response property / became required for the status

    • info

      the / response's property pattern was changed from ^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9\-]+)*(\.[A-Za-z]{2,6})$ to ^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9\\-]+)*(\\.[A-Za-z]{2,6})$ for the status

    • info

      the / response's property pattern was changed from ^[\+]{0,1}[0-9]{5,15}$ to ^[\\+]{0,1}[0-9]{5,15}$ for the status

    • info

      the / response's property pattern ^[A-Za-z0-9]{1,15}$ was removed for the status

    • info

      the / response's property pattern ^[A-Za-z0-9]{1,15}$ was removed for the status