--- page_source: https://juspay.io/sea/docs/hyper-checkout-sea/web/resources/custom-wallet-integration page_title: Custom Wallet Integration --- # Custom Wallet Integration Custom wallet integration helps you to display your in-house wallet/ loyalty points on the Juspay payment page as a payment option, this feature allows you to integrate and display your in-house wallets/ loyalty points through a front end contract in a simplified integration with Juspay. With custom wallet integration on Juspay, your customer has the ability to either pay partially or whole amount using the wallet balance. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/hyper-checkout/image1.png) **Steps to integrate custom wallet :** 1. Share the name of your in-house wallet with your Juspay integration POC, your in-house wallet name needs to be configured in the Juspay Backend. 2. Once the wallet name is configured in the Juspay Backend you will have to configure “Merchant Container” PG under the PG control centre of Juspay Dashboard, please follow the below steps for the same. i) Go to Juspay Dashboard >> EC Operation >> PG control centre  >> Click on other gateways and search for ‘Merchant Container’. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/hyper-checkout/Screenshot%202023-07-12%20at%203.11.59%20PM%20(1).png) ii) Post selecting ‘Merchant Container’, select Environment as Live and click on proceed. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/hyper-checkout/Screenshot%202023-07-12%20at%203.12.23%20PM%20(1).png) iii) Enter Gateway reference ID if required and click on proceed. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/hyper-checkout/Screenshot%202023-07-12%20at%203.12.49%20PM%20(1).png) iv) Then click on Save Gateway  Button to save the gateway. v) Under the Payment options tab check the checkbox against the name of your in-house wallet and on the next step select currency and click on Finish button. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/hyper-checkout/Screenshot%202023-07-12%20at%203.13.48%20PM%20(1).png) 3. Post configuring the Merchant Container PG you can start calling the session API along with an additional parameter and payload to  display your wallet on the Hypercheck out page. 4. **Calling session API -** You need to pass the below parameters into the “**metadata.merchant_container_list** ” parameter while calling the session API to pass the wallet information to Juspay and show the wallet payment option on the Hypercheckout page. | Key Name | Type | Description | Mandatory/Optional | |---|---|---|---| | payment_method | String | To be shared by Juspay | Mandatory | | payment_method_type | String | To be shared by Juspay | Mandatory | | display_name | String | Display name for the wallet | Mandatory | | balance_amount | String | Wallet balance amount in respective country's currency | Optional | | eligible_amount | String | Max amount that can be used for the amount | Mandatory | > **Warning** > You need to pass these parameters into the `metadata.merchant_container_list`**** parameter as string while calling the session API, you can refer to the sample payload for Session API call for reference. ## **Handling Order Status for Custom Wallet Integration** **Case 1:** **** User completes the transaction using in-house wallet + Any Other payment method **Order Status (For successful Debit) :** PARTIAL_CHARGED **Steps to be followed :** You will receive two transaction details in the Order status API response where Order amount will be the sum of the both transaction amount. One Transaction will have the amount paid by the customer online for which you will receive  status as ‘CHARGED’, for the other transaction you will receive the status as ‘TO_BE_COLLECTED’.  You will have to debit amount from the customer’s wallet using amount receive in the second transaction  Where the Payment method will be ‘your wallet’s name and payment method type will be ‘MERCHANT_CONTAINER’ **Case 2 :** **** User completes the transaction using only in-house wallet **Order Status (For successful Debit) :** TO_BE_CHARGED **Steps to be followed :** You will receive one transaction in the response of the order  Status API. You will have to debit the amount from the customer's wallet using the amount received in the transaction block where the Payment method will be your custom wallet’s name and payment method type will be ‘MERCHANT_CONTAINER’. > **Note** > * For transactions done through any other payment method you will get the transaction status as ‘CHARGED’ > * All other cases, where debit is pending or failed in other Instrument, the order status will be PENDING_VBV or AUTHENTICATION_FAILED / AUTHORIZATION_FAILED. Merchant to handle transactions similar to a normal transaction. > * In case the amount from in-house Wallet could not be deducted by the merchant, he will cancel the order in his database and raise a refund request for the non in-house wallet transaction. > * To refund transactions you should use [Txn ID based refund](https://docs.juspay.in/api-reference/docs/express-checkout/transaction-id-based-and-instant-refund) ## Sample Code Snippets: ### Sample Payload for Session API call: #### Request Code Snippet: ```request { "order_id": "testing-order-2205241516", "amount": "1000", "currency":"INR", "customer_email": "test@mail.com", "customer_phone": "9876543210", "payment_page_client_id": "spencers", "action": "paymentPage", "billing_address_first_name":"Test", "first_name": "", "last_name": "", "metadata.merchant_container_list" :"[{\"payment_method\":\"SPENCERS_WALLET\",\"payment_method_type\":\"MERCHANT_CONTAINER\",\"display_name\":\"Spencers Wallet\",\"balance_amount\":10,\"eligible_amount\":10}]" } ``` ### Sample Order Status API Response: #### Case 1: In-house Wallet + Any Other Payment Method: ```plaintext { "customer_email": "test@mail.com", "customer_phone": "9876543210", "customer_id": "testing-customer-two", "status_id": 21, "status": "PARTIAL_CHARGED", "id": "ordeh_2ede878cc54341b5abf15eabb4fbd5eb", "merchant_id": "neeraj_juspay_prod", "amount": 50, "currency": "INR", "order_id": "testing-order-147", "date_created": "2023-05-17T10:19:19Z", "return_url": "https://shop.merchant.com", "product_id": "", "payment_links": { "iframe": "https://api.juspay.in/merchant/ipay/ordeh_2ede878cc54341b5abf15eabb4fbd5eb", "web": "https://api.juspay.in/orders/ordeh_2ede878cc54341b5abf15eabb4fbd5eb/payment-page", "mobile": "https://api.juspay.in/orders/ordeh_2ede878cc54341b5abf15eabb4fbd5eb/payment-page" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "effective_amount": 50, "txn_list": [ { "txn_id": "neeraj_juspay_prod-testing-order-147-3-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2027", "card_reference": "", "saved_to_locker": false, "expiry_month": "11", "name_on_card": "name", "card_issuer": "JP Morgan", "last_four_digits": "1111", "using_saved_card": false, "card_fingerprint": "32qqi3sv1u5237fq7ura2rgqqb", "card_isin": "", "card_type": "CREDIT", "card_brand": "VISA", "using_token": false, "card_issuer_country": "", "juspay_bank_code": "JP_JPM" }, "payment_method": "VISA", "refunded": false, "amount_refunded": 0, "effective_amount": 40, "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozvtPyFpWTFTgrQyGg", "txn_detail": { "txn_id": "neeraj_juspay_prod-testing-order-147-3-1", "order_id": "testing-order-147", "status": "CHARGED", "error_code": null, "net_amount": 50, "surcharge_amount": null, "tax_amount": null, "txn_amount": 40, "offer_deduction_amount": null, "gateway_id": 100, "currency": "INR", "metadata": { "microapp": "hyperpay", "payment_channel": "WEB" }, "express_checkout": false, "redirect": true, "txn_uuid": "mozvtPyFpWTFTgrQyGg", "gateway": "DUMMY", "error_message": "", "created": "2023-05-17T10:23:35Z", "txn_flow_type": "CARD_TRANSACTION" }, "payment_gateway_response": { "resp_code": null, "rrn": null, "created": "2023-05-17T10:23:40Z", "epg_txn_id": null, "resp_message": null, "auth_id_code": "3nhxlt", "txn_id": null }, "gateway_id": 100, "gateway_reference_id": null, "metadata": { "payment_page_sdk_payload": "{\"metadata.merchantContainerList\":\"[{\\\"payment_method\\\":\\\"SPENCERS_WALLET\\\",\\\"payment_method_type\\\":\\\"MERCHANT_CONTAINER\\\",\\\"display_name\\\":\\\"Spencers Wallet\\\",\\\"balance_amount\\\":10,\\\"eligible_amount\\\":10}]\",\"amount\":\"50\",\"lastName\":\"wick\",\"action\":\"paymentPage\",\"currency\":\"INR\",\"firstName\":\"John\",\"description\":\"Payment Done for INR 1000\"}", "merchant_payload": "{\"metadata.merchantContainerList\":\"[{\\\"payment_method\\\":\\\"SPENCERS_WALLET\\\",\\\"payment_method_type\\\":\\\"MERCHANT_CONTAINER\\\",\\\"display_name\\\":\\\"Spencers Wallet\\\",\\\"balance_amount\\\":10,\\\"eligible_amount\\\":10}]\",\"customerPhone\":\"9876543210\",\"customerEmail\":\"test@mail.com\"}", "merchant_container_list": "[{\"payment_method\":\"SPENCERS_WALLET\",\"payment_method_type\":\"MERCHANT_CONTAINER\",\"display_name\":\"Spencers Wallet\",\"balance_amount\":10,\"eligible_amount\":10}]", "payment_page_client_id": "spencers" }, "offers": [], "status": "CHARGED" }, { "txn_id": "neeraj_juspay_prod-testing-order-147-3-2", "payment_method_type": "MERCHANT_CONTAINER", "auth_type": "", "payment_method": "SPENCERS_WALLET", "refunded": false, "amount_refunded": 0, "effective_amount": 10, "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozo3s4eoa1ts5Qb2Rw", "txn_detail": { "txn_id": "neeraj_juspay_prod-testing-order-147-3-2", "order_id": "testing-order-147", "status": "TO_BE_CHARGED", "error_code": null, "net_amount": 50, "surcharge_amount": null, "tax_amount": null, "txn_amount": 10, "offer_deduction_amount": null, "gateway_id": 267, "currency": "INR", "express_checkout": false, "redirect": false, "txn_uuid": "mozo3s4eoa1ts5Qb2Rw", "gateway": "MERCHANT_CONTAINER", "error_message": "", "created": "2023-05-17T10:23:35Z" }, "gateway_id": 267, "gateway_reference_id": null, "metadata": { "payment_page_sdk_payload": "{\"metadata.merchantContainerList\":\"[{\\\"payment_method\\\":\\\"SPENCERS_WALLET\\\",\\\"payment_method_type\\\":\\\"MERCHANT_CONTAINER\\\",\\\"display_name\\\":\\\"Spencers Wallet\\\",\\\"balance_amount\\\":10,\\\"eligible_amount\\\":10}]\",\"amount\":\"50\",\"lastName\":\"wick\",\"action\":\"paymentPage\",\"currency\":\"INR\",\"firstName\":\"John\",\"description\":\"Payment Done for INR 1000\"}", "merchant_payload": "{\"metadata.merchantContainerList\":\"[{\\\"payment_method\\\":\\\"SPENCERS_WALLET\\\",\\\"payment_method_type\\\":\\\"MERCHANT_CONTAINER\\\",\\\"display_name\\\":\\\"Spencers Wallet\\\",\\\"balance_amount\\\":10,\\\"eligible_amount\\\":10}]\",\"customerPhone\":\"9876543210\",\"customerEmail\":\"test@mail.com\"}", "merchant_container_list": "[{\"payment_method\":\"SPENCERS_WALLET\",\"payment_method_type\":\"MERCHANT_CONTAINER\",\"display_name\":\"Spencers Wallet\",\"balance_amount\":10,\"eligible_amount\":10}]", "payment_page_client_id": "spencers" }, "offers": [], "status": "TO_BE_CHARGED" } ] } ``` #### Case 2: Only In-house Wallet: ```plaintext { "customer_email": "test@mail.com", "customer_phone": "9876543210", "customer_id": "testing-customer-two", "status_id": 40, "status": "TO_BE_CHARGED", "id": "ordeh_6f99db8fce9b47cfaa7cfc16b04243a1", "merchant_id": "neeraj_juspay_prod", "amount": 50, "currency": "INR", "order_id": "testing-order-145", "date_created": "2023-05-16T14:10:03Z", "return_url": "https://shop.merchant.com", "product_id": "", "payment_links": { "iframe": "https://api.juspay.in/merchant/ipay/ordeh_6f99db8fce9b47cfaa7cfc16b04243a1", "web": "https://api.juspay.in/orders/ordeh_6f99db8fce9b47cfaa7cfc16b04243a1/payment-page", "mobile": "https://api.juspay.in/orders/ordeh_6f99db8fce9b47cfaa7cfc16b04243a1/payment-page" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "txn_id": "neeraj_juspay_prod-testing-order-145-1", "payment_method_type": "MERCHANT_CONTAINER", "auth_type": "", "payment_method": "SPENCERS_WALLET", "refunded": false, "amount_refunded": 0, "effective_amount": 50, "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozgbkwE4Hyvgkveuar", "gateway_id": 267, "offers": [] } ```