Introduction

Express Checkout APIs are built around basic HTTP communication and closely follows the standards of REST. While the URL themselves are not specific to resources, the URL path is intuitive to reflect the action performed by the API.

API Endpoint

Authentication

Below are the details on the two mode of Authentication that Juspay support.

API Key:

All the APIs except POST /txns use Basic HTTP authentication scheme to authenticate the requests and identify your account. API key is generally used for the server side API calls. The API key can be obtained from the Juspay dashboard. Provide your API key as the basic auth username value. You do not need to provide a password. If its passed as Authorization in the header then it should be the Basic auth of Base64 encoded value of API Key.

Transaction POST /txns API is exempted from authentication so that the card numbers (sensitive data) can be posted from your servers to JusPay’s servers if you are PCI Compliant

🚧

Note: API Key is like the password to your account. You must never send this information to browser or application clients. Also, do not publish your API Key in publicly accessible areas such as Git repositories, Android/iOS clients, support forums, etc.

Sample request

curl --location --request POST 'https://api.juspay.in/orders' \
--header 'Authorization: Basic QkIwQjdwdssjweewfqpkddNzBBMUE2Og=='

curl https://api.juspay.in/orders \
    -u "$your_api_key:"

Client Auth Token

Client Auth Token is another mode of Authentication. The client auth token is a 15min valid token which can be generated from create order or Get/create customer API (Details provided in the respective section). This token can be used for client side authentication ie for SDK integration.

Header

-H 'Content-Type: application/x-www-form-urlencoded'
-H 'x-merchantid:$your_merchantId'

The request should always be in application/x-www-form-urlencoded format. Using different format for request submission might lead to request failure.

The x-merchantid is a mandatory params in all the API call. The value is same as the merchant_id/ username provided by Juspay.

Version

Proper version headers ensure that we do not send any information that your client is not capable of handling. Our latest API version is 2021-03-25. The changelog for the revisions is given below.

2021-03-25
For this version, metadata params is included in refund block in order status response

2021-03-05
Rewards_breakup info will be present in order status response
RewardsBreakup
{ rewards_points_amount
, card_amount
}

2020-11-20
For this version, error_code param is included in refund block in order status response

2020-10-31
For this version, txn_sub_details param is included in order status response if txnObjectType == PARTIAL_CAPTURE.
If txn type is PREAUTH_AND_SETTLE, captured_amount, Refundable_amount params are included in order status response

2020-03-14
For this version the Metadata that is passed during the order creation will be present in order status response

2019-03-12
For this version, refund_source, refund_type params are included in refund block in order status response

2019-11-11
For this version Status in order status API Response can be AUTO_REFUNDED with status_id as 36 if transaction is auto refunded

2018-10-25
For this version, ‘gateway_reference_id’ param is included in order status response payload.

2018-09-20
For this version, 'initiated_by’ param is included in order refund whether the refund was initiated by API or from the dashboard

2018-07-16
Surcharge information is included in the order status response

2017-07-26
Chargebacks against the order will be included in the response payload.

2017-05-25
For this version, PG offer related params are included in the payment_gateway_response block.

2017-03-16
Refunds are marked as MANUAL_REVIEW if they remain in PENDING state for a considerably longer duration. Typically, network timeout errors at the time of the transaction will result in such state and most importantly, for gateways that do not provide automatic reconciliation.

2016-10-27
For this version, webhooks are posted whenever the payment is initiated for an order.

2016-07-19
For order payment failures, webhooks will be sent to your server. Remember to configure this version in the Webhook settings page.

2015-08-18
/order/status will respond with all the failed refunds too. Prior to this version, failed refunds were expressly excluded from the listing as clients did not have the capability to handle refunds in the failure state.

2015-01-09
Refunds in the pending state will have status PENDING. Prior to this, refund status PENDING was sent as SUCCESS.

Note: JusPay introduced PENDING status for refunds as a large number of PayU refunds were initially queued and the success of these refunds was not guaranteed.

Sample request

curl https://api.juspay.in/orders \
    -H "version: 2021-03-05" \
    -u "$your_api_key:"

curl --location --request POST 'https://api.juspay.in/orders' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'version: 2021-03-05' \
--header 'Authorization: Basic QkIwQjMyODuw767eq0NzBBMUE2Og=='