--- page_source: https://juspay.io/in/docs/payment-method-integrations/express-checkout-sdk/reward-integration/twid-v2 page_title: TWID V2 --- # **Twid S2S (Rewards) Onboarding and API Specification** ## **1. Pre-requisites** ### Step 1 Configuring a new gateway account for Twid_v2 on the Juspay Dashboard **→** Sandbox Dashboard Url - [https://sandbox.portal.juspay.in](https://sandbox.portal.juspay.in) → Production Dashboard Url - [https://portal.juspay.in/](https://portal.juspay.in/)**** **• Select TWID_V2 Gateway** **• Enter Gateway Credentials** ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Twid_v2-n0g5Z.png) *All Fields are Mandatory except Resend Otp Wait Time* ### Step 2 Updating existing gateway account to add Twid_v2 from the Juspay Dashboard The same gateway can be modified. ## **2. Sample End-to-end User flow** ### Step 1.1. Best Reward and Instrument Locking • Once the user is logged in and if they are eligible for any rewards, the best reward is automatically displayed as the default option in Rewards home page. • Once the user selects a reward, only the Payment Instruments which are eligible for that specific reward will be displayed while rest of them will be filtered out ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(3).png) *More Rewards and Instrument Locking* ### Step 1.1. More Rewards & Voucher Selection • The user may choose to select another reward from the list of rewards that they are eligible for by clicking on ‘View All Rewards’. • And the user may also apply a voucher from amongst the list of vouchers that they are eligible for on top of the selected reward. • However, the voucher cannot be applied without selecting a Reward. While they can pay using a Reward alone without clubbing it with a Voucher. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(5).png) *More Rewards and Voucher Selection* ### Step 1.1. Split Payment & Transaction The total order amount will be split into two transactions one for the Reward (and Voucher if applied) and one more for the secondary transaction based on the other payment instrument selected. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Untitled%20presentation%20(7).png) *Split Payment and Transaction* ### Step 1.1. Note * Once a phone number is used to link with _Twid Rewards_ on a merchant platform, it will remain linked forever with that user account for that merchant. * If the authentication failed or if the entered OTP is incorrect, a user can re-attempt to get a new OTP not more than 5 times in the span of every 30 minutes. * A _Twid Voucher_ can be applied only if the user selects one of the _Twid Rewards_ that the user is eligible for. * A user can select a maximum of one _Twid Reward_ and a maximum of one Twid Voucher per Order. ## **3. Sample Requests and Responses** **getPaymentMethods for Twid:** **Request:** #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "efdd0cb3-bd51-47ea-99f3-546b3fe71484", "payload": { "action": "paymentMethod" } } ``` **Response:** #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "efdd0cb3-bd51-47ea-99f3-546b3fe71484", "payload":{ "tpvPaymentMethods": [], "emandatePaymentMethods": [], "paymentMethods": [ { "wallet_direct_debit_support": true, "payment_method": "TWID", "payment_method_type": "REWARD", "supported_features": [ { "feature_name": "wallet_direct_debit", // only for linking flow "supported_by_default": true }, { "feature_name": "link_and_pay", // only for linking flow "supported_by_default": true }, { "feature_name": "eligibility", "supported_by_default": true } ], "payment_method_sub_type": "REWARD", "juspay_bank_code": "JP_TWID", "nick_name": "Twid", "supported_by_default": true, "description": "Twid Rewards" } ] } } ``` ### **Process SDK Call for Rendering TWID Rewards** **Eligibility Request** #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "445dc8cf-9fec-4f3e-8286-45af2146cdfb", "payload": { "version": "2024-10-07", // current date "requestId": null, "data": { "wallets": [ { "mobile": "9742144874", "email": "test@gmail.com", "customerId": "test_customer", "checkType": [ "twid" ] } ] }, "clientAuthToken": "tkn_15af534ad81a4a0b9fc317a97542965c", "signature": "", "amount": "100", "action": "eligibility" } } ``` **Eligibility Response** #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "3e2dc248-f7f1-417d-950e-60dabbf409eb", "payload": { "action": "eligibility", "wallets": [ { "paymentMethodsEligibility": [ { "voucherInfo": [ { "voucherTnc": "Visit the link https://bit.ly/3YcF7EO to Download *Mc Delivery* App from App/Play store.\r\nOffer Valid on McDelivery Orders Only.\r\nOffer Valid till stock ends.\r\nOffer Valid on App /Web & Msite.\r\nOffer Applicable on Advance & Regular orders.\r\nOffer Valid in West & South McDonald's India", "voucherId": 628389, "voucherAmount": 25, "type": "VOUCHER", "title": "cashback", // cashback voucher "subTitle": "Get a Free Medium Fries + piri piri mix on purchase of ₹299 or more", "expiresOn": "Expires on 31st Dec 2024", "code": "TWIDCRISPY" }, { "voucherAmount": 50, "voucherId": 1596, "code": "TestDicsount50", "title": "discount", // instant discount voucher "type": "VOUCHER", "subTitle": "Get a Free Medium Fries + piri piri mix on purchase of ₹299 or more", "expiresOn": "Expires on September 20, 2023", "voucherTnc": "Coupon is valid till date 9th Sep 2023\nCoupon is applicable only once per customer and is non-refundable\nCoupons can not be clubbed with any other offers\nIf the bill value is less than the cashback amount, the coupon code will be fully 100% utilized. The balance amount is not refundable.\nOther T&Cs may apply\n" } ], "status": "SUCCESS", "rewardDetails": { "subTitle": "Save Rs 34 using 34 Bonus Rewards Points + Get Rs 1 cashback", "bestRewardType": "burn", "bestRewardId": 7892159, "otpVerificationRequired": false }, "redeemableInfo": [ { "value": 34, "type": "BURN", "toggle": false, "title": "Save Rs 34 using 34 Bonus Rewards Points", "rewardType": "BURN", "rewardId": "7892159", "issuerType": "brand", "brandName": "Bonus Rewards", "brandLogo": "https://cdn.twidpay.com/co/s2s_issuer_images/twid_square.png" }, { "issuerType": "bank", "toggle": false, "rewardId": "212267", "rewardType": "BURN", "value": 998, "paymentLockingPayloadV2": { "rewardRules": { "allowDefaultOptions": false, "options": [ { "paymentMethodType": "CARD", "cardFilters": [ { "enable": true, "cardBins": [ "356139::356139", "356165::356166", "404638::404638", "404652::404652", "405023::405023", "405204::405204", "405210::405210", "512345::512345" ] } ], "enable": true } ] } }, "brandLogo": "https://cdn.twidpay.com/co/s2s_issuer_images/hdfc_square.svg", "title": "Save Rs 998 using 998 HDFC Bank Points", "type": "BURN", "brandName": "HDFC Bank" }, { "issuerType": "brand", "brandLogo": "https://cdn.twidpay.com/co/s2s_issuer_images/cobb_square.png", "brandName": "Cobb", "earnablePoints": 20, "rewardId": "212217", "rewardType": "EARN", "title": "Earn 4X rewards. 20 Cobb Points", "toggle": true, "type": "EARN", "value": null }, { "brandLogo": "https://cdn.twidpay.com/co/s2s_issuer_images/cobb_square.png", "brandName": "Cobb", "issuerType": "brand", "paymentLockingPayloadV2": { "rewardRules":{ "allowDefaultOptions": true, "options": [ { "enable": false, "paymentMethodType": "CASH" } ] } }, "rewardId": "212217", "rewardType": "BURN_EARN", "title": "Save Rs 2 using 8 Cobb Points + Earn 20 Cobb Points", "toggle": true, "type": "BURN_EARN", "value": 2, "earnablePoints": 20 } ], "paymentMethodType": "REWARD", "paymentMethod": "TWID", "isEligible": true, "gatewayErrorMessage": "success", "eligibilityStrategy": "USER", "description": "Twid Rewards" } ], "orderId": "IAOY2386DEKZ1189UUSN", "customerId": "9742144874" } ] }, "errorMessage": "", "errorCode": "", "error": false } ``` Note: * There are two types of vouchers (“discount” and “cashback”). The same can be identified by the value of the key “title” under voucher_info object in redeemable_info of eligibility response. * Refer [Payment Locking](https://juspay.io/in/docs/hyper-checkout/android/resources/payment-locking) to consume `paymentLockingPayloadV2.rewardRules` to filter instruments which are eligible with the corresponding reward. * There are two different flows available for using Twid Rewards - * Linking Flow ( `rewardDetails.optVerification : true` ) * Users would have to link with OTP authentication before they can see Rewards. * Non-Linking Flow ( `rewardDetails.optVerification : false` or the key itself will not be present) * No authentication required. Users can see Rewards directly if they have any eligible Rewards. ### Twid Reward consent & linking (Only for Linking Flow**) **Authenticate (Create Wallet) Request:** (Only for Linking Flow**) #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "048227ea-91f6-4f41-8e36-39e44bd3158c", "payload": { "walletName": "TWID_V2", "mobileNumber": "7093125824", "clientAuthToken": "tkn_99ade0fcd97f4d4aaf0d1e84f472a4ac", "command": "authenticate", "action": "createWallet" } } ``` **Sample Response:** (Only for Linking Flow**) #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "a9dab6ef-05ad-4f36-9305-11dafdb9af4e", "payload": { "wallet": "TWID_V2", "token": null, "auth_params": { "is_resend_allowed": true, "resend_wait_time": "15", "is_submit_allowed": true }, "last_refreshed": null, "object": "wallet_account", "metadata": { "mobile_number": "9078814008" }, "id": "wlm_q2UkPy9Qk8gadYjc", "current_balance": null, "gateway_reference_id": "twid-s2s", "sub_details": [ { "payment_method": "TWID", "payment_method_type": "REWARD", "last_refreshed": null, "current_balance": null } ], "linked": false }, "errorMessage": "", "errorCode": "", "error": false } ``` **Link Wallet Request:** (Only for Linking Flow**) #### Shell Code Snippet: ```shell { "service": "in.juspay.ec", "requestId": "048227ea-91f6-4f41-8e36-39e44bd3158c", "payload":{ "walletName": "TWID_V2", "walletId": "wlm_q2UkPy9Qk8gadYjc", "requestId": null, "otp": "1234", "clientAuthToken": "tkn_b82039848c504825aaa070a81f4e1086", "action": "linkWallet" } } ``` **Sample Response:** (Only for Linking Flow**) #### Shell Code Snippet: ```shell { "wallet": "TWID_V2", "token": "tkn_4739ad910fde4c50a7f0196b1fa3836f", "auth_params": { "is_resend_allowed": false, "resend_wait_time": "15", "is_submit_allowed": false }, "last_refreshed": null, "object": "wallet_account", "id": "wlm_q2UkPy9Qk8gadYjc", "current_balance": null, "sub_details": [ { "payment_method": "TWID", "payment_method_type": "REWARD", "last_refreshed": null, "current_balance": null } ], "linked": true } ``` ### Order Create **Sample Request** #### Shell Code Snippet: ```shell curl --location 'https://sandbox.juspay.in/orders' \ --header 'Authorization: Basic \ --form 'order_id=""' \ --form 'amount="1000.00"' \ --form 'currency="INR"' \ --form 'customer_id=""' \ --form 'customer_email=""' \ --form 'customer_phone=""' \ --form 'return_url="http://www.google.com/"' \ --form 'redirect_after_payment="true"' \ --form 'metadata.JUSPAY:gateway_reference_id=""' ``` **Sample Response** #### Shell Code Snippet: ```shell { "status": "CREATED", "status_id": 1, "id": "ordeh_d330ffa58c8c452e80bbf313af438fc0", "order_id": "HD-1696922937", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_d330ffa58c8c452e80bbf313af438fc0/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_d330ffa58c8c452e80bbf313af438fc0/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_d330ffa58c8c452e80bbf313af438fc0/payment-page" } } ``` ### Transaction Create **Sample Txns Process Payload** #### Txn Process - With Burn Reward Code Snippet: ```txn process - with burn reward { "requestId": "eee6f65e-23dc-42e1-ad7c-ec3cddd64ac9", "service": "in.juspay.hyperapi", "payload": { "action": "cardTxn", "orderId": "hyperorder45314", "paymentMethod": "VISA", "cardNumber": "4**************4", "cardExpMonth": "05", "cardExpYear": "25", "cardSecurityCode": "***", "saveToLocker": true, "clientAuthToken": "tkn_0e37edc631d647fdb606ab48ccfc4213", "tokenize": true, "cardNickName": "User - HDFC", "additionalPaymentDetails": [ { "direct_wallet_token": "tk_2c799f295ae748e991c78af11bb2c8f2", "payment_method": "TWID", "payment_method_type": "REWARD", "reward_id": "140233615", "reward_mode": "burn", "split_amount": "500" // reward_amount } ] } } ``` #### Txn Process - With Earn Reward Code Snippet: ```txn process - with earn reward { "requestId": "eee6f65e-23dc-42e1-ad7c-ec3cddd64ac9", "service": "in.juspay.hyperapi", "payload": { "action": "cardTxn", "orderId": "hyperorder45314", "paymentMethod": "VISA", "cardNumber": "4**************4", "cardExpMonth": "05", "cardExpYear": "25", "cardSecurityCode": "***", "saveToLocker": true, "clientAuthToken": "tkn_0e37edc631d647fdb606ab48ccfc4213", "tokenize": true, "cardNickName": "User - HDFC", "additionalPaymentDetails": [ { "direct_wallet_token": "tk_2c799f295ae748e991c78af11bb2c8f2", "payment_method": "TWID", "payment_method_type": "REWARD", "reward_id": "140233615", "reward_mode": "earn", "split_amount": "0" // (split_amount is zero for earn type rewards) } ] } } ``` #### Txn Process - With Earn Reward + Voucher Code Snippet: ```txn process - with earn reward + voucher { "requestId": "eee6f65e-23dc-42e1-ad7c-ec3cddd64ac9", "service": "in.juspay.hyperapi", "payload": { "action": "cardTxn", "orderId": "hyperorder45314", "paymentMethod": "VISA", "cardNumber": "4**************4", "cardExpMonth": "05", "cardExpYear": "25", "cardSecurityCode": "***", "saveToLocker": true, "clientAuthToken": "tkn_0e37edc631d647fdb606ab48ccfc4213", "tokenize": true, "cardNickName": "User - HDFC", "additionalPaymentDetails": [ { "direct_wallet_token": "tk_2c799f295ae748e991c78af11bb2c8f2", "payment_method": "TWID", "payment_method_type": "REWARD", "reward_id": "140233615", "reward_mode": "earn", "voucher_id": "628389", // reward_amount + voucher_amount (reward_amount is zero for earn type rewards) (voucher_amount is zero for cashback vouchers) "split_amount": "50" } ] } } ``` #### Txn Process - With Burn Reward + Voucher Code Snippet: ```txn process - with burn reward + voucher { "requestId": "eee6f65e-23dc-42e1-ad7c-ec3cddd64ac9", "service": "in.juspay.hyperapi", "payload": { "action": "cardTxn", "orderId": "hyperorder45314", "paymentMethod": "VISA", "cardNumber": "4**************4", "cardExpMonth": "05", "cardExpYear": "25", "cardSecurityCode": "***", "saveToLocker": true, "clientAuthToken": "tkn_0e37edc631d647fdb606ab48ccfc4213", "tokenize": true, "cardNickName": "User - HDFC", "additionalPaymentDetails": [ { "direct_wallet_token": "tk_2c799f295ae748e991c78af11bb2c8f2", "payment_method": "TWID", "payment_method_type": "REWARD", "reward_id": "140233615", "reward_mode": "burn", "voucher_id": "628389", "split_amount": "500" // reward_amount + voucher_amount (voucher_amount = 0 for cashback type vouchers) } ] } } ``` **Sample Txns Process Response** #### Txn Process Response Code Snippet: ```txn process response {"success":false,"message":"No Data found for the given path"} ``` **Note:** 1. For split_amount key, the total discount amount i.e., Reward Amount + Voucher Amount (Only Instant Discount, if any) should be passed. Cashback type Voucher amount should not be included. 2. Voucher cannot be applied alone, for any voucher to be applied, there has to be a Reward applied otherwise the voucher cannot be applied. 3. Both, voucher_id and reward_id has to be passed as a String type. 4. direct_wallet_token: should include the token received from RefreshWallet response. This is a mandatory key to be passed if it’s via Linking Flow. This is not required for Non-Linking flow. 5. The above is just a sample process response (in an ideal case where we receive terminal status before SDK terminate), although it’s possible we do not get a terminal status by that time. Hence, it is recommended to always poll for order-status response or configure and consume the webhook response for order-status. **Sample Txns API** #### Shell Code Snippet: ```shell curl --location 'https://sandbox.juspay.in/txns' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic ==' \ --data-urlencode 'order_id=' \ --data-urlencode 'merchant_id=merchant_id' \ --data-urlencode 'payment_method_type=CARD' \ --data-urlencode 'payment_method=VISA' \ --data-urlencode 'redirect_after_payment=true' \ --data-urlencode 'format=json' \ --data-urlencode 'additional_payment_details=[ { "payment_method_type": "REWARD", "payment_method": "TWID", "split_amount": "254", "reward_id": "212217", "reward_mode": "burn", "voucher_id": "1641" } ]' \ --data-urlencode 'card_number=4111111111111111' \ --data-urlencode 'card_exp_month=11' \ --data-urlencode 'card_exp_year=25' \ --data-urlencode 'name_on_card=Test' \ --data-urlencode 'card_security_code=123' ``` **Sample Txns Response** #### Shell Code Snippet: ```shell { "order_id": "HD-1696763788", "status": "PENDING_VBV", "payment": { "authentication": { "url": "https://sandbox.juspay.in/v2/txns/show-surcharge/azhar_test/mozmFxucfhUFkd5tfNf?cardIssuerBankName%3DHDFC%20Bank%26cardType%3DDEBIT%26paymentMethod%3DVISA%26paymentMethodType%3DCARD", "method": "GET" } }, "txn_uuid": "mozmFxucfhUFkd5tfNf", "offer_details": { "offers": [] }, "txn_id": "azhar_test-HD-1696763788-1-1" } ``` ### **Order Status** **Sample Request** #### Shell Code Snippet: ```shell curl --location 'https://api.juspay.in/ecr/orders/?options.add_full_gateway_response=true' \ --header 'Authorization: Basic Auth' ``` **Sample Response** #### Shell Code Snippet: ```shell { "customer_email": "krishna.gprasad@juspay.in", "customer_phone": "8142954524", "customer_id": "cth_05be651c9a5755db", "status_id": 21, "status": "CHARGED", "id": "ordeh_674a508675bf4cc184747387df7c0236", "merchant_id": "azharamin", "amount": 1000, "currency": "INR", "order_id": "HD-1693982397", "date_created": "2023-09-23T11:17:18Z", "return_url": "http://www.google.com/", "product_id": "1", "payment_links": { "iframe": "http://localhost:8080/merchant/ipay/ordeh_674a508675bf4cc184747387df7c0236", "web": "http://localhost:8080/merchant/pay/ordeh_674a508675bf4cc184747387df7c0236", "mobile": "http://localhost:8080/merchant/pay/ordeh_674a508675bf4cc184747387df7c0236?mobile=true" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "refunded": false, "amount_refunded": 0, "effective_amount": 1000, "txn_list": [ { "txn_id": "azharamin-HD-1693982397-75-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2029", "card_reference": "", "saved_to_locker": false, "expiry_month": "02", "name_on_card": "Test", "card_issuer": "HDFC BANK", "last_four_digits": "6576", "using_saved_card": false, "card_fingerprint": "", "card_isin": "552260", "card_type": "CREDIT", "card_brand": "MASTERCARD", "using_token": false, "tokens": [], "card_issuer_country": "INDIA", "juspay_bank_code": "", "extended_card_type": "CREDIT", "payment_account_reference": "" }, "payment_method": "MASTERCARD", "refunded": false, "amount_refunded": 0, "effective_amount": 822, "refunds": [ { "id": null, "amount": 822, "unique_request_id": "URI_1682603668", "ref": null, "created": "2023-10-03T20:24:47Z", "status": "PENDING", "error_message": "", "sent_to_gateway": false, "initiated_by": "API", "refund_source": "PAYU", "refund_type": "STANDARD", "error_code": null } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozsthBbu3c4uvbYJsZ", "txn_detail": { "txn_id": "azharamin-HD-1693982397-75-1", "order_id": "HD-1693982397", "status": "CHARGED", "error_code": null, "net_amount": 1000, "surcharge_amount": null, "tax_amount": null, "txn_amount": 822, "offer_deduction_amount": null, "gateway_id": 12, "currency": "INR", "express_checkout": false, "redirect": true, "txn_uuid": "mozsthBbu3c4uvbYJsZ", "gateway": "PAYU", "error_message": "", "created": "2023-09-23T11:17:18Z", "txn_flow_type": "CARD_TRANSACTION" }, "payment_gateway_response": { "resp_code": "success", "rrn": "80d2479c-9d2e-4315-8473-c31e678a951a", "created": "2023-09-23T11:18:18Z", "epg_txn_id": "403993715528813375", "resp_message": "Transaction Completed Successfully", "auth_id_code": "NA", "txn_id": "azharamin-HD-1693982397-75-1", "gateway_response": { "PG_TYPE": "CASH-PG", "Settled_At": "0000-00-00 00:00:00", "addedon": "2023-09-23T11:17:18Z", "additional_charges": "0.00", "amt": "822.00", "bank_ref_num": "80d2479c-9d2e-4315-8473-c31e678a951a", "bankcode": "CASH", "card_no": "", "disc": "0.00", "error_Message": "NO ERROR", "error_code": "E000", "field9": "Transaction Completed Successfully", "firstname": "Mohan", "mihpayid": "403993715528813375", "mode": "CASH", "net_amount_debit": "822", "payment_source": "payu", "productinfo": "NA", "request_id": "", "status": "success", "transaction_amount": "822.00", "txnid": "azharamin-HD-1693982397-75-1", "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "unmappedstatus": "captured" }, "discount_amount": 0 }, "gateway_id": 12, "gateway_reference_id": "payu-prod", "offers": [], "status": "CHARGED" }, { "txn_id": "azharamin-HD-1693982397-75-2", "payment_method_type": "REWARD", "auth_type": "", "payment_method": "TWID", "refunded": false, "amount_refunded": 0, "effective_amount": 178, "refunds": [ { "id": null, "amount": 78.65, "unique_request_id": "URI_1682603668-1", "ref": null, "created": "2023-10-03T20:24:47Z", "status": "PENDING", "error_message": "", "sent_to_gateway": false, "initiated_by": "API", "refund_source": "TWID_V2", "refund_type": "STANDARD", "error_code": null } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozv9grDPNrNFG4iqPo", "txn_detail": { "txn_id": "azharamin-HD-1693982397-75-2", "order_id": "HD-1693982397", "status": "CHARGED", "error_code": null, "net_amount": 1000, "surcharge_amount": null, "tax_amount": null, "txn_amount": 178, "offer_deduction_amount": null, "gateway_id": 92, "currency": "INR", "express_checkout": false, "redirect": false, "txn_uuid": "mozv9grDPNrNFG4iqPo", "gateway": "TWID_V2", "error_message": "", "created": "2023-09-23T11:17:11Z", "txn_flow_type": "DIRECT_DEBIT" }, "payment_gateway_response": { "resp_code": "True", "rrn": null, "created": "2023-09-23T11:17:18Z", "epg_txn_id": null, "resp_message": "success", "auth_id_code": null, "txn_id": "azharamin-HD-1693982397-75-2", "gateway_response": { "data": { "twid_transaction_id": 77737, "bill_amount": 1000, "bill_amount_remaining": 822, "cashback_voucher_earned": null, "reward_points_earned": 0, "reward_amount_redeemed": 178, "transaction_date": null, "redeemed_points": "178", "merchant_transaction_id": "azharamin-HD-1693982397-75-2", "voucher_amount_redeemed": null, "total_amount_redeemed": null }, "error_code": null, "message": "success", "status": true } }, "gateway_id": 92, "gateway_reference_id": "twid-test", "offers": [], "status": "CHARGED" } ] } ``` ### Transaction Sync **Sample Request** #### Shell Code Snippet: ```shell curl --location --request GET 'https://sandbox.juspay.in/ecr/syncGatewayStatus?id=403460861331193856' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic MkNFQkU4QjYyQkQ0**********GQUNBRDRGNjA1Og==' \ ``` **Sample Response** #### Shell Code Snippet: ```shell { "txnId": "403460861331193856'" } ``` ### **Refund (Transaction Based)** **Sample Request** #### Shell Code Snippet: ```shell curl --location 'https://api.juspay.in/orders/txns//refunds' \ --header 'Accept: application/json' \ --header 'version: 2022-03-16' \ --header 'x-merchantid:' \ --header 'Authorization: Basic Auth' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'unique_request_id=req-1695671557' \ --data-urlencode 'amount=998' ``` **Sample Response** #### Shell Code Snippet: ```shell { "order_id": "HD-1695671905", "udf3": "", "status": "CHARGED", "amount": 1, "auth_type": null, "refunded": true, "udf8": "", "udf5": "", "payment_method": "TWID", "gateway_id": 92, "refunds": [ { "status": "SUCCESS", "amount": 1, "sent_to_gateway": true, "unique_request_id": "req-1695672056", "error_code": "SUCCESS", "created": "2023-09-25T20:00:56Z", "pg_processed_at": "2023-09-25T20:00:58Z", "initiated_by": "API", "refund_source": "TWID_V2", "error_message": "SUCCESS", "expected_refund_credit_time": "2023-10-06T21:00:00Z", "id": "req-1695672056", "refund_type": "STANDARD", "ref": "rfnd_Mgh0hfnQ0wXUq9" } ], "udf2": "", "payment_method_type": "REWARD", "txn_uuid": "mozgWyfcrtp51rTvymk", "udf4": "", "customer_id": "cth_7CphvPFq1Rn61Ep7", "udf10": "", "bank_pg": null, "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page" }, "effective_amount": 2.02, "udf1": "", "payment_gateway_response": { "debit_amount": "2.02", "auth_id_code": "130203", "created": "2023-09-25T19:59:05Z", "rrn": "130203", "epg_txn_id": "pay_MggyRECLynoUet", "txn_id": "azhar_test-HD-1695671905-2", "resp_message": "SUCCESS", "resp_code": "SUCCESS" }, "product_id": "1", "txn_detail": { "order_id": "HD-1695671905", "status": "CHARGED", "net_amount": 1, "error_code": "", "gateway_id": 23, "surcharge_amount": 1.02, "txn_uuid": "mozgWyfcrtp51rTvymk", "gateway": "TWID_V2", "created": "2023-09-25T19:58:42Z", "tax_amount": 0, "txn_amount": 2.02, "error_message": "", "currency": "INR", "redirect": false, "express_checkout": false, "txn_id": "azhar_test-HD-1695671905-2", "txn_flow_type": "DIRECT_DEBIT" }, "amount_refunded": 1, "customer_email": "krishna.gprasad@juspay.in", "currency": "INR", "customer_phone": "7093125824", "metadata": { "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_aed3f84d9cb448248afc01505f940db9/payment-page" }, "payment_page_client_id": "change", "TWID_V2:gateway_reference_id": "twid_test" }, "bank_error_message": "", "id": "ordeh_aed3f84d9cb448248afc01505f940db9", "txn_id": "azhar_test-HD-1695671905-2", "merchant_id": "azhar_test", "maximum_eligible_refund_amount": 0, "udf7": "", "date_created": "2023-09-25T19:58:25Z", "bank_error_code": "", "offers": [], "udf9": "", "gateway_reference_id": "twid_test", "return_url": "https://sandbox.juspay.in/r/dXNj1v", "status_id": 21, "rewards_breakup": null, "udf6": "" } ``` ### Refund (Order Based) **Sample Request:** #### Shell Code Snippet: ```shell curl --location 'https://sandbox.juspay.in/orders/{order_id}/refunds' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic ***' \ --data-urlencode 'unique_request_id=URI_1696429607' \ --data-urlencode 'amount=950' \ --data-urlencode 'direct_refund_response=true' ``` **Sample Response:** #### Shell Code Snippet: ```shell { "order_id": "HD-1682603668", "status": "SUCCESS", "amount": 950, "sent_to_gateway": false, "unique_request_id": "URI_1696428914", "gateway": "PAYU", "created": "2023-10-04T14:15:15Z", "initiated_by": "API", "split_refund_details": [ { "status": "SUCCESS", "amount": 750, "sent_to_gateway": false, "unique_request_id": "URI_1696428914", "gateway": "PAYU", "refund_source": "PAYU", "txn_id": "azharamin-HD-1682603668-1-1", "refund_type": "STANDARD", "epg_txn_id": null, "refund_arn": null, "authorization_id": null, "reference_id": null }, { "status": "SUCCESS", "amount": 200, "sent_to_gateway": false, "unique_request_id": "URI_1696428914-1", "gateway": "TWID_V2", "refund_source": "TWID_V2", "txn_id": "azharamin-HD-1682603668-1-2", "refund_type": "STANDARD", "epg_txn_id": null, "refund_arn": null, "authorization_id": null, "reference_id": null } ], "refund_source": "PAYU", "refund_arn": null, "error_message": null, "epg_txn_id": null, "txn_id": "azharamin-HD-1682603668-1-1", "authorization_id": null, "reference_id": null, "response_code": null, "refund_type": "STANDARD" } ``` **Note:** Current documentation illustrates transaction Id based refunds for split payments (both full and partial refunds). Order based refunds feature is upcoming. ## **5. FAQs** ### 1. How can payment page merchants avail new TWID flow ? Update to package version 3.21_<>_RC3 or above. ### 2. How do merchants transition smoothly from TWID redirection flow _(referred as V1)_ to the S2S flow _(referred as V2)_ ? | Frontend Version (New = Package 3.21_<>_RC3 and above) | TWID Gateway creds enabled | Eligibility Resp from Juspay Backend | User Experience | |---|---|---|---| | Old | V1 | V1 | Redirected to TWID page for payment | | Old | V2 | No Response | TWID will not be shown | | Old | V1 & V2 | V1 | Redirected to TWID page for payment | | New | V1 | V1 | Redirected to TWID page for payment | | New | V2 | V2 | User will do split transaction | | New | V1 & V2 | V2 | User will do split transaction | ##