Sign in

v1

latestOpenAPI 3.0.02026-07-2431146358.7 KB
Mandate

Create Mandate

A mandate can be created by providing the details of the subscription and the associated payment method. To create a mandate using a payment method, a ‘small-value’ authorization has to be completed for payment_method_type = card and upi.

Mandates can be created using the card, upi or bankaccount (ie enach) as the payment method.

post/pgsi/ve1_2/mandates/create

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

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

amountstring required

Subscription amount in two decimals, eg. 2400.00

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)

authentication_type'3ds2' required

Represents the type of authentication initiated in the request, will be fixed value - 3ds2

3ds_parameter'merchant' required

Value that determines which entity will capture the device attributes, possible values are merchant

payment_method_type'card' | 'netbanking' | 'upi' required

Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option) The associated object will also be provided in the request.

verification_required'true' | 'false'

Indicates whether a verification is required while creating the mandate, and takes the boolean true. Note Required only where payment_method_type = bankaccount.

verification_type'enach_nb' | 'enach_dc'

Indicates type of verification that will be performed by the customer to set up the mandate, accepted values are enach_nb for netbanking, enach_dc for debit card. Note Required only where payment_method_type = bankaccount.

rustring required

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

currencystring required

ISO currency 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

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

Example request

{
  "mercid": "BDMERCID",
  "customer_refid": "CSREF00001",
  "subscription_refid": "SUBREF101",
  "subscription_desc": "Unlimited Plan",
  "start_date": "2021-05-08",
  "end_date": "2059-12-31",
  "amount": "2400.00",
  "authentication_type": "3ds2",
  "ru": "https://www.merchant.com",
  "debit_day": "1",
  "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",
    "browser_language": "en-US",
    "browser_tz": "-330",
    "browser_color_depth": "652",
    "browser_screen_height": "452",
    "browser_screen_width": "702"
  },
  "card": {
    "number": "4242420000001234",
    "expiry_month": "02",
    "expiry_year": "2029",
    "holder_name": "John Doe",
    "cvv": "123"
  },
  "bankaccount": {
    "number": "8928292891111",
    "holder_name": "John Doe",
    "dest_bank_id": "YBK",
    "ifsc": "BANK0000002",
    "bank_id": "1HM"
  },
  "upi": {
    "vpa": "abc@okbank"
  },
  "avs": {
    "bankaccounts": [
      {
        "number": "12233445566",
        "ifsc": "IDBK10000002",
        "name": "John Doe"
      }
    ]
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "9022979988",
    "email": "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"
  }
}

Response

OK

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

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

mandateidstring

Unique mandateid created by BillDesk

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

Unique reference assigned by merchant for a subscription

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

Subscription amount in two decimals, eg. 2400.00

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 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

statusstring

Represents the status of the mandate and depends upon the linked payment method.

The following values are possible: card, upi • initiated - mandate request has been initiated, and this status is applicable for the SDK based workflow • pending - mandate request has been initiated and the linked payment method is not yet validated • active – linked payment method has been validated and recurring charges can be processed • rejected - mandate has been rejected by the issuer or payment provider • deleted - mandate has been deleted by the customer from the merchant channel • cancelled – mandate has been stopped by customer from the issuer channel • suspended – mandate has been temporarily suspended by the issuer or payment provider bankaccount • pending – mandate request has been sent for account verification to NPCI • active – mandate is active and recurring charges can be processed • delete_initiated – mandate delete request is initiated by the customer or the merchant • deleted – mandate is deleted after confirmation from NPCI • rejected – mandate is rejected by NPCI

createdonstring date-time

object creation timestamp

payment_method_type'card' | 'netbanking' | 'upi'

Represents the method of payment, and can take the following values - card, netbanking, wallet, upi, eft, bankaccount, cashcard, cardless (non-card emi option) The associated object will also be provided in the request.

rustring

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

verification_error_codestring

Represents the error code for the response

verification_error_typestring

Represents the error type for the response

verification_error_descstring

Represents the error description for the response

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

qrImagestring
intentstring
bank_umrnstring

Unique mandate reference number provided from the acquiring bank or network Note: This attribute is provided for the upi and bankaccount payment methods

bank_rrnstring
valid_datestring

Date and time till when the url is valid

customer_message'capture_otp'

Customer message for display and is generally provided in the native OTP authentication journey, ie. next_step=capture_otp

Example response

{
  "mercid": "BDMERCID",
  "mandateid": "MA19E400049927",
  "customer_refid": "CSREF00001",
  "subscription_refid": "SUBREF101",
  "subscription_desc": "SUBREF101",
  "start_date": "2021-05-08",
  "end_date": "2059-12-31",
  "amount": "2400.00",
  "ru": "https://www.merchant.com",
  "card": {
    "type": "debit, credit, prepaid",
    "masked_value": "xxxxxxxxxxxx1001",
    "network": "VISA, MASTER"
  },
  "additional_info": {
    "additional_info1": "Details1",
    "additional_info2": "Details2",
    "additional_info3": "Details3",
    "additional_info4": "Details4",
    "additional_info5": "Details5",
    "additional_info6": "Details6",
    "additional_info7": "Details7"
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "9022979988",
    "email": "abc@xyz.com"
  },
  "bank_umrn": "130a977ccabb11e7abc4cec278b6b50a@mypsp",
  "avs": {
    "bankaccount": [
      {
        "number": "12233445566",
        "ifsc": "IDBK10000002",
        "name": "John Doe"
      }
    ]
  }
}