NAV

Introduction

API libraries

Libraries for Express Checkout APIs are available in Python, Ruby and PHP.

API Endpoint

https://api.juspay.in

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.

Content Request Headers

curl https://api.juspay.in/orders
-H "Accept: application/json" \
-H "ContentType: x-url-form-encoded "

Server SDK sources

Language Project location
Python https://bitbucket.org/juspay/expresscheckout-python-client
Ruby https://bitbucket.org/juspay/expresscheckout-ruby-client
PHP https://bitbucket.org/juspay/expresscheckout-php-sdk
Java https://bitbucket.org/juspay/expresscheckout-java-sdk

Authentication

AUTHENTICATE YOUR REQUEST

curl https://api.juspay.in/orders \
   -u 31080C4D8F6A45FB8979266E327503C8:

#curl** tool uses the option `-u` to accept the username and password. The username & password are separted by `:`. Notice that the password is empty in the above request.
import juspay as Juspay
Juspay.api_key = 'ACE565EAB40F4AA78853F03F496F7DB5'
require 'expresscheckout'
$api_key = 'ACE565EAB40F4AA78853F03F496F7DB5'
JuspayEnvironment::init()
->withApiKey("ACE565EAB40F4AA78853F03F496F7DB5")
JuspayEnvironment.withApiKey
("ACE565EAB40F4AA78853F03F496F7DB5");

Ensure that you replace this API Key with the key that pertains to your account.

All the APIs except POST /txns use Basic HTTP authentication scheme to authenticate the requests and identify your account. API key can be obtained from https://merchant.juspay.in/settings/api-key. Provide your API key as the basic auth username value. You do not need to provide a password.

Transaction POST /txns API is exempted from authentication so that the card numbers (sensitive data) can be posted from the browsers or application clients (Android or iOS) directly to JusPay’s servers.

Note: API Key is like 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..

Version

Include version header

curl https://api.juspay.in/orders \
    -H "version: 2016-07-19" \
    -u "$api_key:"

Proper version headers ensure that we do not send any information that your client is not capable of handling. Our latest API version is 2016-10-27. Changelog for the revisions are given below.

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 failure state.

2015-01-09

Refunds in pending state will have status PENDING. Prior to this, refund status PENDING was sent as SUCCESS.

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

Support

Should you have any questions, feel free to reach us at support@juspay.in.

Note: Remember to send your merchant_id in the subject line of the email so that we can help you better.

Customer

Represents a customer who is using your service.

Create customer

Create a new customer object. You may invoke this method whenever someone registers in your website or App. JusPay will respond with an ID that you can persist in your Database. Pass this ID at the time of order creation to ensure proper linking of orders/payments belonging to a customer.

Definition

POST
https://api.juspay.in/customers
Customer.create(Map params);

Example Request

curl -X POST https://api.juspay.in/customers \
-u api_key: \
-d "object_reference_id=customer@gmail.com" \
-d "mobile_number=9988776655" \    
-d "email_address=customer@gmail.com" \
-d "first_name=John" \
-d "last_name=Smith" \
-d "mobile_country_code=91"
Juspay.Customers.add(
        object_reference_id='customer@gmail.com', 
        mobile_number='9988776655', 
        email_address='customer@gmail.com', 
        first_name='John', 
        last_name='Smith', 
        mobile_country_code='91'
)
Customers.create(
        :object_reference_id => 'customer@gmail.com', 
        :mobile_number => '9988776655', 
        :email_address => 'customer@gmail.com', 
        :first_name => 'John', 
        :last_name => 'Smith', 
        :mobile_country_code => '91'
)
$params = array ();
$params['object_reference_id']="customer@gmail.com"; 
$params['mobile_number']="9988776655"; 
$params['email_address']="customer@gmail.com"; 
$params['first_name']="John"; 
$params['last_name']="Smith"; 
$params['mobile_country_code']="91";
$customer = Customer::create($params);
Map<String, Object> params = new LinkedHashMap();
params.put("object_reference_id", "customer@gmail.com");
params.put("mobile_number", "9988776655");
params.put("email_address", "customer@gmail.com");
params.put("first_name", "John");
params.put("last_name", "Smith");
params.put("mobile_country_code", "91");
Customer customer = Customer.create(params);

Request Parameters

Field Type Description
object_reference_id
Required
String Unique ID that you use to represent the customer in your database. This must be atleast 8 characters and must be unique. The typical value for this field would be email address or mobile number or auto increment ID that you have in your DB.
mobile_number
Required
String Customer’s mobile number.
email_address
Required
String Customer’s e-mail address.
first_name
String Customer’s first name.
last_name
String Customer’s last name.
mobile_country_code
String Mobile country code. No need to prefix “+”.

Example Response

{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776655",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-08-02T08:07:52+0000",
   "email_address": "customer@gmail.com",
   "first_name": "John",
   "last_name": "Smith",
   "mobile_country_code": "91",
}
<Customer>
{
  'id': u'cst_om2l6ctlptxwxuzj',
  'object': u'customer',
  'object_reference_id': u'customer@gmail.com',
  'mobile_number': u'9988776655',
  'date_created': u'2016-08-02T08:07:52+0000',
  'last_updated': u'2016-08-02T08:07:52+0000',
  'email_address': u'customer@gmail.com',
  'first_name': u'John',
  'last_name': u'Smith',  
  'mobile_country_code': u'91'
}
<Customers::Customer:0x00000a>
{
  @id = "cst_om2l6ctlptxwxuzj",
  @object = "customer",
  @object_reference_id = "customer@gmail.com",
  @mobile_number = "9988776655",
  @date_created = "2016-08-02T08:07:52+0000",
  @last_updated = "2016-08-02T08:07:52+0000",
  @email_address = "customer@gmail.com",
  @first_name = "John",
  @last_name = "Smith",  
  @mobile_country_code = "91"
}
Customer Object
{
  [id] =>cst_om2l6ctlptxwxuzj
  [object] =>customer
  [object_reference_id] =>customer@gmail.com
  [mobile_number] =>9988776655
  [date_created] =>2016-08-02T08:07:52+0000
  [last_updated] =>2016-08-02T08:07:52+0000
  [email_address] =>customer@gmail.com
  [first_name] =>John
  [last_name] =>Smith  
  [mobile_country_code] =>91
}
@object in.juspay.model.Customer
JSON:
{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776655",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-08-02T08:07:52+0000",
   "email_address": "customer@gmail.com",
   "first_name": "John",
   "last_name": "Smith",
   "mobile_country_code": "91",
}

Response Parameters

Field Type Description
id String Customer ID generated by JUSPAY.
object String Object type of entity, in this case it’ll be customer.
object_reference_id String Customer ID defined by you.
mobile_number String Customer’s mobile number.
date_created String Date creation of customer entity.
last_udpated String Last updated date of customer entity.
email_address String Customer’s e-mail address.
first_name String Customer’s first name.
last_name String Customer’s last name.
mobile_country_code String Mobile country code.

Get customer

This will return customer entity for given identifier.

Definition

GET
https://api.juspay.in/customers/:customer_id
Customer.get(String customerId);

Example Request

curl -X GET https://api.juspay.in/customers/customer@gmail.com \
-u api_key:
Juspay.Customers.get(customer_id='customer@gmail.com')
Customers.get(:customer_id => 'customer@gmail.com')
$customer_id = "customer@gmail.com"
$customer = Customer::get($customer_id);
String customerId = "customer@gmail.com";
Customer customer = Customer.get(customerId);

URL Embedded Parameter

Field Type Description
customer_id
Required
String Use the ID that is generated by JUSPAY during customer creation. You may also send the value that you sent in object_reference_id at the time of creating the customer.

Example Response

{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776655",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-08-02T08:07:52+0000",
   "email_address": "customer@gmail.com",
   "first_name": "firstname",
   "last_name": "lastname",
   "mobile_country_code": "91",
}
<Customer>
{
  'id': u'cst_om2l6ctlptxwxuzj',
  'object': u'customer',
  'object_reference_id': u'customer@gmail.com',
  'mobile_number': u'9988776655'
  'date_created': u'2016-08-02T08:07:52+0000',
  'last_updated': u'2016-08-02T08:07:52+0000',
  'email_address': u'customer@gmail.com',
  'first_name': u'firstname'
  'last_name': u'lastname',  
  'mobile_country_code': u'91'
}
<Customers::Customer:0x00000a>
{
  @id = "cst_om2l6ctlptxwxuzj",
  @object = "customer",
  @object_reference_id = "customer@gmail.com",
  @mobile_number = "9988776655",
  @date_created = "2016-08-02T08:07:52+0000",
  @last_updated = "2016-08-02T08:07:52+0000",
  @email_address = "customer@gmail.com",
  @first_name = "John",
  @last_name = "Smith",  
  @mobile_country_code = "91"
}
Customer Object
{
  [id] =>cst_om2l6ctlptxwxuzj
  [object] =>customer
  [object_reference_id] =>customer@gmail.com
  [mobile_number] =>9988776655
  [date_created] =>2016-08-02T08:07:52+0000
  [last_updated] =>2016-08-02T08:07:52+0000
  [email_address] =>customer@gmail.com
  [first_name] =>John
  [last_name] =>Smith  
  [mobile_country_code] =>91
}
@object in.juspay.model.Customer
JSON:
{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776655",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-08-02T08:07:52+0000",
   "email_address": "customer@gmail.com",
   "first_name": "John",
   "last_name": "Smith",
   "mobile_country_code": "91",
}

Response Parameters

Field Type Description
id String Customer ID generated by juspay.
object String Object type of entity, in this case it’ll be customer.
object_reference_id String Customer ID defined by you.
mobile_number String Customer mobile number.
date_created String Date creation of customer entity.
last_updated String Last updated date of customer entity.
email_address String Customer e-mail address.
first_name String Customer first name.
last_name String Customer fast name.
mobile_country_code String Customer mobile country code.

Update customer

Update customer entity.

Definition

POST
https://api.juspay.in/customers/:customer_id
Customer.update(String customerId, Map params);

Example Request

curl -X POST https://api.juspay.in/customers/cst_om2l6ctlptxwxuzj \
-u api_key: \
-d "mobile_number=9988776644" \    
-d "customer_email=customer@gmail.com" \
-d "first_name=Jon" \
-d "last_name=Snow" \
-d "mobile_country_code=91"
Juspay.Customers.update(
        customer_id='cst_om2l6ctlptxwxuzj', 
        mobile_number='9988776644', 
        customer_email='customer@gmail.com', 
        first_name='Jon', 
        last_name='Snow', 
        mobile_country_code='91'
)
Customers.update(
        :customer_id => 'cst_om2l6ctlptxwxuzj', 
        :mobile_number => '9988776644', 
        :customer_email => 'customer@gmail.com', 
        :first_name => 'Jon', 
        :last_name =>'Snow', 
        :mobile_country_code => '91'
)
$params = array (); 
$customer_id = "cst_om2l6ctlptxwxuzj"
$params['mobile_number']="9988776644"; 
$params['email_address']="customer@gmail.com"; 
$params['first_name']="Jon"; 
$params['last_name']="Snow"; 
$params['mobile_country_code']="91";
$customer = Customer::update($customer_id, $params);
String customerId = "cst_om2l6ctlptxwxuzj"
Map<String, Object> params = new LinkedHashMap();
params.put("first_name", "Jon");
params.put("last_name", "Snow");
params.put("mobile_country_code", "91");
params.put("mobile_number", "9988776644");
params.put("email_address", "customer@gmail.com");
Customer customer = Customer.update(customerId, params);

URL Embedded Parameter

Field Type Description
customer_id
Required
String Use the ID that is generated by JUSPAY during customer creation. You may also send the value that you sent in object_reference_id at the time of creating the customer.

Request Parameters

Field Type Description
mobile_number
String Customer mobile number.
email_address
String Customer e-mail address.
first_name
String Customer first name.
last_name
String Customer last name.
mobile_country_code
String Customer mobile country code.

Example Response

{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776655",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-09-02T07:05:10+0000",
   "email_address": "customer@gmail.com",
   "first_name": "Jon",
   "last_name": "Snow",
   "mobile_country_code": "91"
}
<Customer>
{
  'id': u'cst_om2l6ctlptxwxuzj',
  'object': u'customer',
  'object_reference_id': u'customer@gmail.com',
  'mobile_number': u'9988776644'
  'date_created': u'2016-08-02T08:07:52+0000',
  'last_updated': u'2016-09-02T07:05:10+0000',
  'email_address': u'customer@gmail.com',
  'first_name': u'Jon'
  'last_name': u'Snow',  
  'mobile_country_code': u'91'
}
<Customers::Customer:0x00000a>
{
  @id = "cst_om2l6ctlptxwxuzj",
  @object = "customer",
  @object_reference_id = "customer@gmail.com",
  @mobile_number = "9988776644",
  @date_created = "2016-08-02T08:07:52+0000",
  @last_updated = "2016-09-02T07:05:10+0000",
  @email_address = "customer@gmail.com",
  @first_name = "Jon",
  @last_name = "Snow",  
  @mobile_country_code = "91"
}
Customer Object
{
  [id] =>cst_om2l6ctlptxwxuzj
  [object] =>customer
  [object_reference_id] =>customer@gmail.com
  [mobile_number] =>9988776655
  [date_created] =>2016-08-02T08:07:52+0000
  [last_updated] =>2016-08-02T08:07:52+0000
  [email_address] =>customer@gmail.com
  [first_name] =>Jon
  [last_name] =>Snow  
  [mobile_country_code] =>91
}
@object in.juspay.model.Customer
JSON:
{
   "id": "cst_om2l6ctlptxwxuzj",
   "object": "customer",
   "object_reference_id": "customer@gmail.com",
   "mobile_number": "9988776644",
   "date_created": "2016-08-02T08:07:52+0000",
   "last_updated": "2016-08-02T08:07:52+0000",
   "email_address": "customer@gmail.com",
   "first_name": "Jon",
   "last_name": "Snow",
   "mobile_country_code": "91"
}

Response Parameters

Field Type Description
id String Customer ID generated by JUSPAY.
object String Object type of entity, in this case it’ll be customer.
object_reference_id String Customer id defined by merchant.
mobile_number String Customer mobile number.
date_created String Date creation of customer entity.
last_updated String Last updated date of customer entity.
email_address String Customer e-mail address.
first_name String Customer first name.
last_name String Customer last name.
mobile_country_code String Customer mobile country code.

Order

Create Order

Create an order that is a representation of your shopping cart. Order contains important information like amount, customer details, shipping address, billing address etc. Only after an order is created, payment can be started.

Note: You can also send custom data in the following fields: udf1, udf2, …, udf10.

Order create response now has payment links for web, mobile & iFrame. These links can directly be emailed or messaged to your customers. If you wish to use your own branding, then you can embed the iFrame link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.

Definition

POST
https://api.juspay.in/orders
Juspay.Orders.create()
Orders.create()
Order::create();
Order.create(Map params);

Example Request

curl -X POST https://api.juspay.in/orders \
-u api_key: \
-d "order_id=1418394476" \
-d "amount=100.00" \
-d "currency=INR" \
-d "customer_id=guest_user_101" \
-d "customer_email=customer@gmail.com" \
-d "customer_phone=9988665522" \
-d "product_id=prod-141833" \
-d "return_url=http://shop.merchant.com/payments/handleResponse" \
-d "description=Sample description" \
-d "billing_address_first_name=Juspay" \
-d "billing_address_last_name=Technologies" \
-d "billing_address_line1=Girija Building" \
-d "billing_address_line2=Ganapathi Temple Road" \
-d "billing_address_line3=8th Block, Koramangala" \
-d "billing_address_city=Bengaluru" \
-d "billing_address_state=Karnataka" \
-d "billing_address_country=India" \
-d "billing_address_postal_code=560095" \
-d "billing_address_phone=9988775566" \
-d "billing_address_country_code_iso=IND" \
-d "shipping_address_first_name=Juspay" \
-d "shipping_address_last_name=Technologies" \
-d "shipping_address_line1=Girija Building" \
-d "shipping_address_line2=Ganapathi Temple Road" \
-d "shipping_address_line3=8th Block, Koramangala" \
-d "shipping_address_city=Bengaluru" \
-d "shipping_address_state=Karnataka" \
-d "shipping_address_postal_code=560095" \
-d "shipping_address_phone=9962881912" \
-d "shipping_address_country_code_iso=IND" \
-d "shipping_address_country=India"
Juspay.Orders.create(
    order_id='1418394476',
    amount=100.00,
    currency='INR',
    customer_id='guest_user_101',
    customer_email='customer@gmail.com',
    customer_phone='9988665522',
    product_id='prod-141833',
    return_url='http://shop.merchant.com/payments/handleResponse',
    description='Sample description',
    billing_address_first_name='Juspay',
    billing_address_last_name='Technologies',
    billing_address_line1='Girija Building',
    billing_address_line2='Ganapathi Temple Road',
    billing_address_line3='8th Block, Koramangala',
    billing_address_city='Bengaluru',
    billing_address_state='Karnataka',
    billing_address_country='India',
    billing_address_postal_code='560095',
    billing_address_phone='9988775566',
    billing_address_country_code_iso='IND',
    shipping_address_first_name='Juspay',
    shipping_address_last_name='Technologies',
    shipping_address_line1='Girija Building',
    shipping_address_line2='Ganapathi Temple Road',
    shipping_address_line3='8th Block, Koramangala',
    shipping_address_city='Bengaluru',
    shipping_address_state='Karnataka',
    shipping_address_postal_code='560095',
    shipping_address_phone='9962881912',
    shipping_address_country_code_iso='IND',
    shipping_address_country='India'
)
Orders.create(
    :order_id=>'1418394476',
    :amount=>100.00,
    :currency=>'INR',
    :customer_id=>'guest_user_101',
    :customer_email=>'customer@gmail.com',
    :customer_phone=>'9988665522',
    :product_id=>'prod-141833',
    :return_url=>'http://shop.merchant.com/pay/handleResponse',
    :description=>'Sample description',
    :billing_address_first_name=>'Juspay',
    :billing_address_last_name=>'Technologies',
    :billing_address_line1=>'Girija Building',
    :billing_address_line2=>'Ganapathi Temple Road',
    :billing_address_line3=>'8th Block, Koramangala',
    :billing_address_city=>'Bengaluru',
    :billing_address_state=>'Karnataka',
    :billing_address_country=>'India',
    :billing_address_postal_code=>'560095',
    :billing_address_phone=>'9988775566',
    :billing_address_country_code_iso=>'IND',
    :shipping_address_first_name=>'Juspay',
    :shipping_address_last_name=>'Technologies',
    :shipping_address_line1=>'Girija Building',
    :shipping_address_line2=>'Ganapathi Temple Road',
    :shipping_address_line3=>'8th Block, Koramangala',
    :shipping_address_city=>'Bengaluru',
    :shipping_address_state=>'Karnataka',
    :shipping_address_postal_code=>'560095',
    :shipping_address_phone=>'9962881912',
    :shipping_address_country_code_iso=>'IND',
    :shipping_address_country=>'India'
)
    $params = array();
    $params['order_id'] = "1418394476";
    $params['amount'] = 100.00;
    $params['currency'] = "INR";
    $params['customer_id'] = "guest_user_101";
    $params['customer_email'] = "customer@gmail.com";
    $params['customer_phone'] = "9988665522";
    $params['product_id'] = "prod-141833";
    $params['return_url'] = "http://shop.merchant.com/payments/handleResponse";
    $params['description'] = "Sample description";
    $params['billing_address_first_name'] = "Juspay";
    $params['billing_address_last_name'] = "Technologies";
    $params['billing_address_line1'] = "Girija Building";
    $params['billing_address_line2'] = "Ganapathi Temple Road";
    $params['billing_address_line3'] = "8th Block, Koramangala";
    $params['billing_address_city'] = "Bengaluru";
    $params['billing_address_state'] = "Karnataka";
    $params['billing_address_country'] = "India";
    $params['billing_address_postal_code'] = "560095";
    $params['billing_address_phone'] = "9988775566";
    $params['billing_address_country_code_iso'] = "IND";
    $params['shipping_address_first_name'] = "Juspay";
    $params['shipping_address_last_name'] = "Technologies";
    $params['shipping_address_line1'] = "Girija Building";
    $params['shipping_address_line2'] = "Ganapathi Temple Road";
    $params['shipping_address_line3'] = "8th Block, Koramangala";
    $params['shipping_address_city'] = "Bengaluru";
    $params['shipping_address_state'] = "Karnataka";
    $params['shipping_address_postal_code'] = "560095";
    $params['shipping_address_phone'] = "9962881912";
    $params['shipping_address_country_code_iso'] = "IND";
    $params['shipping_address_country'] = "India";
    $order = Order::create($params);
Map<String, Object> params = new LinkedHashMap();
params.put("order_id","1418394476");
params.put("amount", 100.0);
params.put("currency", "INR");
params.put("customer_id", "guest_user_101");
params.put("customer_email", "customer@gmail.com");
params.put("customer_phone", "9988665522");
params.put("product_id", "prod-141833");
params.put("return_url", "http://shop.merchant.com/payments/handleResponse");
params.put("description", "Sample Description");
params.put("billing_address_first_name", "Juspay");
params.put("billing_address_last_name", "Technologies");
params.put("billing_address_line1", "Girija Building");
params.put("billing_address_line2", "Ganapathi Temple Road");
params.put("billing_address_line3", "8th Block, Koramangala");
params.put("billing_address_city", "Bengaluru");
params.put("billing_address_state", "Karnataka");
params.put("billing_address_country", "India");
params.put("billing_address_postal_code", "560095");
params.put("billing_address_phone", "9988775566");
params.put("billing_address_country_code_iso", "IND");
params.put("shipping_address_first_name", "Juspay");
params.put("shipping_address_last_name", "Technologies");
params.put("shipping_address_line1", "Girija Building");
params.put("shipping_address_line2", "Ganapathi Temple Road");
params.put("shipping_address_line3", "8th Block, Koramangala");
params.put("shipping_address_city", "Bengaluru");
params.put("shipping_address_state", "Karnataka");
params.put("shipping_address_country", "India");
params.put("shipping_address_postal_code", "560095");
params.put("shipping_address_phone", "9962881912");
params.put("shipping_address_country_code_iso", "IND");
params.put("shipping_address_country", "India");
Order order = Order.create(params);

Request Parameters

Field Type Description
order_id
Required
String Unique Identifier for the order.
amount
Required
Double Amount that the customer has to pay. Will accept double values with upto two decimal places. For example, 100.15 is valid input but 100.1532 is not valid.
currency String ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP.
Default value: INR
customer_id String String that uniquely identifies the customer. ID returned when you created customer object.
customer_email String Email address of the customer.
If the backend gateway requires it, then you must send this value.
customer_phone String Mobile number or fixed line number of the customer.
If the backend gateway requires it, then you must send this value.
description String Short description for the order. We send this information to the backend gateways whenever there is a provision for this.
product_id String An identifier for the product. Fits well for impulse purchase usecases.
gateway_id String Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
return_url String A fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters. This URL takes higher precedence over the common return URL configured in your account settings.
billing_address_first_name String First name in the billing address
billing_address_last_name String Last name in the billing address
billing_address_line1 String Line1 in the billing address
billing_address_line2 String Line2 in the billing address
billing_address_line3 String Line3 in the billing address
billing_address_city String Billing address city
billing_address_state String Billing address state
billing_address_country String Billing address country
billing_address_postal_code String Billing address postal code or zip code
billing_address_phone String Mobile or phone number in the billing address
billing_address_country_code_iso String ISO Country code
Default value: IND
shipping_address_first_name String First name in the shipping address
shipping_address_last_name String Last name in the shipping address
shipping_address_line1 String Line1 in the shipping address
shipping_address_line2 String Line2 in the shipping address
shipping_address_line3 String Line3 in the shipping address
shipping_address_city String Shipping address city
shipping_address_state String Shipping address state
shipping_address_country String Shipping address country
shipping_address_postal_code String shipping address postal code or zip code
shipping_address_phone String Mobile or phone number in the shipping address
shipping_address_country_code_iso String ISO Country code
Default value: IND

Example Response

{
  "status": "CREATED",
  "status_id": 1,
  "id": "ord_e294a26e66ad4336a992ceab81ad704c",
  "order_id": "1478851764",
  "payment_links": {
    "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
    "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
    "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
  }
}
<Order>
{
    'status': u'CREATED',
    'order_id': u'1418394476',
    'id': 'ord_805ab74ffe1245afb00b84d57cb18c65',
    'status_id': 1,
    <PaymentLink>
    {
        'web': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c',
        'mobile': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true',
        'iframe': u'https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c'
    }
}
<Orders::Order:0x00000a>
{
    @status = "CREATED",
    @status_id = 1,
    @id = "ord_805ab74ffe1245afb00b84d57cb18c65",
    @order_id = "1418394476",
    <PaymentLink:0x00000a>
    {
         @web: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
         @mobile: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
         @iframe: "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
    }
}
Order object
(
    [status] => 'CREATED'
    [status_id] => 1
    [id]: 'ord_805ab74ffe1245afb00b84d57cb18c65'
    [order_id] => 1418394476
    [PaymentLinks] => (
        [web]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c
        [mobile]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true
        [iframe]: https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c
      )
)
@object in.juspay.model.Order
JSON:
{
  "status": "CREATED",
  "status_id": 1,
  "id": "ord_805ab74ffe1245afb00b84d57cb18c65",
  "order_id": "1418394476"
  "payment_links": 
  {
    "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
    "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
    "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
  }
}

Response Parameters

Field Type Description
id String Unique ID generated by JusPay for the given order.
order_id String Given order ID.
status String Status of the order. If you receive “CREATED”, then the order is successfully created. If you invoke this API with the an order_id which is already created, then this API will return the result of /order/status API.
status_id String Status ID is a numeric id corresponding to the status value.
payment_links.web String Link to checkout page that is optimized for Desktop for the given order.
payment_links.mobile String Link to Mobile optimized checkout page for the given order.
payment_links.iframe String Link to iFrame checkout screen. This is typically embedded inside of your own page.

Get Order Status

Retrieve the order object associated with the order_id.

Definition

GET
https://api.juspay.in/orders/:order_id
Order.status(String orderId);

Example Request

curl https://api.juspay.in/orders/145678234 \
-u api_key:
Juspay.Orders.get_status(order_id='145678234')
Orders.status(:order_id => '145678234')
$params = array();
$params['order_id'] = "145678234"
$response=Order::status($params);
String orderId = "145678234"
Order order = Order.status(orderId);

URL Embedded Parameter

Field Type Description
order_id
Required
String Order ID

Example Response

{
   "merchant_id": "merchant_id",
   "order_id": "order_id",
   "customer_id": "user@gmail.com",
   "customer_email": "user@gmail.com",
   "customer_phone": "9966228812",
   "product_id": ":product_id",
   "status": "CHARGED",
   "status_id": 21,
   "amount": 1000,
   "currency": "INR",
   "refunded": false,
   "amount_refunded": 0,
   "return_url": "",
   "udf1": "",
   "udf2": "",
   "udf3": "",
   "udf4": "",
   "udf5": "",
   "udf6": "",
   "udf7": "",
   "udf8": "",
   "udf9": "",
   "udf10": "",
   "txn_id": "txn_id",
   "gateway_id": 2,
   "bank_error_code": "",
   "bank_error_message": "",
   "card": {
     "last_four_digits": "",
     "card_isin": "524368",
     "expiry_month": "12",
     "expiry_year": "2015",
     "name_on_card": "Cardholder Name",
     "card_type": "CREDIT",
     "card_issuer": "HDFC Bank",
     "card_brand": "MasterCard"
   },
   "payment_gateway_response": {
     "created": "2015-01-29T12:25:49Z",
     "epg_txn_id": "502913366745",
     "rrn": "502913366745",
     "auth_id_code": "999999",
     "txn_id": "11327833",
     "resp_code": "CAPTURED",
     "resp_message": "CAPTURED"
   },
   "payment_links": {
     "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
     "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
     "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
   }
}
<Order>
{
  'status': u'NEW',
  'amount_refunded': 0,
  'status_id': 10,
  'order_id': u'145678234',
  'refunded': False,
  'currency': u'INR',
  'amount': 1000,
  'merchant_id': u'customer',
  <PaymentLink>
  {
    'web': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c',
    'mobile': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true',
    'iframe': u'https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c'
  }
}
<Orders::Order:0x00000a>
{
    @status = "NEW",
    @amount_refunded = 0,
    @status_id = 10,
    @order_id = "145678234",
    @refunded = false,
    @currency = "INR",
    @amount = 1000,
    @merchant_id = "customer",
    <PaymentLink:0x00000a>
     {
         @web: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
         @mobile: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
         @iframe: "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
     }
}
Order Object
(
  [status] => NEW
  [amount_refunded] =>  0
  [status_id] =>  10
  [order_id] =>  145678234
  [refunded] =>  False
  [currency] =>  INR
  [amount] =>  1000
  [merchant_id] =>  customer
  [PaymentLinks] => (
      [web]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c
      [mobile]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true
      [iframe]: https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c
    )
)
@object in.juspay.model.Order
JSON:
{
   "merchant_id": "merchant_id",
   "order_id": "order_id",
   "customer_id": "user@gmail.com",
   "customer_email": "user@gmail.com",
   "customer_phone": "9966228812",
   "product_id": ":product_id",
   "status": "CHARGED",
   "status_id": 21,
   "amount": 1000,
   "currency": "INR",
   "refunded": false,
   "amount_refunded": 0,
   "return_url": "",
   "udf1": "",
   "udf2": "",
   "udf3": "",
   "udf4": "",
   "udf5": "",
   "udf6": "",
   "udf7": "",
   "udf8": "",
   "udf9": "",
   "udf10": "",
   "txn_id": "txn_id",
   "gateway_id": 2,
   "bank_error_code": "",
   "bank_error_message": "",
   "card": {
     "last_four_digits": "",
     "card_isin": "524368",
     "expiry_month": "12",
     "expiry_year": "2015",
     "name_on_card": "Cardholder Name",
     "card_type": "CREDIT",
     "card_issuer": "HDFC Bank",
     "card_brand": "MasterCard"
   },
   "payment_gateway_response": {
     "created": "2015-01-29T12:25:49Z",
     "epg_txn_id": "502913366745",
     "rrn": "502913366745",
     "auth_id_code": "999999",
     "txn_id": "11327833",
     "resp_code": "CAPTURED",
     "resp_message": "CAPTURED"
   },
   "payment_links": {
     "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
     "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
     "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
   }
}

List Orders

List the orders that were created. By default, the orders are listed in the reverse chronological order (starting from the order that was most recently created)

Definition

GET
https://api.juspay.in/orders
Order.list(Map params);

Example Request

curl -X GET https://api.juspay.in/orders?created.lt=1422271716&created.gt=1421407873&count=1&offset=101 \
-u api_key:
Juspay.Orders.list()
Orders.list()
Order.listAll()
Map<String, Object> params = new LinkedHashMap();
params.put("count", 10);
Order.list(params);

Request Parameters

Field Type Description
created Match all orders that were in the time range specified by this. The timestamp value for the attributes mentioned should be given in seconds. This should represent the unix timestamp integer.
gt Integer Return values where the created field is after this timestamp
lt Integer Return values where the created field is before this timestamp
ge Integer Return values where the created field is after or equal to this timestamp
le Integer Return values where the created field is before or equal to this timestamp
count Integer The number of orders that has to be returned
Size range: 1-100
offset Integer The number of orders that should be skipped

Example Response

{
 "list":
 [
   {
     "merchant_id": "nspi",
     "order_id": "2IWz8U9PRriq5cgd_oBhAg",
     "customer_id": "user@mail.com",
     "customer_email": "user@mail.com",
     "customer_phone": null,
     "product_id": "",
     "status": "NEW",
     "status_id": 10,
     "amount": 600,
     "currency": "INR",
     "refunded": false,
     "amount_refunded": 0,
     "return_url": "http://www.merchant.in/order/confirm",
     "udf1": "",
     "udf2": "",
     "udf3": "",
     "udf4": "",
     "udf5": "",
     "udf6": "",
     "udf7": "",
     "udf8": "",
     "udf9": "",
     "udf10": "",
     "payment_links": {
        "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
        "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
        "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
      }
   }
   ...
 ],
 "count": 10,
 "offset": 0,
 "total": 91604
}
<dict>
{
    'count': 10,
    'total': 987,
    'list': [   
    <Order>
    {
          'status': u'NEW',
          'amount_refunded': 0,
          'status_id': 10,
          'order_id': u'1465889517',
          'refunded': False,
          'currency': u'INR',
          'amount': 1000,
          'merchant_id': u'myshop',
          <PaymentLink>
          {
            'web': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c',
            'mobile': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true',
            'iframe': u'https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c'
          }
      }
    ,
    ...
    ],
    'offset': 0
}

<hashmap>
{
     :count => 10,
     :total => 987,
     :list => [ 
          <Orders::Order:0x00000a>
          {
               @status = "NEW",
               @amount_refunded = 0,
               @status_id = 10,
               @order_id = "1465889517",
               @refunded = false,
               @currency = "INR",
               @amount = 1000,
               @merchant_id = "myshop",
               <PaymentLink:0x00000a>
               {
                   @web: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
                   @mobile: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
                   @iframe: "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
               }
          }
          ,
          ...
     ],
     :offset => 0
}

OrderList Object
( 
    count => 10
    total => 987
    offset => 0
    list =>
    (
    [0] => Order Object
        (
            [status] =>NEW
            [amount_refunded] => 0
            [status_id] => 10
            [order_id] => 1465889517
            [refunded] => False
            [currency] => INR
            [amount] => 1000
            [merchant_id] => myshop
            [PaymentLinks] => (
                [web]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c
                [mobile]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true
                [iframe]: https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c
              )
        )   
        ,
        ...
    )
 )
@object in.juspay.model.OrderList
JSON:
{
 "list":
 [
   {
     "merchant_id": "nspi",
     "order_id": "2IWz8U9PRriq5cgd_oBhAg",
     "customer_id": "user@mail.com",
     "customer_email": "user@mail.com",
     "customer_phone": null,
     "product_id": "",
     "status": "NEW",
     "status_id": 10,
     "amount": 600,
     "currency": "INR",
     "refunded": false,
     "amount_refunded": 0,
     "return_url": "http://www.merchant.in/order/confirm",
     "udf1": "",
     "udf2": "",
     "udf3": "",
     "udf4": "",
     "udf5": "",
     "udf6": "",
     "udf7": "",
     "udf8": "",
     "udf9": "",
     "udf10": "",
     "payment_links": {
          "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
          "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
          "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
        }
   }
   ...
 ],
 "count": 10,
 "offset": 0,
 "total": 91604
}

Response Parameters

Field Type Description
list Object This attribute contains an array of orders. Each of the order contains all the information associated with it.
count Integer Number of objects returned.
offset Integer The number of orders that was skipped in the search result. Matches the input.
total Integer The total number of orders that matched he search criteria.

Update Order

Update an order that has already been created. Only amount, address and udf fields can be updated. Address fields can be optionally sent as explained in the /order/create API.

Return

The API returns a response that is same as that of /order/status call.

Definition

POST
https://api.juspay.in/orders/:order_id
Order.update(String orderId, Map params);

Example Request

curl -X POST https://api.juspay.in/orders/1418394476 \
-u api_key: \
-d "amount=90.00"
Juspay.Orders.update(order_id='1465829015', amount=1000)
Orders.update(:order_id => '1465829015', :amount =>1000)
$params = array()
$params['order_id'] = "1465829015";
$params['amount']=1000;
$response = Order::update($params);
String orderId = "1465829015";
Map<String, Object> params = new LinkedHashMap();
params.put("amount", 1000);
Order.update(orderId, params);

URL Embedded Parameter

Field Type Description
order_id
Required
String Order ID

Request Parameters

Field Type Description
order_id
Required
String Unique Identifier for the order.
amount
Required
Double New amount value.

Example Response

{
  "merchant_id": "test",
  "customer_id": "193526",
  "order_id": "1418394476",
  "status": "NEW",
  "status_id": 10,
  "amount": 90,
  "refunded": false,
  "amount_refunded": 0,
  "payment_links": {
    "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
    "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
    "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
  }
}
<Order>
{
  'status': u'NEW',
  'amount_refunded': 0,
  'status_id': 10,
  'order_id': u'1465829015',
  'refunded': False,
  'currency': u'INR',
  'amount': 1000,
  'merchant_id': u'shreyas',
  <PaymentLink>
   {
     'web': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c',
     'mobile': u'https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true',
     'iframe': u'https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c'
   }
}
<Orders::Order:0x00000a>
{
    @status = "NEW",
    @amount_refunded = 0,
    @status_id = 10,
    @order_id = "1465829015",
    @refunded = false,
    @currency = "INR",
    @amount = 1000,
    @merchant_id = "shreyas",
    <PaymentLink:0x00000a>
    {
       @web: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
       @mobile: "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
       @iframe: "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
    }
}
Order Object
(
  [status] => NEW
  [amount_refunded] =>  0
  [status_id] =>  10
  [order_id] =>  145678234
  [refunded] =>  False
  [currency] =>  INR
  [amount] =>  1000
  [merchant_id] =>  shreyas
  [PaymentLinks] => (
    [web]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c
    [mobile]: https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true
    [iframe]: https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c
  ) 
)
@object in.juspay.model.Order
JSON:
{
  "merchant_id": "test",
  "customer_id": "193526",
  "order_id": "1418394476",
  "status": "NEW",
  "status_id": 10,
  "amount": 90,
  "refunded": false,
  "amount_refunded": 0
  "payment_links": {
       "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c"
       "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true"
       "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
     }
}

Refund order

Create a refund for a payment.

Definition

POST
https://api.juspay.in/orders/:order_id/refunds
Order.refund(String orderId, Map params);

Example Request

curl -X POST https://api.juspay.in/orders/1418394476/refunds \
-u api_key: \
-d "unique_request_id=1" \
-d "amount=100.00"
Juspay.Orders.refund(
  unique_request_id='99',
  order_id='1465833326',
  amount=10)
Orders.refund(
  :unique_request_id => '99',
  :order_id => '1465833326',
  :amount => 10)
params = array();
$params['unique_request_id'] = "99";
$params['order_id'] = "1465833326",
$params['amount'] = 10;
$response = Order::refund($params);
String orderId = "1465833326";
Map<String, Object> params = new LinkedHashMap();
params.put("unique_request_id", "99");
params.put("amount", 10);
Order order = Order.refund(orderId, params);

URL Embedded Parameter

Field Type Description
order_id
Required
String Use the order ID that was used while creating the Order.

Request Parameters

Field Type Description
unique_request_id
Required
String Request ID that uniquely identifies this request. You cannot reuse the value for two different refund requests. This is to avoid processing duplicate refund requests. A good candidate for unique_request_id would be your database primary key.
order_id
Required
String Send this as request parameter when using server SDK. Order ID for which the refund has to be processed
amount Double Amount that has to be refunded. Amount has to be less than or equal to the amount of the order that is not yet refunded. If this parameter is not passed, then the order is refunded entirely

Example Response

{
  "merchant_id": "test",
  "customer_id": "193526",
  "order_id": "17027265",
  "status": "CHARGED",
  "status_id": 21,
  "amount": 2400,
  "txn_id": "test-17027265-001",
  "gateway_id": 1,
  "bank_error_code": "",
  "bank_error_message": "",
  "card": {
    "last_four_digits": "",
    "expiry_month": "07",
    "expiry_year": "2013",
    "name_on_card": ""
  },
  "payment_gateway_response": {
    "rrn": "306721283931",
    "epg_txn_id": "1900005",
    "auth_id_code": "T15672",
    "txn_id": "test-17027265-001",
    "resp_code": "0",
    "resp_message": "Approved"
  },
  "refunded": false,
  "amount_refunded": 100,
  "refunds" :
  [
    {
        "id": "refund_id",
        "ref": "bank_reference_no",
        "amount": 100,
        "created" : "2013-02-07 23:11:11",
        "status" : "SUCCESS"
    }
  ]
}
<Order>
{
  'gateway_id': 100,
  'status': u'CHARGED',
  'customer_email': u'user@gmail.com',
  'txn_id': u'txn-1465833326-1',
  'refunds': [
    <Refund> {
      'status': u'SUCCESS',
      'amount': 10,
      'created': u'2016-06-13T15:19:34Z'
    },
  ],
  'amount_refunded': 10,
  'order_id': u'1465833326',
  'refunded': False,
  'status_id': 21,
  'bank_error_code': u'0',
  'bank_error_message': u'Payment Successful',
  'gateway_response': <GatewayResponse> {
    'epg_txn_id': u'1465831091168',
    'auth_id_code': u'834050',
    'resp_code': u'0',
    'txn_id': u'txn-1465833326-1',
    'resp_message': u'Payment Successful',
  }
  ,
  'currency': u'INR',
  'amount': 1000,
  'merchant_id': u'shop',
  'customer_id': u'shop_user_101',
  'card': <Card> {
    'isin': u'424242',
    'brand': u'VISA',
    'type': u'CREDIT',
    'fingerprint': u'3rfeetv0blcc6bkroo4rvkjk62',
  }
  ,
}
<Orders::Order:0x00000a>
{
  @gateway_id = 100,
  @status = "CHARGED",
  @customer_email = "user@gmail.com",
  @txn_id = "txn-1465833326-1",
  @refunds = [
    <Orders::Order::Refund:0x00000b> {
      @status = "SUCCESS",
      @amount = 10,
      @created = "2016-06-13T15:19:34Z"
    },
  ],
  @amount_refunded = 10,
  @order_id = "1465833326",
  @refunded = false,
  @status_id = 21,
  @bank_error_code = "0",
  @bank_error_message = "Payment Successful",
  @gateway_response = <Orders::Order::GatewayResponse:0x00000c>{
    @epg_txn_id = "1465831091168",
    @auth_id_code = "834050",
    @resp_code = "0",
    @txn_id = "txn-1465833326-1",
    @resp_message = "Payment Successful",
  },
  @currency = "INR",
  @amount = 1000,
  @merchant_id = "shop",
  @customer_id = "shop_user_101",
  @card = <Cards::Card:0x00000d> {
    @isin = "424242",
    @brand: "VISA",
    @type: "CREDIT",
    @fingerprint = "3rfeetv0blcc6bkroo4rvkjk62",
  }
  ,
}
Order Object
(
  [gateway_id] => 100,
  [status] => CHARGED
  [customer_email] => user@gmail.com
  [txn_id] => txn-1465833326-1
  [refunds] => (
    [0]=> Refund Object (
      [status] => SUCCESS
      [amount] => 10,
      [created] => 2016-06-13T15:19:34Z
    ),
  ),
  [amount_refunded] => 10,
  [order_id] => 1465833326
  [refunded] => False,
  [status_id] => 21,
  [bank_error_code] => 0
  [bank_error_message] => Payment Successful
  [gateway_response] => GatewayResponse Object (
    [epg_txn_id] => 1465831091168
    [auth_id_code] => 834050
    [resp_code] => 0
    [txn_id] => txn-1465833326-1
    [resp_message] => Payment Successful
  )
  ,
  [currency] => INR
  [amount] => 1000,
  [merchant_id] => shop
  [customer_id] => shop_user_101
  [card] => Card Object (
    [isin] => 424242
    [brand] => VISA
    [type] => CREDIT
    [fingerprint] => 3rfeetv0blcc6bkroo4rvkjk62
  )
)
,
@object in.juspay.model.Order
JSON:
{
  "merchant_id": "test",
  "customer_id": "193526",
  "order_id": "17027265",
  "status": "CHARGED",
  "status_id": 21,
  "amount": 2400,
  "txn_id": "test-17027265-001",
  "gateway_id": 1,
  "bank_error_code": "",
  "bank_error_message": "",
  "card": {
    "last_four_digits": "",
    "expiry_month": "07",
    "expiry_year": "2013",
    "name_on_card": ""
  },
  "payment_gateway_response": {
    "rrn": "306721283931",
    "epg_txn_id": "1900005",
    "auth_id_code": "T15672",
    "txn_id": "test-17027265-001",
    "resp_code": "0",
    "resp_message": "Approved"
  },
  "refunded": false,
  "amount_refunded": 100,
  "refunds" :
  [
    {
        "id": "refund_id",
        "ref": "bank_reference_no",
        "amount": 100,
        "created" : "2013-02-07 23:11:11",
        "status" : "SUCCESS"
    }
  ]
}

Response Parameters

Field Type Description
amount_refunded String Amount which has been refunded so far for this order
refunded Boolean true if the order has been completely refunded. Will be false for partial refunds or if the order doesn’t have any refunds.
refunds List This contains the list of refunds for the order. This attribute is present only if atleast one refund exists for the order.
refund[x].id String ID generated for the refund
refund[x].ref String Reference number provided by the bank for the refund
refund[x].amount Double Amount refunded (or to be refunded)
refund[x].created String Date time (ISO representation) when refund was created
refund[x].status String Status of the refund. Can be one of PENDING, SUCCESS, FAILURE.
SUCCESS:. This means that the refund has been successfully executed.
PENDING:. This would mean that the refund has been queued with JusPay or with the downstream system.
FAILURE:.We were unable to process the refund successfully. You have to try again with new unique_request_id.

Card

Represents a credit or debit card belonging to a customer.

Tokenize

Authentication is NOT required for this API call.

The tokenization API takes in the details of a card and generates a token representing the details of the card. This API is expected to be called from the browser or directly from Android/iOS app. Once a card is tokenized, you can initiate a payment or add the card to any customer’s account using /card/add.

A tokenized card is remembered only for 15 minutes. You have to make use of the card before its validity expires. If expired, you have to get the card input by the user again.

Example Request

curl https://api.juspay.in/card/tokenize \
    -d "card_number=4111111111111111" \
    -d "card_exp_year=2015" \
    -d "card_exp_month=07" \
    -d "card_security_code=123" \
    -d "merchant_id=myshop" \
    -d "name_on_card=123"
// Use pay-v2.js to tokenize a card
# Use pay-v2.js to tokenize a card
# Use pay-v2.js to tokenize a card

Example Response

{
  "token": "ctkn_qvfiry6hreobblus"
}

API

POST https://api.juspay.in/card/tokenize

Request Parameters

Field Type Description
merchant_id
Required
String Merchant ID which represents the merchant storing the card
card_number
Required
String A valid card number
card_exp_year
Required
String Expiry year of the card (Format: yyyy) Example: 2020
card_exp_month
Required
String Expiry month of the card (Format: mm) Example: 06
card_security_code
Required
String The CVV number of the card.
name_on_card String Cardholder name

Response Parameters

Field Type Description
card_token String Unique shortlived token which represents the card that has been added. You can initiate payment with this token.
When initiating payment, CVV is not collected as it is provided at the time of tokenization.

Add card

Add a credit card or debit card of a customer to JusPay Locker. customer_id parameter identifies the customer to whom this card belongs to.

Definition

POST
https://api.juspay.in/cards
Card.create(Map params);

Example Request

curl -X POST https://api.juspay.in/cards \
-u api_key: \
-d "merchant_id=myshop" \
-d "customer_id=user_101" \
-d "customer_email=customer@gmail.com" \
-d "card_number=4111111111111111" \
-d "card_exp_year=2019" \
-d "card_exp_month=07" \
-d "name_on_card=Sindbad" \
-d "nickname=Visa card"
Juspay.Cards.add( merchant_id=myshop, 
                  customer_id=user_101, 
                  customer_email=customer@gmail.com, 
                  card_number= '4111111111111111'
                  card_exp_year=2019, 
                  card_exp_month=07, 
                  name_on_card=Sindbad,
                  nickname=Visa card)
Cards.create( :merchant_id => 'myshop', 
              :customer_id => 'user_101', 
              :customer_email => 'customer@gmail.com', 
              :card_number => '4111111111111111',
              :card_exp_year => 2019, 
              :card_exp_month => 07, 
              :name_on_card => 'Sindbad',
              :nickname => 'Visa card')
$params = array ();
$params ['merchant_id'] = "myshop";
$params ['customer_id'] = "user_101";
$params ['customer_email'] = "customer@gmail.com";
$params ['card_number'] = "4111111111111111";
$params ['card_exp_year'] = "2019";
$params ['card_exp_month'] = "07";
$params ['name_on_card'] = "Sindbad";
$params ['nickname'] = "Visa card";
$card = Card::create ( $params );
Map<String, Object> params = new LinkedHashMap();
params.put("merchant_id", "myshop");
params.put("customer_id", "user_101");
params.put("customer_email", "customer@gmail.com");
params.put("card_number", "4111111111111111");
params.put("card_exp_year", "2018");
params.put("card_exp_month", "07");
params.put("name_on_card", "Sindbad");
params.put("nickname", "Visa card");
Card card = Card.create(params);

Request Parameters

Field Type Description
merchant_id
Required
String Merchant ID which represents the merchant storing the card
customer_id
Required
String Customer ID which represents the user uniquely
customer_email
Required
String Email address of the customer
card_token
Required
String Card token generated using the /card/tokenize API.
If this parameter is sent, the card_number, card_exp_year, card_exp_month fields are not required.
card_number
Required
String A valid card number
card_exp_year
Required
String Expiry year of the card (Format: yyyy) Example: 2020
card_exp_month
Required
String Expiry month of the card (Format: mm) Example: 06
name_on_card String Cardholder name
nickname String A tag or a label for the card so that the user can easily identify the card

Example Response

{
   "card_token": "c75a9fca-1121-418e-973c-47d5c4971456",
   "card_reference": "df2c47951a71e4486827039fad7b039a",
   "card_fingerprint": "c7uapov1smt3a0rd5f9b1l21i"
}
<Card>
{
  'token': u'046f1004-09b7-4e21-95e7-0d791af1492c',
  'reference': u'444d79d0a66c97f66144d3e8d5f8a8cf',
  'fingerprint': u'5fp2hhcsvp3udti59ovagb7knr',
}
<Cards::Card:0x00000a>
{
  @token = "046f1004-09b7-4e21-95e7-0d791af1492c",
  @reference = "444d79d0a66c97f66144d3e8d5f8a8cf",
  @fingerprint = "5fp2hhcsvp3udti59ovagb7knr",
}
Card Object
(
    [token] => c75a9fca-1121-418e-973c-47d5c4971456
    [reference] => 444d79d0a66c97f66144d3e8d5f8a8cf
    [fingerprint] => 5fp2hhcsvp3udti59ovagb7knr
)
@object in.juspay.model.Card
JSON:
{
   "card_token": "c75a9fca-1121-418e-973c-47d5c4971456",
   "card_reference": "df2c47951a71e4486827039fad7b039a",
   "card_fingerprint": "c7uapov1smt3a0rd5f9b1l21i"
}

Response Parameters

Field Type Description
card_token String Unique shortlived token which represents the card that has been added. You can initiate payment with this token.
card_reference String A reference identifier for the card. Use this reference string to map any metadata of the card at your end. For instance, you can setup a transaction counter against the reference or store the channel information against the card for further analytics.
card_fingerprint String A string that uniquely identifies the card across the board. When the same card is stored across multiple accounts, same fingerprint will be returned. This can be used to identify duplicates.

List stored cards

List all the cards stored for a customer. This API gives back only tokens and other metadata relevant to the cards stored in JusPay Locker.

Definition

GET
https://api.juspay.in/cards
Card.list(Map params);

Example Request

curl -X GET https://api.juspay.in/cards?customer_id=guest_user \
-u api_key:
Juspay.Cards.list(customer_id='guest_user')
Cards.list(:customer_id => 'guest_user')
$params = array ();
$params ['customer_id'] = "guest_user";
$response = Card:listAll($params);
Map<String, Object> params = new LinkedHashMap();
params.put("customer_id", customerId);
List<Card> cards = Card.list(params);

Request Parameters

Field Type Description
customer_id
Required
String Customer ID which represents the user uniquely

Example Response

{
  "customer_id": "guest_user",
  "merchantId": "guest",
  "cards": [
    {
      "card_token": "2ea1fc4d-cbeb-4df7-b03d-97198e5c5e4e",
      "card_reference": "20d67719b2249ccd375f44fd98817a47",
      "card_fingerprint": "f6f6ac14a9438561404e8ec0776d",
      "card_number": "5264-XXXXXXXX-3394",
      "card_isin": "526419",
      "card_exp_year": "2014",
      "card_exp_month": "10",
      "card_type": "DEBIT",
      "card_issuer": "HDFC BANK",
      "card_brand": "MASTERCARD",
      "nickname": "",
      "name_on_card": "Real Card",
      "expired": true
    }
  ]
}
[
  <Card>
  {
      'exp_month': u'12',
      'reference': u'c945f23cf7d2218dc0479ddc2c0b901b',
      'number': u'4242-xxxxxxxx-4242',
      'token': u'0630bb23-55fc-42c8-b912-2f053fab16d0',
      'fingerprint': u'5fp2hhcsvp3udti59ovagb7knr',
      'isin': u'424242',
      'exp_year': u'20',
      'expired': False,
    },
  <Card>
  {
      'exp_month': u'12',
      'reference': u'd249c873550566782586983052dbb95a',
      'number': u'4111-xxxxxxxx-1111',
      'token': u'feee4822-0f90-44c8-b4b6-a68a2fb2e14a',
      'fingerprint': u'7osbi02mhbi5ctom4fn8fbicbd',
      'isin': u'411111',
      'exp_year': u'20',
      'expired': False,
  }
]

[
  <Cards::Card:0x00000a>
  {
      @exp_month = "12",
      @reference = "c945f23cf7d2218dc0479ddc2c0b901b",
      @number = "4242-xxxxxxxx-4242",
      @token = "0630bb23-55fc-42c8-b912-2f053fab16d0",
      @fingerprint = "5fp2hhcsvp3udti59ovagb7knr",
      @isin = "424242",
      @exp_year = "20",
      @expired = false,
    },
  <Cards::Card:0x00000b>
  {
      @exp_month = "12",
      @reference = "d249c873550566782586983052dbb95a",
      @number = "4111-xxxxxxxx-1111",
      @token = "feee4822-0f90-44c8-b4b6-a68a2fb2e14a",
      @fingerprint = "7osbi02mhbi5ctom4fn8fbicbd",
      @isin = "411111",
      @exp_year = "20",
      @expired = false,
  }
,
]
(
    [0] => Card Object
        (
            [exp_month] => 12
            [reference] => c945f23cf7d2218dc0479ddc2c0b901b
            [number] => 4242-xxxxxxxx-4242
            [token] => 0630bb23-55fc-42c8-b912-2f053fab16d0
            [fingerprint] => 5fp2hhcsvp3udti59ovagb7knr
            [isin] => 424242
            [exp_year] => 20
            [expired] => false
        )
    [1] => Card Object
        (
            [exp_month] => 12
            [reference] => d249c873550566782586983052dbb95a
            [number] => 4111-xxxxxxxx-1111
            [token] => feee4822-0f90-44c8-b4b6-a68a2fb2e14a
            [fingerprint] => 7osbi02mhbi5ctom4fn8fbicbd
            [isin] => 411111
            [exp_year] => 20
            [expired] => false
        )
)
@object java.util.List<Card>
JSON:
[
  {
      exp_month = "12",
      reference = "c945f23cf7d2218dc0479ddc2c0b901b",
      number = "4242-xxxxxxxx-4242",
      token = "0630bb23-55fc-42c8-b912-2f053fab16d0",
      fingerprint = "5fp2hhcsvp3udti59ovagb7knr",
      isin = "424242",
      exp_year = "20",
      expired = false,
  },
  {
      exp_month = "12",
      reference = "d249c873550566782586983052dbb95a",
      number = "4111-xxxxxxxx-1111",
      token = "feee4822-0f90-44c8-b4b6-a68a2fb2e14a",
      fingerprint = "7osbi02mhbi5ctom4fn8fbicbd",
      isin = "411111",
      exp_year = "20",
      expired = false,
  }
]

Response Parameters

Field Type Description
customer_id String Given Customer ID.
cards String Array of stored cards that belongs to the given user represented by the Customer ID. Each member of the array is an associative array that represents a stored card of the user.
card_token String Token representing the card. Payment has to be initiated using this token. Tokens are by definition short lived and so, please do not cache them in your system. Expired tokens will lead to transactions being declined.
card_reference String A reference identifier that doesn’t change for the stored card. Use this identifier to store any metadata that you wish. For example, you can store card type or card bin or even transaction data using this reference.
card_fingerprint String A string that uniquely identifies the card across the board. When the same card is stored across multiple accounts, same fingerprint will be returned. This can be used to identify duplicates.
card_number String Masked card number that can be displayed to the customer.
card_isin String First 6 digits of the card
card_exp_year String Year of expiry of the card
card_exp_month String Month of expiry of the card
card_type String Indicates if the card is either CREDIT or DEBIT. Please note that this information is inferred. Not all cards will have this information.
card_issuer String Indicates the bank which issued the card. This again is not available all the time. We make our best effort to get this information for all cards.
name_on_card String Cardholder name given while storing the card
nickname String Returns the given nickname while storing the card
expired String Indicates whether the stored card is expired or not

Delete card

Definition

DELETE
https://api.juspay.in/cards/:card_token
Card.delete(String cardToken);

Example Request

curl -X DELETE https://api.juspay.in/cards/c75a9fca-1121-418e-973c-47d5c4971456 \
-u api_key:
Juspay.Cards.delete(card_token='c75a9fca-1121-418e-973c-47d5c4971456')
Cards.delete(:card_token => 'c75a9fca-1121-418e-973c-47d5c4971456')
$params = array ();
$params ['card_token'] = "c75a9fca-1121-418e-973c-47d5c4971456";
$response = Card:delete($params);
String cardToken = "c75a9fca-1121-418e-973c-47d5c4971456";
boolean isDeleted = Card.delete(cardToken);

URL Embedded Parameter

Field Type Description
card_token
Required
String Card token obtained from /card/list API

Example Response

{
   "card_token": "c75a9fca-1121-418e-973c-47d5c4971456",
   "card_reference": "df2c47951a71e4486827039fad7b039a",
   "deleted": true
}
<Card>
{
    'deleted': True,
    'token': u'c75a9fca-1121-418e-973c-47d5c4971456',
    'reference': u'444d79d0a66c97f66144d3e8d5f8a8cf',
}
<Cards::Card:0x00000a>
{
    @deleted = true,
    @token = "c75a9fca-1121-418e-973c-47d5c4971456",
    @reference = "444d79d0a66c97f66144d3e8d5f8a8cf",
}
Card Object
(
    [deleted] => true
    [token] => c75a9fca-1121-418e-973c-47d5c4971456
    [reference] => 444d79d0a66c97f66144d3e8d5f8a8cf
)
true

Response Parameters

Field Type Description
card_token String Card token that was given as input
card_reference String Reference identifier of the card
deleted Booloean Indicates if the card has been successfully deleted or not

Wallet

Represents a wallet account that belongs to a customer. Wallet account is valid only when your wallet provider has granted you permission for DIRECT WALLET DEBIT flow. To initiate a transaction for the first time, you need to authenticate and link the wallet. A linked wallet account will have an associated token with it. Such a token is assigned by JusPay and you must send this token to directly debit from the wallet.

Security

To ensure better security, JusPay will expire the token within 10 minutes of issuance (issued when you call /wallets list API). Also a token is valid only for single use.

Usage

To allow direct wallet debit, you need to list the wallets of the customer using /wallets. After listing the wallets, you have the following three options available with you:

  1. Wallet is not listed

    • In this case, you need to create a wallet and then link it to allow direct wallet debit. Following are the steps to create and link a wallet:
      1. Call the wallet create api with command=authenticate parameter which will send an OTP to the registered mobile of the customer.
      2. Send the OTP back to Juspay using link api. Juspay will authenticate the OTP with the provider and then link the wallet.
  2. Wallet is listed but not linked

    • In this case, you need to link the wallet to allow direct wallet debit. Following are the steps to link a wallet:
      1. Call the wallet authenticate api which will send an OTP to the registered mobile of the customer.
      2. Send the OTP back to Juspay using link api. Juspay will authenticate the OTP with the provider and then link the wallet.
  3. Wallet is listed and already linked

    • In this case, the wallet is already linked and you can use the token to initiate payment on the wallet directly.

After this we are good to perform transactions via the linked wallet.

List

Wallets can be listed only in the context of a Customer. This API will return the list of wallets for a given customer which may be linked or delinked.

Note 1: Delinked wallets needs to be linked to initiate a transaction.

Note 2: For linked wallets, the balance in the response may not be the current balance, last_refreshed field will have the date when last balance updated. Use refresh wallet API to get updated balance for individual wallets.

Definition

GET
https://api.juspay.in/customers/:customer_id/wallets
Wallet.list(String customerId);

Example Request

curl -X GET https://api.juspay.in/customers/guest_user/wallets \
-u api_key:
Juspay.Wallets.list(customer_id='guest_user')
Wallets.list(:customer_id => 'guest_user')
$customerid = 'guest_user';
$response = Wallet::listAll($customerid);
String customerId = "guest_user";
WalletList wallets = Wallet.list(customerId);

URL Embedded Parameter

Field Type Description
customer_id
Required
String Use the ID that is generated by JUSPAY during customer creation. You may also send the value that you sent in object_reference_id at the time of creating the customer.

Example Response

{
  "object": "list"
  "list": [
    {
     "id": "wlt_q23xzki3pazgtezo",
     "object": "wallet_account",
     "wallet": "MOBIKWIK",
     "token": "tok_winysteev9eftrwcv6me",
     "current_balance": 250.00,
     "linked": true,
     "last_refreshed": "2016-08-02T08:07:52+0000"
    },
    {
      "id": "wlt_mu2xfwb4mr18flbs",
      "object": "wallet_account",
      "wallet": "FREECHARGE",
      "token": null,
      "current_balance": null,
      "linked": false,
      "last_refreshed": null
    },
  ],
  ...
 "count": 10,
 "offset": 0,
 "total": 100
}
[
  <Wallet>
  {
  'id': u'wlt_q23xzki3pazgtezo',
  'object': u'wallet_account',
  'wallet': u'MOBIKWIK',
  'token': u'tok_winysteev9eftrwcv6me',
  'current_balance': u'250.00',
  'linked': true,
  'last_refreshed': u'2016-08-02T08:07:52+0000'
  },
  {
  'id': u'wlt_mu2xfwb4mr18flbs',
  'object': u'wallet_account',
  'wallet': u'FREECHARGE',
  'token': null,
  'current_balance': null,
  'linked': false,
  'last_refreshed': null
  },
  ...
]

[
  <Wallets::Wallet:0x00000a>
  {
    @id = "wlt_q23xzki3pazgtezo",
    @object = "wallet_account",
    @wallet = "MOBIKWIK",
    @token = "tok_winysteev9eftrwcv6me",
    @current_balance = "250.00",
    @linked = true,
    @last_refreshed = "2016-08-02T08:07:52+0000"
  },
  {
    @id = "wlt_mu2xfwb4mr18flbs",
    @object = "wallet_account",
    @wallet = "FREECHARGE",
    @token = null,
    @current_balance = null,
    @linked = false,
    @last_refreshed = null
  },
  ...
]
WalletList Object
(
    count => 10
    total => 100
    offset => 0
    list =>
    ( 
        [0] => Wallet Object
            (
                [id] => wlt_q23xzki3pazgtezo
                [object] => wallet_account
                [wallet] => MOBIKWIK
                [token] => tok_winysteev9eftrwcv6me
                [current_balance] => 250.00
                [linked] => true
                [last_refreshed] => 2016-08-02T08:07:52+0000
            ),
        [1] => Wallet Object
            (
                [id] => wlt_mu2xfwb4mr18flbs
                [object] => wallet_account
                [wallet] => FREECHARGE
                [token] => null
                [current_balance] => null
                [linked] => false
                [last_refreshed] => null
            ),
            ...
    )
)
@object in.juspay.model.WalletList
JSON:
{
  "list": 
  [
    {
     "id": "wlt_q23xzki3pazgtezo",
     "object": "wallet_account",
     "wallet": "MOBIKWIK",
     "token": "tok_winysteev9eftrwcv6me",
     "current_balance": 250.00,
     "linked": true,
     "last_refreshed": "2016-08-02T08:07:52+0000"
    },
    {
      "id": "wlt_mu2xfwb4mr18flbs",
      "object": "wallet_account",
      "wallet": "FREECHARGE",
      "token": null,
      "current_balance": null,
      "linked": false,
      "last_refreshed": null
    }
  ],
 "count": 10,
 "offset": 0,
 "total": 100
}

Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Create

Wallet account can be created only for an existing customer. Please use POST /customers api to create the customer objects as needed.

Creating the wallet with command=authenticate parameter will trigger an OTP which will be used for linking the wallet thereby enabling direct debit authorization. You also have the option of deferring the authentication to a later point of time by omitting the command=authenticate parameter. In case you decide to defer it, Please use the authenticate and link api to authenticate and link the wallet.

Definition

POST
https://api.juspay.in/customers/$customer_id/wallets

Example Request

curl -X POST https://api.juspay.in/customer/$customer_id/wallets \
-u api_key: \
-d "gateway=MOBIKWIK" \
-d "command=authenticate"




Request Parameters

Field Type Description
gateway
Required
String Name of the gateway supplying the wallet.
command String Send it as authenticate if you want to start the authentication/linking process as soon as the wallet gets created.

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : "tok_winysteev9eftrwcv6me",
    "current_balance" : 250.00,
    "linked" : true,
    "last_refreshed" : "2016-08-02T08:07:52+0000"
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Authenticate

Starts the authentication and linking process of the wallet with the customer. This API is used if the wallet was delinked earlier by the customer or you decided to skip authentication during wallet creation. The customer will get an OTP on his registered mobile number on successful completion of this step.

Definition

POST
https://api.juspay.in/wallets/$wallet_id

Example Request

curl -X POST https://api.juspay.in/wallets/$wallet_id \
-u api_key: \
-d "command=authenticate"




Request Parameters

Field Type Description
command
Required
String Send it as authenticate if you want to start the authentication/linking process.

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : null,
    "current_balance" : null,
    "linked" : false,
    "last_refreshed" : null
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Completes the authentication and linking process of the wallet with the customer account. OTP received from the authenticate API call is forwarded to Juspay using this API for linking the wallet. On successful verification of the OTP, the wallet is linked with the customer object. If failed, then linked attribute will remain to be false.

Returns the wallet object.

Definition

POST
https://api.juspay.in/wallets/$wallet_id

Example Request

curl -X POST https://api.juspay.in/wallets/$wallet_id \
-u api_key: \
-d "command=link"
-d "otp=345678"




Request Parameters

Field Type Description
command
Required
String Send it as link if you want to complete the authentication/linking process.
otp
Required
String OTP sent by the provider to the customer’s registered mobile number.

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : "tok_winysteev9eftrwcv6me",
    "current_balance" : 250.00,
    "linked" : true,
    "last_refreshed" : "2016-08-02T08:07:52+0000"
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Use this call to delink the wallet from the customer.

Definition

POST
https://api.juspay.in/wallets/$wallet_id

Example Request

curl -X POST https://api.juspay.in/wallets/$wallet_id \
-u api_key: \
-d "command=delink"




Request Parameters

Field Type Description
command
Required
String Send it as delink to delink the wallet.

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : null,
    "current_balance" : null,
    "linked" : "false",
    "last_refreshed" : null
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Get

Get the wallet details. You can also use this api to generate one time use token for direct debit transactions.

Definition

GET
https://api.juspay.in/wallets/$wallet_id

Example Request

curl -X GET https://api.juspay.in/wallets/$wallet_id \
-u api_key: 




Request Parameters

Field Type Description

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : "tok_winysteev9eftrwcv6me",
    "current_balance" : 250.00,
    "linked" : "true",
    "last_refreshed" : "2016-08-02T08:07:52+0000"
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated when you call the refresh api.

Refresh

Refresh wallet API can be used to get the wallet with updated balance from wallet provider. This API is applicable only for linked wallets.

Definition

GET
https://api.juspay.in/wallets/$wallet_id

Example Request

curl -X GET https://api.juspay.in/wallets/$wallet_id \
-u api_key: \
-d "command=refresh"




Request Parameters

Field Type Description
command
Required
String Send it as refresh to get the updated balances.

Example Response

{
    "id" : "wlt_q23xzki3pazgtezo",
    "object" : "wallet_account",
    "wallet" : "MOBIKWIK",
    "token" : "tok_winysteev9eftrwcv6me",
    "current_balance" : 250.00,
    "linked" : "true",
    "last_refreshed" : "2016-08-02T08:07:52+0000"
}




Response Parameters

Field Type Description
id String Wallet id generated by Juspay after creating wallet.
object String Object type of the entity. In this case, it will be wallet_account.
wallet String Name of the wallet provider.
token String One time use token for performing direct debit transaction. This value will be null if wallet is not linked. This has to be passed in /txns while attempting direct debit using particular wallet.
current_balance Double Wallet balance at last_refreshed time.
linked Boolean Indicates if the wallet account is deep linked for direct authorization. Requires one time authentication by the customer.
last_refreshed String Date and time of the last synchronisation with the wallet provider. Will be updated on calling this api.

Payments

Credit/Debit Card Payment

Create a payment transaction for Credit or Debit card. For MAESTRO cards that do not have expiry & CVV, send 12/49 as expiry and 111 as CVV.

Definition

POST
https://api.juspay.in/txns
Payment.create(Map params)

Example Request

// A regular card transaction
curl -X POST https://api.juspay.in/txns \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=CARD" \
-d "payment_method=MASTERCARD" \
-d "card_number=5243681100075285" \
-d "card_exp_month=10" \
-d "card_exp_year=20" \
-d "name_on_card=Name" \
-d "card_security_code=111" \
-d "save_to_locker=true" \
-d "redirect_after_payment=true" \
-d "format=json"

// A Stored card transaction
curl -X POST https://api.juspay.in/txns \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=CARD" \
-d "card_token=:card_token" \
-d "card_security_code=111" \
-d "redirect_after_payment=true" \
-d "format=json"
# A regular card transaction
Juspay.Payments.create_card_payment(
      order_id='1465893617',
      merchant_id='guest',
      payment_method_type='CARD',
      card_token='68d6b0c6-6e77-473f-a05c-b460ef983fd8',
      redirect_after_payment=False,
      format='json',
      card_number='5243681100075285',
      name_on_card='Customer',
      card_exp_year='20',
      card_exp_month='12', card_security_code='123',
      save_to_locker=False)

# A Stored card transaction
Juspay.Payments.create_card_payment(
      order_id='1465893617',
      merchant_id='guest',
      payment_method_type='CARD',
      card_token='68d6b0c6-6e77-473f-a05c-b460ef983fd8',
      redirect_after_payment=False,
      format='json',
      card_security_code='123',
      save_to_locker=False)
# A regular card transaction
Payments.create_card_payment(
      :order_id => '1465893617',
      :merchant_id => 'guest',
      :payment_method_type => 'CARD',
      :card_token => '68d6b0c6-6e77-473f-a05c-b460ef983fd8',
      :redirect_after_payment => false,
      :format => 'json',
      :card_number => '5243681100075285',
      :name_on_card => 'Customer',
      :card_exp_year => '20',
      :card_exp_month => '12', 
      :card_security_code => '123',
      :save_to_locker => false)

# A Stored card transaction
Payments.create_card_payment(
      :order_id => '1465893617',
      :merchant_id => 'guest',
      :payment_method_type => 'CARD',
      :card_token => '68d6b0c6-6e77-473f-a05c-b460ef983fd8',
      :redirect_after_payment => false,
      :format => 'json',
      :card_security_code => '123',
      :save_to_locker => false)
# A regular card transaction
$params = array();
$params['order_id'] ="1465893617";
$params['merchant_id'] ="guest";
$params['payment_method_type'] ="CARD";
$params['card_token'] ="68d6b0c6-6e77-473f-a05c-b460ef983fd8";
$params['redirect_after_payment'] =False;
$params['format'] ="json";
$params['card_number'] ="5243681100075285";
$params['name_on_card'] ="Customer";
$params['card_exp_year'] ="20";
$params['card_exp_month'] ="12"; 
$params['card_security_code'] ="123";
$params['save_to_locker'] = false;
$response = Payment::create($params);

 # A Stored card transaction
$params = array();
$params['order_id'] ="1465893617";
$params['merchant_id'] ="guest";
$params['payment_method_type'] ="CARD";
$params['card_token'] ="68d6b0c6-6e77-473f-a05c-b460ef983fd8";
$params['redirect_after_payment'] =False;
$params['format'] ="json";
$params['card_security_code'] ="123";
$params['save_to_locker'] = false;
$response = Payment::create($params);     
Map<String, Object> params = new LinkedHashMap();
params.put("order_id", "1465893617");
params.put("merchant_id", "guest");
params.put("payment_method_type", "CARD");
params.put("card_token","68d6b0c6-6e77-473f-a05c-b460ef983fd8");
params.put("payment_method", "MASTERCARD");
params.put("redirect_after_payment", true);
params.put("card_number", "5243681100075285");
params.put("card_exp_month", "10");
params.put("card_exp_year", "20");
params.put("card_security_code", "111");
params.put("save_to_locker", false);
Payment payment = Payment.create(params);

Request Parameters

Field Type Description
order_id
Required
String order_id pertaining to the order for which the payment is started.
merchant_id
Required
String ID of the merchant_account that you hold with us.
payment_method_type
Required
String Must be CARD.
payment_method String One of VISA/MASTERCARD/MAESTRO/AMEX/RUPAY. This is usually inferred from the card number itself and we will take care of this if you are unable to provide this from your end.
card_token
Required
String A valid card token obtained using /card/list API. If you send this parameter, then card_number, name_on_card, card_exp_year, card_exp_month fields are not required.

If the token is generated using the /card/tokenize API, card_number, name_on_card, card_exp_year, card_exp_month and card_security_code fields are not required.
card_number
Required
String A valid credit/debit card number
name_on_card
Required
String Card holder name. Should contain alphabetical characters only.
card_exp_year
Required
String Represent the expiry year of the card as YY (two digits only)
card_exp_month
Required
String Represent the expiry month of the card as MM (two digits only)
card_security_code
Required
String CVV of the card. Usually three digits.
save_to_locker
Required
Boolean This is a boolean variable and accepts true/false. If set to true, then the card will be saved in locker when the transaction is successful. Else, the card will not be saved.
redirect_after_payment
Required
Boolean This is a boolean variable and accepts true/false. We recommend that you set this to true and use the redirection flow. If set to true, then the user is redirected to the return_url configured for the order. If set to false, then the user will be stopped at the response page from the gateway. Your client should be able to read the page/title to infer that the user has completed the transaction.
format
Required
String If it is set to json, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL.
is_emi Boolean Default is false. Set it to true if the user wishes to perform an EMI transaction on the given card.
emi_bank String Represents the bank that issued the card. Value must be one of the entries mentioned under EMI Bank in the support matrix below.
emi_tenure Integer The tenure of the EMI in number of months.

EMI Support Matrix

The following are the valid combinations for emi_bank and emi_tenure, although you need to check if bank has approved all the tenures for your gateway account. JusPay does not validate this for you.

EMI Bank EMI Tenure Supported Gateways
HDFC 3,6,9,12,18,24 PAYU, HDFC
CITI 3,6,9,12,18,24 PAYU
ICICI 3,6,9,12,18,24 PAYU, ICICI, CCAVENUE
SBI 3,6,9,12 PAYU, CCAVENUE
AXIS 3,6,9,12 PAYU, ICICI, CCAVENUE
SCB 3,6,9,12 ICICI
KOTAK 3,6,9,12 ICICI, CCAVENUE, PAYU
HSBC 3,6,9,12 ICICI, CCAVENUE, PAYU
AMEX 3,6,9,12 PAYU, CCAVENUE
INDUSIND 3,6,9,12,18,24 PAYU, CCAVENUE
ICICIDC 3,6,9,12 PAYU
AXISDC 3,6,9,12 PAYU

Example Response

{
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"
     }
   }
}
<Transaction>
{
  'order_id': u'1465893617',
  'status': u'PENDING_VBV',
  'txn_id': u'guest-1465893617-1',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507',
      'method': u'GET',
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "1465893617",
  @status = "PENDING_VBV",
  @txn_id = "guest-1465893617-1",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507",
      @method = "GET"
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] =>1465893617
  [status] => PENDING_VBV
  [txn_id] => guest-1465893617-1
  [method] => GET
  [url] => https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507
)
@object in.juspay.model.Payment
JSON:
{
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",  
   "method": "GET",
   "url": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"

}

Response Parameters

Field Type Description
order_id String OrderID for which the payment is being started.
txn_id String Transaction ID for the payment attempt.
status String Status of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete. Please do not validate this at your end.
payment String Contains the payment authentication details.
authentication String Contains the authentication details.
method String HTTP Method for authentication. Can be one of GET or POST
url String URL to which the user has to be taken to for completing the authentication
params String Present only when method is POST. Parameter map that has to be sent along with the URL for authentication.

NetBanking Payment

Create a payment transaction for NetBanking. Once you have the response, depending on the “method” attribute, you will have to take the next step. If you receive GET, then take the value in the “url” attribute and redirect the user to this location. If you receive POST, then “params” attribute will hold a map containing key value pairs.

For Web, you can create a form with these parameters as hidden variables and auto submit the form. Example code in Javascript: Serialize Parameters.

For Android, serialize this data such that it can be loaded to WebView directly via postData. Example code in Java: Serialize Parameters.

Definition

POST
https://api.juspay.in/txns
Payment.create(Map params);

Example Request

curl -X POST https://api.juspay.in/txns \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=NB" \
-d "payment_method=NB_ICICI" \
-d "redirect_after_payment=true" \
-d "format=json"
Juspay.Payments.create_net_banking_payment(
                order_id='1465893617',
                merchant_id='guest',
                payment_method_type='NB',
                payment_method='NB_ICICI',
                redirect_after_payment=False,
                format='json'
)
Payments.create_net_banking_payment(
                :order_id => '1465893617',
                :merchant_id => 'guest',
                :payment_method_type => 'NB',
                :payment_method => 'NB_ICICI',
                :redirect_after_payment => false,
                :format => 'json'
)
$params = array();
$params['order_id'] ="1465893617";
$params['merchant_id'] ="guest";
$params['payment_method_type'] ="NB";
$params['payment_method'] ="NB_ICICI";
$params['redirect_after_payment'] =False;
$params['format'] ="json";
$response = Payment::create($params);     
Map<String, Object> params = new LinkedHashMap();
params.put("order_id", "1465893617");
params.put("merchant_id", "guest");
params.put("payment_method_type", "NB");
params.put("payment_method", "NB_ICICI");
params.put("redirect_after_payment", false);
params.put("format", "json");
Payment payment = Payment.create(params);

Request Parameters

Field Type Description
order_id
Required
String order_id pertaining to the order for which the payment is started.
merchant_id
Required
String ID of the merchant_account that you hold with us.
payment_method_type
Required
String Must be NB
payment_method
Required
String The actual payment method that was selected by the user. For NetBanking transactions, it must be one of the below:
redirect_after_payment
Required
String This is a boolean variable and accepts true/false. We recommend that you set this to true. If set to true, then the user is redirected to the return_url configured for the order. If set to false, then the user will be stopped at the response page from the gateway. Your client should be able to read the page/title to infer that the user has completed the transaction.
format
Required
String If it is set to json, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL.

Example Response (having POST as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "POST",
       "url": "https://bank-url.com/payment-path/start",
       "params": {
            "key1": "v1",
            "key2": "v2",
            "key3": "v3"
       }
     }
   }
 }
<Transaction>
{
  'order_id': u'order_id',
  'status': u'PENDING_VBV',
  'txn_id': u'txn_id',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://bank-url.com/payment-path/start',
      'method': u'POST',
      'params': {
         "key1": "v1",
         "key2": "v2",
         "key3": "v3"
       }
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "order_id",
  @status = "PENDING_VBV",
  @txn_id = "txn_id",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://bank-url.com/payment-path/start",
      @method = "POST",
      @params:{
        :key1 => "v1",
        :key2 => "v2",
        :key3 => "v3"
      }
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] =>1465893617
  [status] => PENDING_VBV
  [txn_id] => guest-1465893617-1
  [method] => POST
  [url]  => https://bank-url.com/payment-path/start
  [params] =>
  (
    [key1] => v1
    [key2] => v2
    [key3] => v3
  )
)
 Payment Object
 {
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "PENDING_VBV",
   "method": "POST",
   "url": "https://bank-url.com/payment-path/start",
   "params": 
   {
     "key1": "v1",
     "key2": "v2",
     "key3": "v3"
   }
 }

Example Response (having GET as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"
     }
   }
 }
<Transaction>
{
  'order_id': u'1465893617',
  'status': u'PENDING_VBV',
  'txn_id': u'guest-1465893617-2',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507',
      'method': u'GET',
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "1465893617",
  @status = "PENDING_VBV",
  @txn_id = "guest-1465893617-1",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507",
      @method = "GET",
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] =>1465893617
  [status] => PENDING_VBV
  [txn_id] => guest-1465893617-1
  [method] => GET
  [url] => https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507
)
@object in.juspay.model.Payment
JSON:
{
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "PENDING_VBV",
   "method": "GET",
   "url": "https://api.juspay.in/pay/start/guest/8646a7a029974fa99995fec00340a507"
}

Response Parameters

Field Type Description
order_id String OrderID for which the payment is being started.
txn_id String Transaction ID for the payment attempt.
status String Status of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete.
payment String Contains the payment authentication details.
authentication String Contains the authentication details.
method String HTTP Method for authentication. Can be one of GET or POST
url String URL to which the user has to be taken to for completing the authentication
params String Present only when method is POST. Parameter map that has to be sent along with the URL for authentication.
Do not hardcode the params in your client
* Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis.

Handling POST

Handling POST

<form method="POST" action="$authentication.url" id="authForm">
  {{ for key in  $authentication.params }}
  <input type="hidden" name="$key" value="$authentication.params[$key]">
  {{ end }}
</form>
<script type="text/javascript">
 document.forms["authForm"].submit()
</script>

When you get POST as the authentication method in the response, then the customer must be redirected using a form. Example HTML code is given to you. Depending on your client language, choose the appropriate way to create the form.

Handling GET

Handling GET

<!-- Example for handling GET response -->
<script type="text/javascript">
 // assuming that you are passing the JSON response of /txns API directly here
 function handleJuspayGetResponse(juspayResponse) {
   window.location.href = juspayResponse.payment.authentication.url
 }
 handleJuspayGetResponse(response)
</script>

When you get GET as the authentication method in the response, you may load the URL directly into the customer’s browser. You can easily achieve this by send HTTP 302 from your server. However, if the API call was made from the browser, then you can utilize the code snippet provided.

Wallet Payment

Create a payment transaction for paying from a prepaid Wallet. Once you have the response, depending on the “method” attribute, you will have to take the next step. If you receive GET, then take the value in the “url” attribute and redirect the user to this location. If you receive POST, then “params” attribute will hold a map containing key value pairs.

For Web, you can create a form with these parameters as hidden variables and auto submit the form. Example code in Javascript: Serialize Parameters.

For Android, serialize this data such that it can be loaded to WebView directly via postData. Example code in Java: Serialize Parameters.

Definition

POST
https://api.juspay.in/txns
Payment.create(Map params);

Example Request

curl -X POST https://api.juspay.in/txns \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=WALLET" \
-d "payment_method=MOBIKWIK" \
-d "redirect_after_payment=true" \
-d "format=json"
Juspay.Payments.create_wallet_payment(
                order_id='1465893617',
                merchant_id='guest',
                payment_method='MOBIKWIK',
                redirect_after_payment=False,
                format='json')
Payments.create_wallet_payment(
                :order_id => '1465893617',
                :merchant_id => 'guest',
                :payment_method_type => 'WALLET',
                :payment_method => 'MOBIKWIK',
                :redirect_after_payment => false,
                :format => 'json'
)
$params = array();
$params['order_id'] ="1465893617";
$params['merchant_id'] ="guest";
$params['payment_method'] ="MOBIKWIK";
$params['payment_method_type'] ="WALLET";
$params['redirect_after_payment'] =False;
$params['format'] ="json";
$response = Payment::create($params);  
Map<String, Object> params = new LinkedHashMap();
params.put("order_id", "1465893617");
params.put("merchant_id", "guest");
params.put("payment_method_type", "MOBIKWIK");
params.put("payment_method", "WALLET");
params.put("redirect_after_payment", false);
params.put("format", "json");
Payment payment = Payment.create(params);

Request Parameters

Field Type Description
order_id
Required
String order_id pertaining to the order for which the payment is started.
merchant_id
Required
String ID of the merchant_account that you hold with us.
payment_method_type
Required
String Must be WALLET
payment_method
Required
String The actual payment method that was selected by the user. For WALLET transactions, it must be one of the below:
redirect_after_payment
Required
String This is a boolean variable and accepts true/false. We recommend that you set this to true. If set to true, then the user is redirected to the return_url configured for the order. If set to false, then the user will be stopped at the response page from the gateway. Your client should be able to read the page/title to infer that the user has completed the transaction.
format
Required
String If it is set to json, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL.

Example Response (having POST as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "POST",
       "url": "https://walllet-url.com/payment-path/start",
       "params": {
         "key1": "v1",
         "key2": "v2",
         "key3": "v3"
       }
     }
   }
 }
<Transaction>
{
  'order_id': u'order_id',
  'status': u'PENDING_VBV',
  'txn_id': u'txn_id',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://wallet-url.com/payment-path/start',
      'method': u'POST',
      'params': {
         "key1": "v1",
         "key2": "v2",
         "key3": "v3"
       }
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "order_id",
  @status = "PENDING_VBV",
  @txn_id = "txn_id",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://wallet-url.com/payment-path/start",
      @method = "POST",
      @params:{
        :key1 => "v1",
        :key2 => "v2",
        :key3 => "v3"
      }
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] => order_id
  [status] => PENDING_VBV
  [txn_id] => txn_id
  [method] => POST
  [url]  => https://wallet-url.com/payment-path/start
  [params] =>
  (
    [key1] => v1
    [key2] => v2
    [key3] => v3
  )
)
 Payment Object
 {
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "PENDING_VBV",
   "method": "POST",
   "url": "https://wallet-url.com/payment-path/start",
   "params": {
   "key1": "v1",
   "key2": "v2",
   "key3": "v3"
   }
 }

Example Response (having GET as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "PENDING_VBV",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": "https://wallet-url.com/payment-path/start?hello=world"
     }
   }
 }
<Transaction>
{
  'order_id': u'1465893617',
  'status': u'PENDING_VBV',
  'txn_id': u'shop-1465893617-2',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://api.juspay.in/pay/start/shop/8646a7a029974fa99995fec00340a507',
      'method': u'GET',
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "1465893617",
  @status = "PENDING_VBV",
  @txn_id = "shop-1465893617-2",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://api.juspay.in/pay/start/shop/8646a7a029974fa99995fec00340a507",
      @method = "GET",
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] =>1465893617
  [status] => PENDING_VBV
  [txn_id] => shop-1465893617-2
  [method] => GET
  [url] => https://api.juspay.in/pay/start/shop/8646a7a029974fa99995fec00340a507
)
@object in.juspay.model.Payment
JSON:
{
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "CHARGED",
   "method": "GET",
   "url": "https://api.juspay.in/pay/start/shop/8646a7a029974fa99995fec00340a507"
}

Response Parameters

Field Type Description
order_id String OrderID for which the payment is being started.
txn_id String Transaction ID for the payment attempt.
status String Status of the transaction. PENDING_VBV indicates that the transaction requires authentication to complete.
payment String Contains the payment authentication details.
authentication String Contains the authentication details.
method String HTTP Method for authentication. Can be one of GET or POST
url String URL to which the user has to be taken to for completing the authentication
params String Present only when method is POST. Parameter map that has to be sent along with the URL for authentication.
Do not hardcode the params in your client
* Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis.

Handling POST

Handling POST

<form method="POST" action="$authentication.url" id="authForm">
  {{ for key in  $authentication.params }}
  <input type="hidden" name="$key" value="$authentication.params[$key]">
  {{ end }}
</form>
<script type="text/javascript">
 document.forms["authForm"].submit()
</script>

When you get POST as the authentication method in the response, then the customer must be redirected using a form. Example HTML code is given to you. Depending on your client language, choose the appropriate way to create the form.

Handling GET

Handling GET

<!-- Example for handling GET response -->
<script type="text/javascript">
 // assuming that you are passing the JSON response of /txns API directly here
 function handleJuspayGetResponse(juspayResponse) {
   window.location.href = juspayResponse.payment.authentication.url
 }
 handleJuspayGetResponse(response)
</script>

When you get GET as the authentication method in the response, you may load the URL directly into the customer’s browser. You can easily achieve this by send HTTP 302 from your server. However, if the API call was made from the browser, then you can utilize the code snippet provided.

Wallet Direct Debit

Directly debit the amount from a Wallet that is linked to a Customer’s account. If the status in the response is CHARGED, then the payment is immediatley successful.

Note: This is an authenticated call unlike other transaction APIs. This API must be invoked from your server directly. DO NOT send the API Key to client.

Definition

POST
https://api.juspay.in/txns
Payment.create(Map params);

Example Request

curl -X POST https://api.juspay.in/txns \
-u api_key: \
-d "order_id=:order_id" \
-d "merchant_id=:merchant_id" \
-d "payment_method_type=WALLET" \
-d "direct_wallet_tokens=:direct_wallet_token"
-d "payment_method=MOBIKWIK" \
-d "redirect_after_payment=true" \
-d "format=json"
Juspay.Payments.create_wallet_payment(
      order_id='1465893617',
      merchant_id='guest',
      direct_wallet_token='directdebittoken123',
      payment_method='MOBIKWIK',
      redirect_after_payment=False,
      format='json'
)
Payments.create_wallet_payment(
                :order_id => '1465893617',
                :merchant_id => 'guest',
                :direct_wallet_token => 'directdebittoken123',
                :payment_method_type => 'WALLET',
                :payment_method => 'MOBIKWIK',
                :redirect_after_payment => false,
                :format => 'json'
)
$params = array();
$params['order_id'] ="1465893617";
$params['merchant_id'] ="guest";
$params['direct_wallet_token'] ="directdebittoken123";
$params['payment_method'] ="MOBIKWIK";
$params['payment_method_type'] ="WALLET;
$params['redirect_after_payment'] =False;
$params['format'] ="json";
$response = Payment::create($params);  
Map<String, Object> params = new LinkedHashMap();
params.put("order_id", "1465893617");
params.put("merchant_id", "guest");
params.put("payment_method_type", "MOBIKWIK");
params.put("payment_method", "WALLET");
params.put("redirect_after_payment", false);
params.put("format", "json");
Payment payment = Payment.create(params);

Request Parameters

Field Type Description
order_id
Required
String order_id pertaining to the order for which the payment is started.
merchant_id
Required
String ID of the merchant_account that you hold with us.
direct_wallet_token
Required
String Juspay wallet token for linked wallets. This is available in /cusotmers/:id/wallets API.
payment_method_type
Required
String Must be WALLET
payment_method
Required
String The actual payment method that was selected by the user. For WALLET transactions, it must be one of the supported wallets:
redirect_after_payment
Required
String This is a boolean variable and accepts true/false. We recommend that you set this to true. If set to true, then the user is redirected to the return_url configured for the order. If set to false, then the user will be stopped at the response page from the gateway.
format
Required
String If it is set to json, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL.

Example Response (having POST as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "CHARGED",
   "payment": {
     "authentication": {
       "method": "POST",
       "url": "https://api.juspay.in/pay/finish/:merchant-id/:txn-id",
       "params": {
         "key1": "v1",
         "key2": "v2",
         "key3": "v3"
       }
     }
   }
 }
<Transaction>
{
  'order_id': u'order_id',
  'status': u'CHARGED',
  'txn_id': u'txn_id',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://api.juspay.in/pay/finish/:merchant-id/:txn-id',
      'method': u'POST',
      'params': {
         "key1": "v1",
         "key2": "v2",
         "key3": "v3"
       }
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "order_id",
  @status = "CHARGED",
  @txn_id = "txn_id",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://api.juspay.in/pay/finish/:merchant-id/:txn-id",
      @method = "POST",
      @params:{
        :key1 => "v1",
        :key2 => "v2",
        :key3 => "v3"
      }
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] => order_id
  [status] => CHARGED
  [txn_id] => txn_id
  [method] => POST
  [url]  => https://api.juspay.in/pay/finish/:merchant-id/:txn-id
  [params] =>
  (
    [key1] => v1
    [key2] => v2
    [key3] => v3
  )
)
@object in.juspay.model.Payment
JSON:
{
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "CHARGED",
   "method": "POST",
   "url": "https://api.juspay.in/pay/finish/:merchant-id/:txn-id",
   "params": {
   "key1": "v1",
   "key2": "v2",
   "key3": "v3"
   }
}

Example Response (having GET as the method)

 {
   "order_id": ":order_id",
   "txn_id": ":txn_id",
   "status": "CHARGED",
   "payment": {
     "authentication": {
       "method": "GET",
       "url": "https://api.juspay.in/pay/finish/:merchant-id/:txn-id"
     }
   }
 }
<Transaction>
{
  'order_id': u'1465893617',
  'status': u'CHARGED',
  'txn_id': u'shop-1465893617-2',
  'payment': 
  <Payment>
  {
    'authentication': 
    <Authentication>
    {
      'url': u'https://api.juspay.in/pay/finish/:merchant-id/:txn-id',
      'method': u'GET',
    }
    ,
  }
  ,
}
<Payments::Transaction:0x00000a>
{
  @order_id = "1465893617",
  @status = "CHARGED",
  @txn_id = "shop-1465893617-2",
  @payment = 
  <Payments::Transaction::Payment:0x00000b>
  {
    @authentication =  
    <Payments::Transaction::Payment::Authentication:0x00000c>
    {
      @url = "https://api.juspay.in/pay/finish/:merchant-id/:txn-id",
      @method = "GET",
    }
    ,
  }
  ,
}
Payment Object
(
  [order_id] =>1465893617
  [status] => CHARGED
  [txn_id] => shop-1465893617-2
  [method] => GET
  [url] => https://api.juspay.in/pay/finish/:merchant-id/:txn-id
)
 Payment Object
 {
   "order_id": "1465893617",
   "txn_id": "guest-1465893617-1",
   "status": "CHARGED",
   "method": "GET",
   "url": "https://api.juspay.in/pay/finish/:merchant-id/:txn-id"
 }

Response Parameters

Field Type Description
order_id String Order ID for which the payment is being started.
txn_id String Transaction ID for the payment attempt.
status String Status of the transaction. Successful direct debit will return CHARGED status with pay/finish url which will redirect to your configured return url. PENDING_VBV indicates that the transaction requires authentication to complete.
payment String Contains the payment authentication details.
authentication String Contains the authentication details.
method String HTTP Method for authentication. Can be one of GET or POST
url String URL to which the user has to be taken to for completing the authentication
params String Present only when method is POST. Parameter map that has to be sent along with the URL for authentication.
Do not hardcode the params in your client
* Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis.

Handling POST

Handling POST

<form method="POST" action="$authentication.url" id="authForm">
  {{ for key in  $authentication.params }}
  <input type="hidden" name="$key" value="$authentication.params[$key]">
  {{ end }}
</form>
<script type="text/javascript">
 document.forms["authForm"].submit()
</script>

When you get POST as the authentication method in the response, then the customer must be redirected using a form. Example HTML code is given to you. Depending on your client language, choose the appropriate way to create the form.

Handling GET

Handling GET

<!-- Example for handling GET response -->
<script type="text/javascript">
 // assuming that you are passing the JSON response of /txns API directly here
 function handleJuspayGetResponse(juspayResponse) {
   window.location.href = juspayResponse.payment.authentication.url
 }
 handleJuspayGetResponse(response)
</script>

When you get GET as the authentication method in the response, you may load the URL directly into the customer’s browser. You can easily achieve this by send HTTP 302 from your server. However, if the API call was made from the browser, then you can utilize the code snippet provided.

UPI Payment

another_day=86400
while :
do
    if is_upi_completed(); then
        echo "Great. Come on in!"
        break
    else
        echo "Coming soon..."
        sleep $another_day
    fi
done

another_day=86400
while True:
    success = is_upi_available()
    if success:
        echo "Done. Lets go!"
        break
    else
        echo "Wait my friend..."
        sleep another_day
        continue

another_day=86400
while true:
    success = is_upi_available()
    if success
        echo "Done. Lets go!"
        break
    else
        echo "Wait my friend..."
        sleep(another_day)
        next

Coming Soon...

 

Outage

Represents a Scheduled Outage that is associated with either a Payment Gateway or a Bank (wherein the NetBanking or Direct Debit option will not be available)

List Outages

This API will return list of outages with banks and payment gateways. At this point, we only return the Scheduled downtimes that are announced by the Bank. You may use this to suggest alternative payment methods to your customers during the checkout process.

An example checkout screen with downtime info: Checkout screen with downtime info

Note: The API will contain the current outages and those in the near future as well. Please check the start time & end time to show only the outages that are currently ongoing.

Definition

GET
https://api.juspay.in/outages

Example Request

curl -X GET https://api.juspay.in/outages \
-u api_key:

Request Parameters

Field Type Description
id String Outage ID generated by JusPay.
object String Object type of entity, in this case it’ll be outage.
scope String Scope of the outage, one of BANK or GATEWAY. If GATEWAY, then all the payment methods supported by the gateway will be impacted. If BANK, then the issue pertains only to the bank.
gateway String Will be present only if the scope is GATEWAY. All the payment methods pertaining to the GATEWAY will be impacted.
You can mitigate this risk by having multiple gateways for each of the payment methods. The probability that two gateways will be down simulateneously is extremely low.
bank String Will be present only if the scope is BANK.
payment_method_type String Will be present only if the scope is BANK. One of NB or CARD. If NB, then NetBanking is impacted. If CARD, then cards issued by the bank will not work.
start_time String Indicates the start time of the outage event.
end_time String Indicates the outage completion time.
description String Short description about the nature of the outage. You can display this message to your users.

Example Response

{
    "object": "list",
    "list": [
        {
            "id": "5xtum1onxblhq28e",
            "object": "outage",
            "scope": "GATEWAY",
            "start_time": "2016-09-19T18:32:00+0000",
            "end_time": "2016-09-20T18:29:59+0000",
            "description": "ABCD PG is down",
            "gateway": "ABCD"
        },
        {
            "id": "b3xy6lc0egxvjt02",
            "object": "outage",
            "scope": "BANK",
            "start_time": "2016-09-19T18:30:00+0000",
            "end_time": "2016-09-21T12:30:00+0000",
            "description": "ABCD Bank cards are failing. Please use other options.",
            "bank": "ABCD Bank",
            "payment_method_type": "CARD"
        }
    ],
    "count": 2,
    "offset": 0,
    "total": 2
}
#
# Not implemented in the SDK yet. Please check the CURL tab.
#
#
# Not implemented in the SDK yet. Please check the CURL tab.
#

Recurring Payments

There are two steps to schedule a recurring payment transaction via Juspay:

  1. Create a customer via /customers, tokenize his card with /cards/tokenize, add it to the stored cards via /cards and then create a plan through /plans with those details.
  2. Create a subscription with the id got from step one. If the card requires authentication then you will get a validation url in response to validate the payment source once. Redirect the customer to it, Juspay will validate his payment source and will redirect the customer to the return url.
  • After the successful completion of step two, Juspay will periodically do the recurring debit for you and your customer according to schedule.

Create plan

Create a new recurring debit plan object. You may invoke this method for adding plans for your subscription. JusPay will respond with a plan ID that you can persist in your Database.

Definition

POST
https://api.juspay.in/plans

Example Request

curl -X POST https://api.juspay.in/plans \
-u api_key: \
-d "name= Plan_5" \
-d "object_reference_id"= "plan_5",
-d "amount=3000.00" \
-d "period_unit=3" \
-d "period=MONTH" \
-d "amount_type=FIXED" \
-d "description=Test plan"




Request Parameters

Field Type Description
name
Required
String Name of the plan.
object_reference_id String Unique plan ID defined by you.
amount
Required
Double Amount defined for the plan.
period_unit
Required
String Quantity of the time period defined for the billing cycle.
period
Required
String Unit of Time period for the billing cycle defined.Value could be :
amount_type
Required
String You have the option of either fixed or variable debit amounts controlled by this parameter. Value can be: FIXED or VARIABLE
description
Required
String Description of the plan.

Example Response

{
  "id": "plan_hfja9v8w2gevjur0",
  "object": "plan",
  "object_reference_id": "plan_5",
  "period": "DAY",
  "period_unit": 10,
  "name": "Plan_5",
  "description": "Test plan",
  "currency": "INR",
  "amount": 3000,
  "amount_type": "VARIABLE",
  "created": "2016-12-12T13:10:59Z",
  "updated": "2016-12-12T13:10:59Z"
}





Response Parameters

Field Type Description
id String Plan ID generated by JUSPAY. Has to be persisted in DB and should be used while creating a subscription
object String Type of the Juspay Entity, Object type is plan here.
object_reference_id String Unique plan ID defined by you.
period String Unit of Time period for the billing cycle defined.
period_unit String Quantity of the time period defined for the billing cycle.
name String Name of the plan.
description String Description for the plan.
currency String Unit of currency.
amount Double Amount for the plan.
amount_type String You have the option of either fixed or variable debit amounts controlled by this parameter. Value can be: FIXED or VARIABLE.
created String Date of plan creation.
updated String Last Updated time of the plan.

Get plan

Get a specified plan for the given plan ID.

Definition

GET
https://api.juspay.in/plans/:plan_id

Example Request

curl https://api.juspay.in/plans/plan_hfja9v8w2gevjur0 \
-u api_key: 




URL Embedded Parameter

Field Type Description
plan_id
Required
String Use the ID that is generated by JUSPAY during plan creation. You may also send the value that you sent in object_reference_id at the time of creating the plan.

Example Response

{
  "id": "plan_hfja9v8w2gevjur0",
  "object": "plan",
  "period": "DAY",
  "period_unit": 10,
  "name": "Plan_5",
  "description": "Test plan",
  "currency": "INR",
  "amount": 3000,
  "amount_type": "VARIABLE",
  "created": "2016-12-12T13:10:59Z",
  "updated": "2016-12-12T13:10:59Z"
}





Response Parameters

Field Type Description
id String Plan ID generated by JUSPAY. Has to be persisted in DB and should be used while creating a subscription
object String Type of the Juspay Entity, Object type is plan here.
period String Unit of Time period for the billing cycle defined.
period_unit String Quantity of the time period defined for the billing cycle.
name String Name of the plan.
description String Description for the plan.
currency String Unit of currency
amount Double Amount for the plan.
amount_type String You have the option of either fixed or variable debit amounts controlled by this parameter. Value can be: FIXED or VARIABLE
created String Date of plan creation.
updated String Last Updated time of the plan.

Create subscription

Create a new subscription object. You may invoke this method for scheduling recurring payment. Requires a valid recurring payment plan id created via /plans api. JusPay will respond with a subscription ID that you can persist in your Database.

Definition

POST
https://api.juspay.in/subscriptions

Example Request

curl -X POST https://api.juspay.in/subscriptions \
u api_key: \ 
-d "object_reference_id=sub1" \
-d "max_amount=10000.00" \
-d "plan=plan_hfja9v8w2gevjur0" \
-d "start_date=2016-12-12T00:00:00Z" \
-d "customer=cst_9uiehncjizlfcnps" \
-d "gateway_id=100" \
-d "payment_source=8825bc1d-993f-4f65-94b3-24048db1f239" \
-d "number_of_billing_cycles=2"
-d "source_validation_required=true"




Request Parameters

Field Type Description
object_reference_id
Required
String Unique ID that you use to represent the subscription in your database. This must be atleast 8 characters and must be unique.
max_amount
Required
String Maximum amount defined for a single recurring transaction.
planRequired
String Plan identifier for which you want to subscribe. This was generated by juspay on /plan/create api response.
start_date
Required
String Start date of subscription.
customer
Required
String Customer id for which you want to create subscription. This was generated by juspay on customer create api response.
gateway_id
Required
String Gateway Id of the gateway used for performing this and the future transactions.
payment_source
Required
String A valid card token obtained using /cards/list API. Card should have been added by the /card API. Other payment sources will be added soon.
number_of_billing_cycles
Required
String Represents total number of billing cycles, It will work out as the period defined in the plan times the no of billing cycles defined here. Ex a quarterly plan x 3 billing cycles = Recurring payment made for a year every 4 months.
source_validation_required Boolean This parameter is used to control the authentication requirement on the payment source. If it is set to false a direct debit transaction will be performed on the payment source without authenticating it with the user. Default value is true if unspecified.

Example Response

{
  "id": "sub_y8emhyhklyqni681",
  "object": "subscription",
  "object_reference_id=sub1",
  "state": "CREATED",
  "start_date": "2016-12-11T18:30:00Z",
  "end_date": "2016-12-31T18:30:00Z",
  "plan": {
    "id": "plan_hfja9v8w2gevjur0",
    "object": "plan",
    "period": "DAY",
    "period_unit": 10,
    "name": "Plan_5",
    "description": "Test plan",
    "currency": "INR",
    "amount": 3000,
    "amount_type": "VARIABLE",
    "created": "2016-12-12T13:10:59Z",
    "updated": "2016-12-12T13:10:59Z"
  },
  "quantity": 1,
  "object_reference_id": "sub1",
  "current_billing_cycle": 0,
  "number_of_billing_cycles": 2,
  "trial_period_end": null,
  "max_amount": 10000,
  "tax_percent": 0,
  "activated_on": "2016-12-12T13:57:25Z",
  "current_period_start": null,
  "current_period_end": null,
  "date_created": "2016-12-12T13:57:25Z",
  "last_updated": "2016-12-12T13:58:41Z",
  "gateway": "DUMMY",
  "payment_source": "8825bc1d-993f-4f65-94b3-24048db1f239",
  "validation_url": "https://api.juspay.in/subscriptions/sub_y8emhyhklyqni681/validate-payment-source",
  "return_url": "https://merchant-return-url.com/subscription",
  "source_validated": false,
  "source_validation_required": false
}




Response Parameters

Field Type Description
id String Subscription ID generated by JUSPAY.
object String Type of the Juspay Entity, Object type is Subscription here.
object_reference_id String Subscription ID defined by you.
state String State of subscription.
start_date String Starting Date of the Subscription.
end_date String Ending date of the subscription. No more debits will happen after this date.
plan Object The plan details specified for this subscription. Check the /plans api for further details.
quantity String Quantity of objects involved in the bill.
current_billing_cycle String The current billing cycle this subscription process is in.
number_of_billing_cycles String The total no of billing cycles in this subscription.
trial_period_end String The end of the trial period.
max_amount String Maximum amount defined for a single recurring transaction.
activated_on String The date of the plan activation.
date_created String Date of plan creation.
last_updated String Last Updated time of the subscription.
gateway String Gateway used for the transactions.
payment_source
String A valid card token used for the transactions.
validation_url String The customer has to be redirected to this url once to perform authentication for the deferred debit transactions, if source_validation_required was specified as true during creation.
return_url String The return url to which the customer will be redirected to after the authorisation of the validation_url occurs. Please use the get subscription api calls to know the status of the subscription.
source_validated Boolean Indicates whether the authorisation has been already performed for the given payment source.
source_validation_required Boolean Indicates whether authentication is required for the given payment source. The value was specified by you during plan creation.Use this as a decision flag to redirect the customer to the validation url.

Get subscription

This will return subscription entity for given identifier. It will also return list of payments associated with the subsciption.

Definition

GET
https://api.juspay.in/subscription/:subscription_id

Example Request

curl https://api.juspay.in/subscriptions/sub_y8emhyhklyqni681 \
-u api_key:




URL Embedded Parameter

Field Type Description
subscription_id
Required
String Use the ID that is generated by JUSPAY during subscription creation. You may also send the value that you sent in object_reference_id at the time of creating the subscription.

Example Response


  "id": "sub_y8emhyhklyqni681",
  "object": "subscription",
  "state": "CREATED",
  "start_date": "2016-12-11T18:30:00Z",
  "end_date": "2016-12-31T18:30:00Z",
  "plan": {
    "id": "plan_hfja9v8w2gevjur0",
    "object": "plan",
    "period": "DAY",
    "period_unit": 10,
    "name": "Plan_5",
    "description": "Test plan",
    "currency": "INR",
    "amount": 3000,
    "amount_type": "VARIABLE",
    "created": "2016-12-12T13:10:59Z",
    "updated": "2016-12-12T13:10:59Z"
  },
  "quantity": 1,
  "object_reference_id": "sub1",
  "current_billing_cycle": 0,
  "number_of_billing_cycles": 2,
  "trial_period_end": null,
  "max_amount": 10000,
  "tax_percent": 0,
  "activated_on": "2016-12-12T13:57:25Z",
  "current_period_start": null,
  "current_period_end": null,
  "date_created": "2016-12-12T13:57:25Z",
  "last_updated": "2016-12-12T13:58:41Z",
  "gateway": "DUMMY",
  "payment_source": "8825bc1d-993f-4f65-94b3-24048db1f239",
  "validation_url": "https://api.juspay.in/subscriptions/sub_y8emhyhklyqni681/validate-payment-source",
  "return_url": "https://merchant-return-url.com/subscription",
  "source_validated": false,
  "source_validation_required": false
}





Response Parameters

Field Type Description
id String Subscription ID generated by JUSPAY.
state String State of subscription.
start_date String Starting Date of the Subscription.
end_date String Ending date of the subscription. No more debits will happen after this date
plan Object The plan details specified for this subscription. Check the /plans/ api for further details.
quantity String Quantity of objects involved in the bill.
object_reference_id String Subscription ID defined by you.
current_billing_cycle String The current billing cycle this subscription process is in.
number_of_billing_cycles String The total no of billing cycles in this subscription.
trial_period_end String The end of the trial period.
max_amount String Maximum amount defined for a single recurring transaction.
activated_on String The date of the plan activation.
date_created String Date of plan creation.
last_updated String Last Updated time of the subscription.
gateway String Gateway used for the transactions.
payment_source
String A valid card token used for the transactions.
validation_url String The customer has to be redirected to this url once to perform authorization for the deferred debit transactions.
return_url String The return url to which the customer will be redirected to after the authorisation of the validation_url occurs.
source_validated Boolean Indicates whether the authorisation has been already performed for the given payment source.
source_validation_required Boolean Indicates whether authorisation is required for the given payment source. Use this to redirect the customer to the validation url.

Get Invoice

Invoices are generated whenever a scheduled transaction happens during the billing cycle. You can use this api to view the invoices generated for a particular subscription.

Definition

GET
https://api.juspay.in/subscriptions/:subscription_id/invoices

Example Request

curl https://api.juspay.in/subscriptions/tdne2rcd8dlxkeug/invoices \
-u api_key: 




URL Embedded Parameter

Field Type Description
subscription_id
Required
String Use the ID that is generated by JUSPAY during subscription creation.

Example Response

{
  "object": "list",
  "list": 
  [
    {
      "id": "tdne2rcd8dlxkeug",
      "object": "invoice",
      "amount_due": 3000,
      "attempted": false,
      "currency": "INR",
      "tax": 0,
      "subtotal": 3000,
      "date_created": "2016-12-16T14:34:30Z",
      "last_updated": "2016-12-16T14:34:30Z",
      "metadata": null,
      "tax_percent": 0,
      "paid": false,
      "attempts_count": 0,
      "subscription": {
        "id": "sub_kg71wnm2qzfv3sq1",
        "object": "subscription",
        "state": "ACTIVE",
        "start_date": "2016-12-14T18:30:00Z",
        "end_date": "2016-12-29T18:30:00Z",
        "plan": {
          "id": "plan_khxheoxq8yw4ondw",
          "object": "plan",
          "period": "DAY",
          "period_unit": 1,
          "name": "Plan_5",
          "description": "Test plan",
          "currency": "INR",
          "amount": 3000,
          "amount_type": "FIXED",
          "created": "2016-12-14T15:06:03Z",
          "updated": "2016-12-14T15:06:03Z"
        },
        "quantity": 1,
        "object_reference_id": "sub1",
        "current_billing_cycle": 2,
        "number_of_billing_cycles": 15,
        "trial_period_end": null,
        "max_amount": 10000,
        "tax_percent": 0,
        "activated_on": "2016-12-14T18:30:00Z",
        "current_period_start": "2016-12-15T18:30:00Z",
        "current_period_end": "2016-12-16T18:30:00Z",
        "date_created": "2016-12-15T15:06:58Z",
        "last_updated": "2016-12-16T14:34:30Z",
        "gateway": "DUMMY",
        "payment_source": null,
        "validation_url": "https://api.juspay.in/subscriptions/sub_kg71wnm2qzfv3sq1/validate-payment-source",
        "return_url": null,
        "source_validated": false,
        "source_validation_required": false
      },
      "customer": "cst_9uiehncjizlfcnps",
      "period_start_date": "2016-12-14T18:30:00Z",
      "period_end_date": "2016-12-15T18:30:00Z",
      "billing_cycle": 1
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}




Response Parameters

Field Type Description
id String Invoice ID generated by Juspay.
object String Type of the Juspay entity, Object type is invoice here.
amount_due Double Total amount of money charged for that transaction, inclusive of tax.
attempted boolean Indicates whether the transaction has been attempted.
currency String Unit of currency.
tax Double Total amount of money charged as tax.
subtotal Double Amount of money charged without tax.
date_created String Date of the invoice.
last_updated String Last updated time of the invoice.
tax_percent Double Percentage of amount as tax charged for this transaction.
paid boolean Represents the status of the transaction.
attempts_count Double Indicates the no of attempts made to authorize this transaction.
subscription Object The Juspay recurring payment subscription entity.
customer String The id of the Juspay customer entity object associated with this transaction.
period_start_date String The start date of the billing cycle which was invoiced.
period_end_date String The end date of the billing cycle which was invoiced.
billing_cycle String The present iteration number of the billing cycle.