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 10 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 10 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 List 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

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

Returns: Wallet Object

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

Returns: Wallet Object

"otp" should be returned also, so it can be sent with 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/

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

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.

* = Required (only for the specified API)

Additional Request (Form) Parameters for the Wallet APIs.

Field	Type	*	Description
gateway	String	*	Required only for the Create API. - Name of the gateway supplying the wallet.
otp	String		Optional only for the Link API. - OTP sent by the provider to the customer’s registered mobile number.

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.

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.

* = Required

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

The List API returns 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 ID of the wallet
object String "wallet_account"
wallet String Name of wallet
token String One time token used to debit from wallet (expires after ?? minutes)
current_balance String Wallet balance as of last balance update with the "Refresh Wallet API".
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.

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'

Parameter	Type	Description
id	String	The ID of the wallet
object	String	"wallet_account"
wallet	String	Name of wallet
token	String	One time token used to debit from wallet (expires after ?? minutes)
current_balance	String	Wallet balance as of last balance update with the "Refresh Wallet API".
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.

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.

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