API Guide

This section provides a comprehensive overview of API Integration, including key components like API Endpoints, Request/Response/Callback Structure.

Section 1 : API Endpoints

To make API calls for your chosen Bank Partner, please use the endpoints provided to you during onboarding, depending on your environment. Insert these endpoints before the respective API URL path.

Section 2 : API Format

This section provides detailed understanding of different parts of the API. Further, each API-specific section includes detailed descriptions of the Request, Response, and associated callbacks.

Request Structure

This section provides a comprehensive breakdown of the core components that make up an API Request. This section gives understanding of Request Headers, Body and JWS Signature generation.

Request Headers

All the required headers for making API calls are as mentioned below.

Request Body

The request body contains essential data for the request, including the signature, payload, and protected in JSON format. Every request parameter is required for the API, unless stated otherwise. The data type of all parameters is string.

You can find a detailed guide on how to create the signature, payload, and protected in the upcoming section.

Request Body Generation - JWS

The signature for a request payload is generated using the RS256 JWS algorithm (a sample code has been attached below). This algorithm involves signing the JSON payload with the private key, which is stored on the merchant's server. It's important to note that all requests from the merchant must be signed using this private key.

The following snippets shows the way to create a signature over data required for the request.

On executing the above code by replacing the private key, payload, and KID, it will produce a response containing the signature, payload, and protected data. These elements make up the body of the API call. The sample response from the codes is attached below.

Sample Response of the JWS Code : Javascript

The response returned by Javascript code is to be passed as the request body while hitting the requests.

Sample Response of the JWS Code : Java

The given code produces a response containing a token separated by periods ('.'). This token is made up of three parts : the protected, the payload, and the signature. When you split the token on the periods ('.'), you get these three components. The first part is the "protected," the second part is the "payload," and the third part is the "signature." You can consider these parts as the request body for the API.

Sample Curl for Request

Below is a sample CURL request to access the APIs. You need to update the request headers with the merchant's credentials and set the request body with the JWS signature response obtained from the previous code section. This modified CURL request should be used to interact with the APIs.

JWE Encryption

Introduction

Currently Juspay uses signature based algorithms for inbound communication from UPI merchant partners. Juspay has added support for encryption of request/response bodies utilizing JSON Web Encryption (JWE) methodology for enhanced security based on Bank’s recommendation.

Solution Scope And Details

High-level Design And Changes

Exchanging Keys & Key-IDs

• A public-private key pair is generated by the merchant for the JWS use case. Merchant will use the private key for creating a signed JWS object for subsequent requests and pass on the public key to Juspay. In return, Juspay will provide a key-Id mapped to this public key (Let’s call this key-Id “JWS-KEY-ID”). This is a one-time activity. Juspay will use the acquired public key for verifying signed JWS objects.

• Another public-private key pair is generated by Juspay for the JWE use case. Juspay will pass on the public key and a mapped key-Id (Let’s call this key-Id “JWE-KEY-ID”) to the merchant. This is a one-time activity. Merchant will use the acquired public key for creating encrypted JWE request. Juspay will use the private key for decrypting the JWE request.

Exchanging Key Mechanism

• We’ll leverage SFTP mechanism for the key sharing between each other. Juspay will post the public key on the SFTP exposed by Meta. Same mechanism can be used for key rotation after going live

Request Flow

Generating the JWS+JWE request

Response Structure

Response Headers

Here is a list of headers that are sent with every response.

Response Body

Below is a sample API response format which will be obtained from an executed API request. This example serves to showcase the structure and content of the responses received from the API calls.

Every API response will include a JSON-formatted response body. Within this response, there is a key called "status" which can have one of two values: "SUCCESS" or "FAILURE." This "status" key helps determine whether the query was successful or not.

When the "status" is "SUCCESS" it means that a valid payload is included in the response. On the other hand, if the "status" is "FAILURE" the response will contain two additional keys: "responseCode" and "responseMessage." These keys provide information about why the query failed.

A detailed Part wise guide on handling different Status & Codes received during API hits from PSP system is available in Resource Section under Codes Guide.

Response Signature Validation - RSA SHA256

Along with the response, PSP shares response signature which can be verified using the PSP public key as shared during the onboarding. The algorithm used for creating the signature is SHA256 RSA with PSS padding. Following snippet shows how merchant has to validate the signature at their end.

Callback Structure

Callback Headers

Here is a list of headers that are sent with every callback.

Callback Signature Validation - RSA SHA256

Along with every callbacks, PSP shares payload signature which can be verified using the PSP public key as shared during the onboarding. The algorithm used for creating the signature is SHA256 RSA with PSS padding. Following snippet shows how merchant has to validate the signature at their end. The keys in JSON body will be in alphabetically sorted order.

Callback IP Whitelisting

At the time of onboarding, you will be provided with the IPs through which callbacks are sent. Merchants are required to whitelist these IPs in order to receive callbacks from Juspay.