Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

Overview of the Wallet APIs

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).

FieldAPI used forRequired Value
command=
authenticate
CreateSend it as "authenticate" if you want to start the authentication/linking process as soon as the wallet gets created.
command=
authenticate
*AuthenticateSend it as "authenticate" if you want to start the authentication/linking process.
command=
link
*LinkSend it as "link" if you want to complete the authentication/linking process.
command=
delink
*DelinkSend it as "delink" if you want to remove the authentication/linking of the wallet (if called by cstomer). Otherwise, remove linking only.
command=
refresh
*RefreshSend 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
ParameterTypeDescription
objectString"list"
list: [{...},{...},..]ArrayAn array of Wallet Objects     (see table below)
totalIntTotal wallets set against customer_id
offsetIntOffset from start (default is 0)
countIntCount 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:
ParameterTypeDescription
idStringThe unique identifier generated by Juspay for a particular wallet
objectStringMust be "wallet_account"
walletStringName of the Wallet Provider
tokenStringOne time token used to initiate a wallet transaction (expires after 15 minutes)
current_balanceStringThe balance available in the wallet as of the last refresh update. Available only for linked wallets.
linkedbooleanIf 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_refreshedStringRepresents the date & time when the balance was updated last.
metadata:wwwwwww
  {param1, param2,...}
ObjectCustom key-value sets can be passed here.
Example: {"mobile_number": "9999999999"}
gateway_reference_idStringUnique 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
ParameterTypeDescription
topup_txn_idStringMerchant transaction id for topup request
wallet_idStringThe ID of the wallet
statusStringStatus of the topup payment. "PENDING" means that the payment request is waiting a response from the customer.
payment_urlStringA 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
ParameterTypeDescription
payment_methods_eligibility:
    [{...},{...},..]
ArrayAn 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:
FieldTypeDescription
payment_methodStringName of the Payment Method which has eligibility criteria
payment_method_typeStringType of the payment method, like WALLET
descriptionStringDescription about the payment method
is_eligibleBooleanFlag which specifies if the customer is eligible for the payment method
eligibility_strategyStringDifferent strategy of eligibility. like Transaction eligibility, User eligibility
balanceDoubleBalance given in the gateway eligibility response
statusStringThe Juspay mapped error status for the corresponding gateway error code
(see Appendix below)
due_dateStringDue date of the pay later option bill payment.
gateway_error_codeStringError code
gateway_error_messageStringError message given by gateway
APPENDIX:   Eligibility status codes and meaning:
Status codeDescription
SUCCESSSuccessful
INSUFFICIENT_FUNDSThe wallet amount is less than the order amount
USER_NOT_FOUNDUser not found for that gateway
BAD_REQUESTBad Request
INVALID_DATAInvalid header or input data or any of the values are expired
NOT_ACCESSIBLEWhen the user does not have access because of the insufficient credit limit or blocked to that wallet
PENDING_DUESPending dues are present in the wallet which user needs to clear
UNAUTHORIZEDUnauthorized
ERRORAny other error mapping
  All other Wallet APIs return a Wallet Object
ParameterTypeDescription
idStringThe unique identifier generated by Juspay for a particular wallet
objectStringMust be "wallet_account"
walletStringName of the Wallet Provider
tokenStringOne time token used to initiate a wallet transaction (expires after 15 minutes)
current_balanceStringThe balance available in the wallet as of the last refresh update. Available only for linked wallets.
linkedbooleanIf 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_refreshedStringRepresents the date & time when the balance was updated last.
metadata:wwwwwww
  {param1, param2,...}
ObjectCustom key-value sets can be passed here.
Example: {"mobile_number": "9999999999"}
gateway_reference_idStringUnique 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.