Create Mandate RequestNEW

Create a mandate that is used for user to authenticate using UPI

To view error codes, click here

Create Mandate Request

post {BASE_URL}/v3/client/mandate/create_form

This API is used to create a upi mandate request

REQUEST

REQUEST BODY application/json

Field

Type

Description

corporate_config_id *

string

Corporate profile created from dashboard has below info and is auto populated during user authentication. Utility Code Service provider name Sponsor bank name Sponsor bank Sponsor bank ifsc

mandate_type *

enum

➔ Type of mandate to be created: 'create': 'amend':

Allowed: CREATE┃AMEND

- mandate_data*

object

Data attributes of mandate.

customer_ref_number

string

➔ Reference number maintained by Corporate
e.g.: Customer_id, Loan account number, Folio number, Insurance policy number etc
Max len = 20, ALPHA and NUMERIC allowed
Note : Please pass this attribute unique for each mandate created, as many sponsor banks consider it as a unique identifier at their end.

Constraints: 0 to 20 chars

Pattern: ^[0-9A-Za-z]{0,}$

is_recurring *

boolean

True / False
Pass False if its a one-time debit

frequency *

enum

➔ If is_recurring : true, pass debit frequency.

Note: Choose one from below, commensurate with your use case category (Management Category Code) eg: 7322 (Loan Installment should have a defined frequency that is commensurate with the EMI schedule agreed upon with the customer eg: Monthly). Incorrect frequency passed for a management category, may lead to mandate registration failure.
Adhoc [means “As on when presented”]
IntraDay
Daily
Weekly
Monthly
BiMonthly
Quarterly
Semiannually
Yearly

Default: ADHO

Allowed: ADHO┃INDA┃DAIL┃WEEK┃MNTH┃QURT┃MIAN┃YEAR┃ONETIME┃BIMN

first_collection_date *

date-time

Date for First Debit in yyyy-mm-dd ; means the date from which you want the mandate to be registered Note : Ideally it should be the current date on which the mandate is created. So auto debit can be successful

final_collection_date *

date-time

Date for Last Debit in yyyy-mm-dd

collection_amount *

number

➔ Collection amount for the mandate

Constraints: Min 1┃Max 100000

maximum_amount *

number

➔ Maximum amount that may be collected from the customer's account, per instruction eg: 4500.50

Note: Either of collection_amount or maximum_amount is mandatory.

UPI AutoPay Additional Factor of Authentication (AFA) (viz. UPI PIN) limit has been relaxed from 15,000/- to 2,00,000/- for the below Merchant Category Codes (MCC).
MCC Description
5413: Credit Card Bill Payments
5960: Direct Marketing Insurance Services
6012: Financial Institutions Merchandise and Services
6211: Securities brokers and dealers
6300: Insurance sales, underwriting and premiums
6381: Insurance Premiums
6399: Insurance
6529: LIC

Constraints: Min 1┃Max 200000

customer_name *

string

➔ Recommended that the name is same as per Destination Bank records
Max len = 100

Constraints: 0 to 100 chars

Pattern: ^[0-9A-Za-z]{1,}[0-9A-Za-z\s.]{0,}$

scheme_ref_number

string

➔ Additional Reference number maintained by Corporate for the reconciliation
E.g: Loan account number, Folio number, Insurance policy number etc
Max len = 20, ALPHA and NUMERIC allowed

Constraints: 0 to 20 chars

Pattern: ^[0-9A-Za-z]{0,}$

customer_mobile

string

➔ Customer Mobile number

Constraints: 0 to 34 chars

customer_email

string

➔ Customer Email address

Constraints: 0 to 50 chars

customer_account_number *

string

➔ Customer bank account number
Min len = 8 Max len = 18
All numeric

Constraints: 0 to 34 chars

customer_vpa

string

Virtual address of the customer

include_upi_url

boolean

➔ This is used if intent url is required in the response

Default: false

auto_debit_amount_in_paise

integer

Default 100 ( 1 Rs Auto Debit) Note: Only applicable in case auto debit amount needs to be customized. It should be less than maximum_amount

account_validation

boolean

➔ Set to true if mandate should be auto revoked in case the customer’s account number shared by merchant in “customer_account_number” is different then the account number used by customer to authenticate the UPI mandate.

Default: false

Allowed: true┃false

expire_in_days

integer

➔ Please pass this value to allow the end user to be able to submit the mandate image (in case of physical mandate) or perform eSign authentication within ‘X’ days. X you can pass as the value

Constraints: Min 1┃Max 90

auth_mode

enum

➔ Authentication mode for mandate. Possible values are: 'upi'

Allowed: upi

generate_access_token

boolean

➔ If true, will receive an access_token object in response. access_token used to bypass first factor authentication in SDKs.

Default: false

sub_user_identifier

string

If mandate needs to be reflected to specific sub-user

customer_identifier

string

User email or mobile

notify_customer

boolean

➔ Set true to send notification to customer with a gateway link to authenticate/sign the mandate. Else, false

Allowed: true┃false

include_authentication_url

boolean

➔ Pass True if authentication link is required in response payload based on above customer’s identifier

Allowed: true┃false

RESPONSE

application/json

Field

Type

Description

string

Unique ID to identify mandates provided by Digio.

mandate_id

string

Unique ID to identify mandates provided by Digio.

state

enum

➔ 'partial': 'signed': 'expired': 'auth_success': 'auth_failed': 'cancelled': 'revoked':

Allowed: partial┃complete┃signed┃expired┃auth_success┃auth_failed┃cancelled┃revoked

type

enum

➔ Use case of mandate

Allowed: CREATE┃AMEND

- mandate_details

object

Details of mandate

file_name

string

Name of file shared with the bank

customer_identifier

string

Identifier for customer, could be email or mobile number

customer_name

string

Name of customer

customer_ref_number

string

Unique Reference Number identifier the customer

scheme_ref_number

string

Unique number maintained by Corporate for the reconciliation

customer_mobile

string

Mobile number of customer

customer_email

string

Customer email number

auth_type

enum

➔ Mode of authentication used for mandate

Allowed: api┃esign┃physical┃any┃upi

authentication_time

date-time

Timestamp of mandate authentication

is_recurring

boolean

Denotes whether it is a recurring mandate or not

frequency

enum

➔ In case of recurring mandate, denotes the frequency.

Allowed: ADHO┃INDA┃DAIL┃WEEK┃MNTH┃QURT┃MIAN┃YEAR┃ONETIME┃BIMN

first_collection_date

date-time

Date of first debit

final_collection_date

date-time

Date of last debit

collection_amount

number

For fixed amount mandate, this denotes the amount

maximum_amount

number

Maximum amount that may be collected from the customer's account

customer_account_number

string

Masked account number of customer

customer_account_type

enum

➔ Type of bank account of customer

Allowed: savings┃current┃cc┃sb_nre┃sb_nro┃other

destination_bank_id

string

IFSC code of customer's bank account

destination_bank_name

string

Name of customer's bank

sponsor_bank_name

string

Name of sponsor's bank account

npci_txn_id

string

Transaction ID in reference to NPCI

- sub_user

object

string

Unique ID for sub-user

identifier_value

string

Identifier for sub-user, this is generally emailID or mobile number

identifier

enum

➔ This denotes what type of identifier was used

Allowed: email┃mobile┃unknown

email_id

string

Sub-user's email id, if registered

mobile

string

Subuser's mobile number

umrn

string

UMRN of the mandate registered

created_at

date-time

Timestamp at which mandate was created

updated_at

date-time

Last modification timestamp of the mandate

mode

enum

➔ Mode of mandate authentication

Allowed: api┃esign┃physical┃any┃upi

auth_sub_mode

enum

➔ In case of API mandate, sub auth mode type

Allowed: net_banking┃debit┃aadhaar

- service_provider_details

object

Details of service provider

service_provider_name

string

Service provider name

service_provider_utility_code

string

Utility code of service provider

is_enabled_for_aadhaar_auth

boolean

It is only applicable for API mandate and it returns true/false. If the sponsor bank supports authentication using aadhaar then it returns true, else it returns false.

- access_token

object

created_at

date-time

'yyyy-mm-dd hh:mm:ss': Timestamp of generation

entity_id

string

Unique identifier of the parent entity the access token belongs to

string

Unique identifier referencing an access token

valid_till

date-time

DateTime at which the access token expires. New token can be generated when expired with the access token generation API mentioned in the document.

npci_auth_failed_error

string

Failure reason if shared by NPCI after rejecting a request at NPCI gateway level

npci_auth_reject_reason

string

Failure reason if shared by bank post NPCI gateway acceptence