--- title: "Create Mandate Token" method: POST path: "/pgsi/ve1_2/mandatetokens/create" tags: ["Order"] --- # Create Mandate Token `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` 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 ## Headers - `BD-Traceid` string, required - `BD-Timestamp` string, required - `Content-Type` string, required - `Accept` string, required ## Request body - object - `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 - `currency` string, 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) - `amount` string, required: Transaction amount in two decimals, eg. 299.28 - `start_date` string, 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` string, 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 - `customer` Customer, required - `first_name` string, required: Customer’s First Name - `last_name` string, required: Customer’s Last Name - `mobile` string: Customer’s Mobile number - `mobile_alt` string: Customer’s Alternate Mobile number - `email` string: Customer’s Email address - `email_alt` string: Customer’s alternate Email Address - `ru` string, required: Merchants URL where the customer will be redirected after a transaction is completed - `device` DeviceOrder, required: Device - `init_channel` 'internet' | 'app' | 'kiosk', required: Initiating channel,accepted values are internet,app or kiosk - `ip` string, required: Actual end customer IP address is required to be passed - `user_agent` string, required: Exact content of the HTTP user-agent header Note: If the total length of the User-Agent sent by the browser exceeds 2048 characters, truncate the excess portion - `accept_header` string, required: Customer browser accept header values - `additional_info` AdditionalInfo: 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. - `additional_info1` string - `additional_info2` string - `additional_info3` string - `additional_info4` string - `additional_info5` string - `additional_info6` string - `additional_info7` string ## Response `200` OK - object - `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_tokenid` string: Unique value generated by BillDesk for each mandate_token created by the merchant - `mercid` string: Unique identifier as defined by BillDesk for each merchant - `customer_refid` string: 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: Unique reference assigned by merchant for a subscription - `subscription_desc` string: Customer friendly description for the subscription, this narration is generally displayed to the customer at the issuer channel - `start_date` string, 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_date` string, 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 - `amount` string: 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) - `currency` string: 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 - `createdon` string, date-time: object creation timestamp - `ru` string: Merchants URL where the customer will be redirected after a transaction is completed - `customer` Customer - `first_name` string, required: Customer’s First Name - `last_name` string, required: Customer’s Last Name - `mobile` string: Customer’s Mobile number - `mobile_alt` string: Customer’s Alternate Mobile number - `email` string: Customer’s Email address - `email_alt` string: Customer’s alternate Email Address - `additional_info` AdditionalInfo: 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. - `additional_info1` string - `additional_info2` string - `additional_info3` string - `additional_info4` string - `additional_info5` string - `additional_info6` string - `additional_info7` string - `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 - `links` object[] - `method` string - `rel` string - `href` string - `headers` object - `authorization` string: Unique value generated by BillDesk for each request - `valid_date` string - `parameters` object - `mercid` string: Unique identifier as defined by BillDesk for each merchant - `bdorderid` string: Unique value generated by BillDesk for each order id generated using Create Order API - `rdata` string: Unique key generated by BillDesk for each request ## Other responses - `403`: Forbidden - `500`: Internal Server Error - `default`: Any bad or invalid request will lead to following error object ## Changes - **2026-11-03** `ae8f82399027`: 2 breaking, 3 warning, 12 info - the request property `customer/first_name` became required - the request property `customer/last_name` became required - changed the pattern of the request property `customer/email` 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})$` - changed the pattern of the request property `customer/mobile` from `^[\+]{0,1}[0-9]{5,15}$` to `^[\\+]{0,1}[0-9]{5,15}$` - …13 more [Operation history](https://skmtc.dev/billdesk/apis/payments/changes/pgsi/ve1_2/mandatetokens/create/post.md) --- [API](https://skmtc.dev/billdesk/apis/payments.md) - [All operations](https://skmtc.dev/billdesk/apis/payments/llms.txt) - [OpenAPI document](https://skmtc.dev/billdesk/apis/payments/revisions/ae8f82399027?raw)