e-RUPI Integration GuideVersion 2.0.0

Endpoint Details

This endpoint allows you to generate a new e-RUPI voucher by providing recipient and voucher details in the request body.

endpoint:
  path: /generator/generate-voucher
  method: POST
  headers:
    - name: X-API-KEY
      required: true
      description: API key for authentication.
    - name: X-API-SECRET
      required: true
      description: API secret for authentication.
    - name: X-PARTNER-ID
      required: true
      description: Partner ID for authentication.
  contentType: application/json
  requestBody:
    description: JSON object containing voucher and recipient details.
    required: true
  response:
    description: JSON object containing eRupiOrderId, voucher details, and status.

Endpoint Url:

/generator/generate-voucher

Note: Append this path to the appropriate base URL mentioned in the Prerequisites section.

Endpoint Description and Usage:

This endpoint is used by e-RUPI Generators to generate a new voucher. The request must include all required headers and a valid JSON body containing voucher details. Upon successful creation, the API returns an e-RUPI order ID and the associated voucher details.

Security

All requests to this endpoint must be authenticated using the required headers as specified in the Prerequisites section. Ensure that your API key and other credentials are kept secure and not exposed in client-side code. Failure to provide valid authentication headers will result in a 401 Unauthorized error.

Sample Request:

Here is an example of a cURL command to generate a voucher using this endpoint:

curl -X POST \
  https://{{base_url}}/generator/generate-voucher \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret" \
  -H "X-PARTNER-ID: your-partner-id" \
  -d '{
    "denomination": 1000,
    "mobileNumber": "9876543210",
    "orderId": "order_123456",
    "purposeCode": "PC001",
    "recipientName": "John Doe",
    "mandateName": "Mandate for John Doe",
    "mandateFrequency": "ONE_TIME",
    "startDate": "2026-01-01", // Optional
    "expiryDate": "2026-12-31" // Optional
  }'

Request Body

The POST request to the e-RUPI API must include a JSON payload with the following fields:

{
  "denomination": 1000,
  "mobileNumber": "9876543210",
  "orderId": "order_123456",
  "purposeCode": "PC001",
  "recipientName": "John Doe",
  "mandateName": "Mandate for John Doe",
  "mandateFrequency": "ONE_TIME",
  "startDate": "2026-01-01", // Optional
  "expiryDate": "2026-12-31" // Optional
}

Request Schema (YAML)

The request schema for generating a voucher is as follows:

parameters:
  - name: denomination
    in: body
    description: Amount of the voucher in INR.
    required: true
    schema:
      type: number

  - name: mobileNumber
    in: body
    description: Recipient's mobile number in 10-digit format.
    required: true
    schema:
      type: string

  - name: orderId
    in: body
    description: Unique order identifier for this transaction.
    required: true
    schema:
      type: string

  - name: purposeCode
    in: body
    description: Code representing the purpose of the voucher.
    required: true
    schema:
      type: string

  - name: recipientName
    in: body
    description: Full name of the voucher recipient.
    required: true
    schema:
      type: string

  - name: mandateName
    in: body
    description: Name of the voucher.
    required: true
    schema:
      type: string

  - name: mandateFrequency
    in: body
    description: Indicates if the voucher can be used once or multiple times. (ONE_TIME / MULTIPLE)
    required: true
    schema:
      type: string

  - name: startDate
    in: body
    description: |
      Start date of the voucher in YYYY-MM-DD format. Optional.
      - If omitted, defaults to today if expiryDate is provided.
      - If both startDate and expiryDate are omitted, defaults are assigned by voucher policy.
      - Must not exceed 365 days difference with expiryDate.
    required: false
    schema:
      type: string
      format: date

  - name: expiryDate
    in: body
    description: |
      Expiration date of the voucher in YYYY-MM-DD format. Optional.
      - If omitted, defaults are assigned by voucher policy.
      - Must not exceed 365 days difference with startDate.
    required: false
    schema:
      type: string
      format: date

Success Response

When the voucher is successfully generated, the API returns a JSON object containing the voucher details:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Voucher generated successfully",
  "result": {
    "eRupiOrderId": "5c8c3469-807f-45ea-b058-9ee36d255968",
    "voucher": {
      "umn": "EDAkkwR871cOs1oZUCaiwGBLvZ8vdUHY@ypay",
      "amount": "1",
      "balance": "1",
      "voucherCreatedAt": "2025-09-16T18:30:00.000Z",
      "voucherExpiryAt": "2026-09-16T18:30:00.000Z",
      "mobileNumber": "7007447101",
      "voucherStatus": "CREATED",
      "mandateName": "Mandate for John Doe",
      "voucherFrequency": "ONE_TIME"
    }
  }
}

Error Response

If there is an error with the request, the API will return a JSON object with error details:

{
  "status": {
    "code": "400",
    "error": true
  },
  "message": "Error message describing the issue",
  "result": null
}

Response Schema (YAML)

The response schema for both success and error responses is as follows:

parameters:
  - name: status
    in: body
    description: Contains response metadata.
    required: true
    schema:
      type: object
      properties:
        code:
          type: string
          description: HTTP-style status code.
        error:
          type: boolean
          description: Indicates if the API encountered an error.

  - name: message
    in: body
    description: Human-readable message describing the result or error.
    required: true
    schema:
      type: string

  - name: result
    in: body
    description: Contains details of the result in case of success; will be null in case of an error.
    required: true
    schema:
      type: object
      nullable: true
      properties:	
        eRupiOrderId:
          type: string
          description: Unique ID for the order.
        voucher:
          type: object
          description: Object containing voucher information.
          properties:
            umn:
              type: string
              description: Unique Merchant Number.
            amount:
              type: string
              description: Amount of voucher in INR.
            balance:
              type: string
              description: Remaining balance in INR.
            voucherCreatedAt:
              type: string
              format: date-time
              description: Creation timestamp.
            voucherExpiryAt:
              type: string
              format: date-time
              description: Expiry timestamp.
            mobileNumber:
              type: string
              description: Recipient's mobile number.
            voucherStatus:
              type: string
              description: Status of voucher (CREATED, REDEEMED, etc.).
            mandateName:
              type: string
              description: Voucher name.
            voucherFrequency:
              type: string
              description: ONE_TIME or MULTIPLE; indicates single-use or multiple-use.