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:
- Call the wallet to
create
API with acommand=authenticate
parameter which will send an OTP to the registered mobile of the customer. - Send the OTP back to Juspay using
link
API. Juspay will authenticate the OTP with the provider and then link the wallet.
- Call the wallet to
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:
- Call the wallet
authenticate
API which will send an OTP to the registered mobile of the customer. - Send the OTP back to Juspay using
link
API. Juspay will authenticate the OTP with the provider and then link the wallet.
- Call 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:
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.







MobileNumber:



All Wallets:

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. |
NOTE: Some Wallet APIs must include a command parameter in the request tospecify 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. |
Field | Type | * | Description |
---|
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 |
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 |
otp | String |
Optional for the Link API. - OTP sent by the provider to the customer’s registered mobile number. |
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. |
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. |
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 . |
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 . |
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' |
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. |
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 |
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 |