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 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:

WalletFlow1WalletFlow1

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

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.
  * = 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
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 ID of the wallet
objectString"wallet_account"
walletStringName of wallet
tokenStringOne time token used to debit from wallet (expires after ?? minutes)
current_balanceStringWallet balance as of last balance update with the "Refresh Wallet API".
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.

  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


What’s Next