Represents a wallet account that belongs to a customer. Wallet account is valid & usable only when your wallet provider has granted you permission for DIRECT WALLET DEBIT flow. To initiate a direct debit transaction, you need to authenticate and link the wallet with the respective customer account. 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 15 minutes of issuance (issued for a linked wallet when you call /wallets list API the List, Link, or Get APIs). 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. The 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 to create API with a 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. The wallet is listed but not linked

In this case, you need to create a wallet and then link it the listed wallet to allow direct wallet debit. Following are the steps to create and 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. The 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.

This flow diagram explains the usage more clearly, and shows how each of the nine Wallet APIs interact:

WalletFlow1

These nine Wallet APIs handle wallet/customer interaction on the Juspay server.

Note: A new one-time use token is generated for linked wallets each time the List, Link, or Get API is called. This token must be used immediately (within 15 minutes) for a direct debit transaction if direct debit is enabled by the wallet provider for your setup.

If a wallet is not linked, and a direct debit is enabled by the provider for your setup, you must use the authenticate and link APIs to link the wallet with the customer object, unless the wallet was previously linked, and you delinked it with the Delink API. In this case, a relink can be done be calling the Link API only.

List:

Returns a detailed list of wallets for a customer as an array of Wallet Objects (list), which may or may not be linked. If linked, a token is generated for it.

Required: customer_id Optional: version

Returns: object, list[{...},{...},...], total, offset, count

GET https://api.juspay.in/customers/:customer_id/wallets

Create:

Creates a wallet account for an existing customer with an option to authenticate.

Required: customer_id, gateway

Optional: command = authenticate, mobile_number

gateway_reference_id, client_auth_token

Returns: Wallet Object (see tables below)

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

Authenticate:

Starts the authentication and linking process of a wallet. Sends OTP to customer to authorize linking.

Required: wallet_id, command = authenticate

Optional: gateway_reference_id, client_auth_token

Returns: Wallet Object

Note: "otp" should be returned also, so it can be sent with the Link API (not shown in main document)

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

Link:

This API will forward OTP received from the authenticate API call to Juspay for linking. Once verified by customer, wallet will be linked.

Required: wallet_id, command = link Optional: otp

Returns: Wallet Object

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

Delink:

This API will delink a wallet from a customer. If wallet was delinked by customer, a relink must be done with Authenticate/Link APIs.

Required: wallet_id, command = delink

Returns: Wallet Object

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

Get:

Returns wallet details of a customer based on wallet_id.

Required: wallet_id

Returns: Wallet Object

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

Refresh:

This API will update the balance of a linked wallet from the wallet provider.

Required: wallet_id, command = refresh

Returns: Wallet Object

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

Update
MobileNumber:

This API can be used to update the mobile number passed in The Create wallet API.

Required: wallet_id, command = update, mobile_number

Optional: version, Content-Type

Returns: Wallet Object

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

Topup:

This API can be used to add money to a linked customer wallet.

Required: wallet_id, topup_txn_id, amount Optional: return_url

Returns: topup_txn_id, wallet_id, status, payment_url

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

Eligibility:

Determines if a customer has a linked wallet with sufficient amount for the order.

Required: customer_id, (amount or order_id)

Optional: gateway_data, gateway_reference_id

Returns: payment_methods_eligibility array (see tables below)

POST https://api.juspay.in/customers/:customer_id/eligibility

Refresh
All Wallets:

Returns an updated list of wallets for a customer as an array of Wallet Objects (list), which may or may not be linked. If linked, the current_balance is updated for it.

Required: customer_id, version, x-merchantId, Content-Type

Returns: object, list[{...},{...},...], total, offset, count

Note: version and Content-Type should be listed as Optional

GET https://sandbox.juspay.in/customers/:customer_id/wallets

Each of the Wallet APIs must include one of the following two
URL Embedded (Path) Parameters:

Field	*	Type	Description
customer_id	*	String	Use the Customer ID generated by Juspay or object reference ID given by merchant during customer creation.
wallet_id	*	String	The ID of the wallet.

* = Required only for the APIs using the URL format described above.

NOTE: Some Wallet APIs must include a command parameter in the request to

specify the action. (click to open table)

Command Parameters: (all have string type)

(set up as a Request (Form) Parameter).

Field		API used for	Required Value
command= authenticate		Create	Send it as "authenticate" if you want to start the authentication/linking process as soon as the wallet gets created.
command= authenticate	*	Authenticate	Send it as "authenticate" if you want to start the authentication/linking process.
command= link	*	Link	Send it as "link" if you want to complete the authentication/linking process.
command= delink	*	Delink	Send it as "delink" if you want to remove the authentication/linking of the wallet (if called by cstomer). Otherwise, remove linking only.
command= refresh	*	Refresh	Send it as "refresh" to get the updated balances.
command= update	*	Update MobileNumber	Send it as "update" to update the customer's mobile number.

* = Required (only for the specified API)

Additional Request (Form) Parameters for the Wallet APIs.

Field	Type	*	Description

Additional request parameters for the Create API :

gateway	String	*	Name of the gateway supplying the wallet.
mobile_number	String		Mobile number against which wallet has to be linked. The parameter can be used if the customer wants to link a different number than the one registered at merchant.
gateway_reference_id	String		Unique string identifier for the gateway supplying the wallet. Required in case of multiple MID setup
client_auth_token	String		Required for client side authentication

Additional request parameters for the Authenticate API :

gateway_reference_id	String		Unique string identifier for the gateway supplying the wallet. Required in case of multiple MID setup
client_auth_token	String		Required for client side authentication

Additional request parameter for the Link API :

otp

String

Optional for the Link API.
- OTP sent by the provider to the customer’s registered mobile number.

Additional request parameters for the Topup API :

topup_txn_id	String	*	Merchant transaction id for topup request.
amount	String	*	Amount that has to be added to the wallet
return_url	String		A fully qualified URL to which the customer will be redirected after payment completion.

Additional request parameters for the Eligibility API :

amount	String	Amount to check eligibility. Conditional (either order_id or amount are required)
order_id	String	Order ID to check eligibility. Conditional (either order_id or amount are required)
gateway_reference_id	String	Reference ID configured in case of multi MID setup.
gateway_data:-- {SIMPL: {payload:---}}	Object String	Details required for the gateway call.

Additional request parameters for the Update MobileNumber API :

mobile_number	String	*	The new/updated mobile number.
version	String		Refer to #Introduction for latest version ( >=2019-09-17).
Content-Type	String		Should be application/x-www-form-urlencoded .

Additional request parameters for the Refresh All Wallets API :

x-merchantid	String	*	The merchantId/username provided by Juspay.
version	String	* ?	Refer to #Introduction for latest version ( >=2019-09-17).
Content-Type	String	* ?	Should be application/x-www-form-urlencoded .

* = Required

The Response for each of the Wallet APIs is a Wallet Object, except as noted below for the List, Topup, Eligibility, and Refresh All Wallets APis. (click to open tables)

The List and Refresh All Wallets APIs return an array of Wallet Objects

Parameter	Type	Description
object	String	"list"
list: [{...},{...},..]	Array	An array of Wallet Objects (see table below)
total	Int	Total wallets set against customer_id
offset	Int	Offset from start (default is 0)
count	Int	Count of wallet objects to be included in response Default is same as 'total'

The Wallet Objects in the list array contain details of each wallet of a customer.

Wallet Object:

Parameter	Type	Description
id	String	The unique identifier generated by Juspay for a particular wallet
object	String	Must be "wallet_account"
wallet	String	Name of the Wallet Provider
token	String	One time token used to initiate a wallet transaction (expires after 15 minutes)
current_balance	String	The balance available in the wallet as of the last refresh update. Available only for linked wallets.
linked	boolean	If true, wallet is linked with the respective customer account. Merchant can then use the given token to debit directly from the wallet. Note: The Create, Authenticate, and Delink APIs will always return "false" for this parameter.
last_refreshed	String	Represents the date & time when the balance was updated last.
metadata:wwwwwww {param1, param2,...}	Object	Custom key-value sets can be passed here. Example: {"mobile_number": "9999999999"}
gateway_reference_id	String	Unique string identifier for the gateway supplying the wallet. Required in case of multiple MID setup

The Topup API returns a JSON block which includes

topup_txn_id, wallet_id, status, and payment_url parameters

Parameter	Type	Description
topup_txn_id	String	Merchant transaction id for topup request
wallet_id	String	The ID of the wallet
status	String	Status of the topup payment. "PENDING" means that the payment request is waiting a response from the customer.
payment_url	String	A fully qualified URL such as https://shop.merchant.com/ to which the customer will be redirected to acknowledge the payment. This URL shouldn’t contain any query parameters.

The Eligibility API returns an array of EligibilityData Objects

Parameter	Type	Description
payment_methods_eligibility: [{...},{...},..]	Array	An array of EligibilityData Objects. Lists all the payment methods which have eligibility criteria.

The elements returned in the payments_eligibility_array array are EligibilityData Objects, that provide details of each payment method of a customer.

EligibilityData Object:

Field	Type	Description
payment_method	String	Name of the Payment Method which has eligibility criteria
payment_method_type	String	Type of the payment method, like WALLET
description	String	Description about the payment method
is_eligible	Boolean	Flag which specifies if the customer is eligible for the payment method
eligibility_strategy	String	Different strategy of eligibility. like Transaction eligibility, User eligibility
balance	Double	Balance given in the gateway eligibility response
status	String	The Juspay mapped error status for the corresponding gateway error code (see Appendix below)
due_date	String	Due date of the pay later option bill payment.
gateway_error_code	String	Error code
gateway_error_message	String	Error message given by gateway

APPENDIX: Eligibility status codes and meaning:

Status code	Description
SUCCESS	Successful
INSUFFICIENT_FUNDS	The wallet amount is less than the order amount
USER_NOT_FOUND	User not found for that gateway
BAD_REQUEST	Bad Request
INVALID_DATA	Invalid header or input data or any of the values are expired
NOT_ACCESSIBLE	When the user does not have access because of the insufficient credit limit or blocked to that wallet
PENDING_DUES	Pending dues are present in the wallet which user needs to clear
UNAUTHORIZED	Unauthorized
ERROR	Any other error mapping

All other Wallet APIs return a Wallet Object

Parameter	Type	Description
id	String	The unique identifier generated by Juspay for a particular wallet
object	String	Must be "wallet_account"
wallet	String	Name of the Wallet Provider
token	String	One time token used to initiate a wallet transaction (expires after 15 minutes)
current_balance	String	The balance available in the wallet as of the last refresh update. Available only for linked wallets.
linked	boolean	If true, wallet is linked with the respective customer account. Merchant can then use the given token to debit directly from the wallet. Note: The Create, Authenticate, and Delink APIs will always return "false" for this parameter.
last_refreshed	String	Represents the date & time when the balance was updated last.
metadata:wwwwwww {param1, param2,...}	Object	Custom key-value sets can be passed here. Example: {"mobile_number": "9999999999"}
gateway_reference_id	String	Unique string identifier for the gateway supplying the wallet. Required in case of multiple MID setup

NOTE: For linked wallets, the balance in the response may not be the current balance. The last_refreshed field represents the date & time when the balance was updated last. Use the Refresh or Refresh All Wallets APIs to update the balance for individual wallets. This results in a network call to the wallet provider and hence the response might be slow.