API Reference

Wallet

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 when you call /wallets list APIlink icon). 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:

Wallet Linking Flow (Authentication)

This flow handles the setup phase where a user connects their wallet to your app for the first time.

  • Step 1: Call the List Wallets API link icon- To check if the wallet is already linked. 

  • Step 2: Call the Create Wallet API (Authenticate)link icon - Pass the user details and the command = authenticate. This triggers an OTP from the wallet provider to the user.

  • Step 3: Call the Link Wallet APIlink icon - Pass the OTP entered by the user and the command = link.

    • If successful, the API returns a wallet_token.

    • Save or Cache this state to enable the Linked Wallet Transaction Flow next time.

  • In this case, The wallet is listed but not linked

    1. Call the wallet Authenticate APIlink icon which will send an OTP to the registered mobile of the customer.

    2. Send the OTP back to Juspay using Link APIlink icon. Juspay will authenticate the OTP with the provider and then link the wallet.

Linked Wallet Transaction Flow (Direct Debit)

This flow handles "One-Click" payments for users who have already linked their wallet to your app.

  • Step 1: Call List Wallet APIlink icon - Give the user option to choose the wallet they wish to make the payment with.

  • Step 2: Call the Create Order APIlink icon - To register the transaction amount and generate a unique order_id. Ensure the customer_id is passed in this call - it is instrumental in fetching wallets.

  • Step 3: Call the Transaction API link icon- Pass payment_method_type: "WALLET", the stored wallet_token obtained from List Wallet API for the user-chosen wallet, and set txn_type: "DIRECT_DEBIT". - not necessary.

  • Step 4: Parse the response from the Transaction API.

    • Scenario A (Success): If status is CHARGED, show the success screen.

    • Scenario B (Low Balance): If the response contains a topup_url (or status INSUFFICIENT_BALANCE), redirect the user to that URL so they can add money to their wallet.

Standard Wallet Transaction Flow

This flow handles standard web-based wallets where the user must be redirected to the provider's website to login and pay.

  • Step 1: Call the Create Order API link icon- To register the transaction amount and generate a unique order_id.

  • Step 2: Call the Transaction APIlink icon - Pass the payment_method_type: "WALLET" and the specific payment_method code.

  • Step 3: Parse the response from the Transaction API. 

    • Look for the payment.authentication object in the JSON response. 

    • Extract the url URL (the redirect link).

    • Redirect the user's browser to this URL to complete the payment.

Last updated 3 months ago