---
title: "Initiate Mandate"
method: POST
path: "/subscription/mandate"
tags: ["Mandate"]
---

# Initiate Mandate

`POST /subscription/mandate`

## Request

- Base URL: `https://services.jiopay.co.in/api`
- URL: `https://services.jiopay.co.in/api/subscription/mandate`
- Auth: HTTP bearer

Creates a recurring-payment mandate (UPI AutoPay or Card Standing Instruction). Two request shapes are supported depending on the flow:

- **Seamless** (`mandates[0].isSeamless: "1"`): `client_id` at the top level, mandate fields wrapped in a `mandates` array. Response returns a `redirectURI` for the customer to complete authentication.
- **Non-seamless** (`isSeamless: "0"`): all fields flat at the top level, no `mandates` wrapper. Response returns a generated `mandate_link` instead.

## Request body

- union
  - SeamlessMandateRequest: Seamless flow: client_id at the top level, mandate fields wrapped in a `mandates` array.
    - `client_id` string, required: Client identifier.
    - `mandates` MandateItemFields[], required
      - `isSeamless` '0' | '1', required: 1 for the seamless flow, 0 for the redirect/non-seamless flow.
      - `customer_ref_id` string: Merchant's reference ID for the customer.
      - `payment_method` string[], required: One or more payment methods for the mandate.
      - `amount_type` 'MAX' | 'FIXED', required: MAX = ceiling amount; FIXED = fixed amount charged.
      - `amount` string, required: Mandate amount.
      - `authAmount` string: Amount for the first debit during mandate creation.
      - `frequency` 'OT' | 'DL' | 'AS' | 'WK' | 'BM' | 'MT' | 'QT' | 'HY' | 'YR', required: OT = one-time (UPI only), DL = daily, AS = as-presented, WK = weekly, BM = bi-monthly, MT = monthly, QT = quarterly, HY = half-yearly, YR = yearly.
      - `start_date` string, required: Mandate start date.
      - `end_date` string, required: Mandate end date.
      - `collectByDate` string: Required for UPI. Date until which the mandate can be approved; max 45 days from today.
      - `subscription_refid` string, required: Merchant's unique subscription reference ID.
      - `consent` boolean, required: Customer consent flag.
      - `customer_name` string: Customer name.
      - `customer_mobile` string: Customer mobile number.
      - `customer_email` string: Customer email address.
      - `autoExecute` 'Y' | 'N', required: Auto-execute flag. Default N.
      - `blockfund` 'Y' | 'N': Block-fund flag.
      - `debitDay` string, required: WEEKLY: 1(Mon)–7(Sun). FORTNIGHTLY: 1–15. MONTHLY/BIMONTHLY/QUARTERLY/HALFYEARLY/YEARLY: 1–30/31.
      - `debitRule` string, required: BF/ON/AF/NA. ONETIME, DAILY and ASPRESENTED frequencies use NA.
      - `remark` string: Free-text remark.
      - `purpose` string, required: Purpose of the mandate.
      - `revokable` 'Y' | 'N', required: Whether the mandate can be revoked. MCC dependent.
      - `is_vpa` string: VPA (UPI ID) related flag. Likely Y/N based on similar fields, though not explicitly enumerated in the source.
      - `card` MandateCard: Required when payment_method includes CARD.
        - `cardNo` string, required: Card number.
        - `cardExpiryMonth` string, required: MM.
        - `cardExpiryYear` string, required: YYYY.
        - `cvv` string, required: CVV.
        - `cardHolderName` string, required: Name on card.
      - `payerVA` string: Required for UPI. Payer's Virtual Payment Address (UPI ID).
      - `udfFields` MandateUdfFields: Merchant-defined fields (udf_1–udf_14), echoed back in the response. Confirmed by the authoritative spec as the correct request-side naming (supersedes an earlier udf21–udf32 form seen elsewhere).
        - `udf_1` string
        - `udf_2` string
        - `udf_3` string
        - `udf_4` string
        - `udf_5` string
        - `udf_6` string
        - `udf_7` string
        - `udf_8` string
        - `udf_9` string
        - `udf_10` string
        - `udf_11` string
        - `udf_12` string
        - `udf_13` string
        - `udf_14` string
      - `subscription_details` MandateSubscriptionDetails: Marked 'Not to be passed' in the source spec for all three fields — send as empty string or omit.
        - `plan_id` string: Not to be passed — send as empty string or omit.
        - `plan_name` string: Not to be passed — send as empty string or omit.
        - `plan_description` string: Not to be passed — send as empty string or omit.
      - `return_url` string: URL to redirect the customer to after mandate registration.
      - `allow_first_debit` 'Y' | 'N': Whether the first debit is allowed.
      - `refund_auth_amount` 'Y' | 'N': Whether the authentication amount should be refunded.
      - `requestType` 'C', required
      - `validatePayerAccFlag` 'Y' | 'N', required: Default N. Y if the payer account needs to be validated (TPV).
      - `link_expiry` integer: Mandate registration link expiry, in days. Default 7.
      - `link_expiry_time` string: Explicit link expiry time.
      - `send_sms` 'Y' | 'N': Send mandate registration SMS to the customer.
      - `send_email` 'Y' | 'N': Send mandate registration email to the customer.
      - `secureHash` string, required: HMAC-SHA256 signature, computed client-side before sending and validated server-side (auto-generated by the caller, not a value you choose). Algorithm: remove any existing secureHash, sort the remaining top-level keys alphabetically, join String(value).trim() per key with `|`, then HMAC-SHA256 the resulting string with your client_secret, hex-encoded. A second variant used by some endpoints strips comments from the raw body first and JSON-stringifies object values instead of String()-converting them — confirm which variant applies with the JPSL integration team before implementing.
  - NonSeamlessMandateRequest: Non-seamless flow: client_id and all mandate fields are flat at the top level — no `mandates` array wrapper.
    - `client_id` string, required: Client identifier.
    - `isSeamless` '0' | '1', required: 1 for the seamless flow, 0 for the redirect/non-seamless flow.
    - `customer_ref_id` string: Merchant's reference ID for the customer.
    - `payment_method` string[], required: One or more payment methods for the mandate.
    - `amount_type` 'MAX' | 'FIXED', required: MAX = ceiling amount; FIXED = fixed amount charged.
    - `amount` string, required: Mandate amount.
    - `authAmount` string: Amount for the first debit during mandate creation.
    - `frequency` 'OT' | 'DL' | 'AS' | 'WK' | 'BM' | 'MT' | 'QT' | 'HY' | 'YR', required: OT = one-time (UPI only), DL = daily, AS = as-presented, WK = weekly, BM = bi-monthly, MT = monthly, QT = quarterly, HY = half-yearly, YR = yearly.
    - `start_date` string, required: Mandate start date.
    - `end_date` string, required: Mandate end date.
    - `collectByDate` string: Required for UPI. Date until which the mandate can be approved; max 45 days from today.
    - `subscription_refid` string, required: Merchant's unique subscription reference ID.
    - `consent` boolean, required: Customer consent flag.
    - `customer_name` string: Customer name.
    - `customer_mobile` string: Customer mobile number.
    - `customer_email` string: Customer email address.
    - `autoExecute` 'Y' | 'N', required: Auto-execute flag. Default N.
    - `blockfund` 'Y' | 'N': Block-fund flag.
    - `debitDay` string, required: WEEKLY: 1(Mon)–7(Sun). FORTNIGHTLY: 1–15. MONTHLY/BIMONTHLY/QUARTERLY/HALFYEARLY/YEARLY: 1–30/31.
    - `debitRule` string, required: BF/ON/AF/NA. ONETIME, DAILY and ASPRESENTED frequencies use NA.
    - `remark` string: Free-text remark.
    - `purpose` string, required: Purpose of the mandate.
    - `revokable` 'Y' | 'N', required: Whether the mandate can be revoked. MCC dependent.
    - `is_vpa` string: VPA (UPI ID) related flag. Likely Y/N based on similar fields, though not explicitly enumerated in the source.
    - `card` MandateCard: Required when payment_method includes CARD.
      - `cardNo` string, required: Card number.
      - `cardExpiryMonth` string, required: MM.
      - `cardExpiryYear` string, required: YYYY.
      - `cvv` string, required: CVV.
      - `cardHolderName` string, required: Name on card.
    - `payerVA` string: Required for UPI. Payer's Virtual Payment Address (UPI ID).
    - `udfFields` MandateUdfFields: Merchant-defined fields (udf_1–udf_14), echoed back in the response. Confirmed by the authoritative spec as the correct request-side naming (supersedes an earlier udf21–udf32 form seen elsewhere).
      - `udf_1` string
      - `udf_2` string
      - `udf_3` string
      - `udf_4` string
      - `udf_5` string
      - `udf_6` string
      - `udf_7` string
      - `udf_8` string
      - `udf_9` string
      - `udf_10` string
      - `udf_11` string
      - `udf_12` string
      - `udf_13` string
      - `udf_14` string
    - `subscription_details` MandateSubscriptionDetails: Marked 'Not to be passed' in the source spec for all three fields — send as empty string or omit.
      - `plan_id` string: Not to be passed — send as empty string or omit.
      - `plan_name` string: Not to be passed — send as empty string or omit.
      - `plan_description` string: Not to be passed — send as empty string or omit.
    - `return_url` string: URL to redirect the customer to after mandate registration.
    - `allow_first_debit` 'Y' | 'N': Whether the first debit is allowed.
    - `refund_auth_amount` 'Y' | 'N': Whether the authentication amount should be refunded.
    - `requestType` 'C', required
    - `validatePayerAccFlag` 'Y' | 'N', required: Default N. Y if the payer account needs to be validated (TPV).
    - `link_expiry` integer: Mandate registration link expiry, in days. Default 7.
    - `link_expiry_time` string: Explicit link expiry time.
    - `send_sms` 'Y' | 'N': Send mandate registration SMS to the customer.
    - `send_email` 'Y' | 'N': Send mandate registration email to the customer.
    - `secureHash` string, required: HMAC-SHA256 signature, computed client-side before sending and validated server-side (auto-generated by the caller, not a value you choose). Algorithm: remove any existing secureHash, sort the remaining top-level keys alphabetically, join String(value).trim() per key with `|`, then HMAC-SHA256 the resulting string with your client_secret, hex-encoded. A second variant used by some endpoints strips comments from the raw body first and JSON-stringifies object values instead of String()-converting them — confirm which variant applies with the JPSL integration team before implementing.

## Response `200`

OK

- InitiateMandateResponse
  - `statusCode` integer
  - `statusDesc` string
  - `summary` BatchSummary: Bulk-submission counters.
    - `total` integer
    - `success` integer
    - `failed` integer
    - `pending` integer: Count of items left pending in the batch (seen on Initiate Mandate; not present in every batch endpoint's response).
  - `results` union[]: Item shape depends on the request flow: seamless results include a redirect response object; non-seamless results include a generated link.
    - union
      - MandateResultItemSeamless
        - `statusCode` integer
        - `statusDesc` string
        - `subscription_refid` string
        - `response` MandateResultResponse: Seamless-flow result: a redirect URI for the customer to complete authentication.
          - `redirectURI` string: URL to redirect the customer to for mandate authentication.
          - `secureHash` string, nullable
          - `udfFields` MandateResponseUdfFields: Echo of a subset of the submitted udf_1–udf14 fields, under a udf21–udf32 naming convention. The exact mapping between request and response field numbers is not explained in the source — observed from one example, not guaranteed.
            - `udf21` string
            - `udf22` string
            - `udf23` string
            - `udf24` string
            - `udf25` string
            - `udf26` string
            - `udf27` string
            - `udf28` string
            - `udf29` string
            - `udf30` string
            - `udf31` string
            - `udf32` string
          - `merchantId` string
          - `responseDescription` string
          - `merchantTxnNo` string
          - `tranCtx` string: Transaction context token for the redirect flow.
          - `aggregatorId` string
          - `responseCode` string: R1000 = accepted for processing.
      - MandateResultItemNonSeamless: Non-seamless-flow result: a payment/mandate link the customer completes out-of-band.
        - `statusCode` integer
        - `statusDesc` string
        - `subscription_refid` string
        - `mandate_link` string: URL of the generated mandate/payment link.
        - `redirect_url` string: Echo of return_url.
        - `communication_status` string: Status of notification delivery.
        - `sms_sent` boolean
        - `email_sent` boolean

---

[API](https://skmtc.dev/jiopay/apis/subscription-hub.md) - [All operations](https://skmtc.dev/jiopay/apis/subscription-hub/llms.txt) - [OpenAPI document](https://skmtc.dev/jiopay/apis/subscription-hub/revisions/9da96f805941?raw)