UPI Merchant Stack

Merchant Onboarding

This section provides a comprehensive, step-by-step guide to merchant onboarding on Payment Gateway. From the initial step of receiving merchant credentials to hitting the APIs, the complete onboarding process is explained in this section.

Step 1 : Merchant Credentials

Once a Bank Partner is chosen, merchant will be required to complete an onboarding form. Upon submission of the form with the necessary details, Juspay will then provide the following merchant credentials which are required for making API calls. Here’s a quick understanding of the credentials that we share.

  1. Merchant Id : A unique identifier for the Merchant in the PSP system.

  2. Merchant Channel Id : Unique id for the channel via which request is made.

  3. Merchant VPA : This is the Virtual Payment Address assigned to the merchant for receiving payments.

  4. MCC : A 4-digit Merchant Category Code used to categorize the payee.

  5. KID : A unique Key ID to identify the public-private key pair used for signature generation within the PSP system.

  6. PG Public Key : This is the PSP's public key, employed for the verification of API responses and callbacks.

Error

  1. For merchants with different LOBs(Line of Business), separate VPA needs to be created for each use case and with correct MCC.

  2. VPA should only contain a-z, 0-9, . (dot), - (hyphen).

  3. Once the merchant receives the details mentioned above, the merchant will be required to provide a Merchant Callback URL for receiving Webhooks and the Merchant Public Key for verifying the requests sent by the merchant. After these details are shared, Juspay will enable the merchant and can start hitting the APIs. For guidance on generating a Public-Private key pair and understanding the callback URL, please refer below.

Step 2 : Generate API Keys

We use JSON Web Signature (JWS) to ensure the integrity of data exchanged between merchant and our system. Private key is used to generate the JWS Signature and Public key is used for verifying it. It is crucial to securely store the Private Key within a cryptographic vault on the merchant's servers and under no circumstances should the Private Key be exposed to the client or any external parties.

Here are the step-by-step instructions to generate a 2048 bit public-private key pair(KeyFormat-PEM).

  1. Generating Private Key

    To generate the Private Key, run the below command on terminal.

    The private key generated will be stored as a file named ‘privateKey.pem’ and is to be used to generate the Public key using the procedure given below.

  2. Generating Public Key

    Public key is always generated on top of the private key as they both come in pair. To generate the Public key, run the below command on the terminal.

    The public key generated will be stored as a file named ‘publicKey.pem’ and is required to be shared with payment gateway for verifying the requests sent by the merchant.

Step 3 : Callback URL

For every API call made, we provide a callback (commonly known as a webhook) to your server. These callbacks serve as direct notifications, updating you on events status for transactions, refunds etc. Configuring callbacks remains is mandatory step in our process. As a merchant, it is required to share your designated callback URL with Juspay to receive these callbacks for API calls.

UAT Testing App

UPI App for UAT testing will be provided over the merchant contact number once UAT onboarding is completed, only supported on android devices. User needs to install & register for creating VPA. This app can be used for Intent, Collect & Mandates testing during API Integration process.

Merchant Dashboard

Dashboard can be used for Analytics, Order Search, Dispute Management, Reports(MIS & Settlement files).

Note

For automation of Reports(MIS & Settlement files) via SFTP. Merchant’s server Username & SSH Public Key need to be shared with PSP/Bank for whitelisting.

  • MIS will have both SUCCESS & FAILURE status of all transactions/refunds, for 24 hr cycle starting at 12am.
    Sample MIS file: MERCHANTMID-MIS-REFUND-REPORT-DDMMYYYY.csv

  • SR will have only SUCCESS status of all transactions/refunds, for 24 hr cycle starting at 8am.
    Sample SR file: UPI_YP_SR_MERCHANTMID_YYYYMMDD.csv

Contact Us

Should you have any questions or clarifications, please feel free to reach out to our dedicated team. We are always happy to help!

For any Integration queries, please reach out to upi.integration@juspay.inlink icon

For any Post-Settlement queries, be it reconciliation or disputes, please reach out to reconops@juspay.inlink icon

For any Production queries, be it technical or general, please reach out to upimerchantsuccess@juspay.inlink icon

For any escalation / business queries, please reach out to product.upi@juspay.inlink icon / upi.biz@juspay.inlink icon