Create Mandate

post

https://uat1.billdesk.com/u2/pgsi/ve1_2/mandates/create

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.

Body Params

mercid

string

required

Unique identifier as defined by BillDesk for each merchant

customer_refid

string

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_refid

string

required

Unique reference assigned by merchant for a subscription

subscription_desc

string

required

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

start_date

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_date

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

amount

string

required

Subscription amount in two decimals, eg. 2400.00

amount_type

string

enum

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)

Allowed:

authentication_type

string

enum

required

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

Allowed:

3ds_parameter

string

enum

required

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

Allowed:

payment_method_type

string

enum

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.

Allowed:

verification_required

string

enum

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

Allowed:

verification_type

string

enum

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.

Allowed:

string

required

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

currency

string

required

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

frequency

string

enum

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

Allowed:

recurrence_rule

string

enum

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

Allowed:

debit_day

string

enum

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

Allowed:

device

object

required

Device Object

card

bankaccount

object

Required when payment_method_type = bankaccount

upi

object

Required when payment_method_type = upi and txn_process_type = collect

avs

object

This API can be used to verify the bank account number by initiating a penny drop to the account. For upi, validation is done at acquiring bank end

customer

object

additional_info

object

Array of 7 additional_info values that can be attached to the transaction. Note: Merchant is advised to not pass customer PII information in additional info fields.

Headers

BD-Traceid

string

required

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

string

required

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

string

required

Request Content-Type to take the values application/jose

string

required

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

Responses

200OK

403Forbidden

500Internal Server Error

defaultAny bad or invalid request will lead to following error object