--- page_source: https://juspay.io/in/docs/payment-method-integrations/express-checkout-api/twidv2-onboarding-and-api-specification-ec/twidv2 page_title: Twid_V2 --- # **Twid_V2 Onboarding (EC Merchants)** ## **1. Pre-requisites** ### Step 1.1. Configuring a new gateway account for Twid_v2 on the Juspay Dashboard #### **Step 1: 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 (All Fields are Mandatory except Resend Otp Wait Time (default Resend OTP time is 15s)) #### **Step 2: Payment Method Configuration** Select Twid Rewards from payment Method Configurations #### **Step 3: Advanced Features** In Advanced Features, enable Power Wallet ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Twid_v2-n0g5Z-fgmGv.png) ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Twid_PMC-1mo1o-esyo3.png) ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/payment-method-integrations/Advanced%20Configuration.png) ## **2. Front-End Design Guidelines** ### Step 1.1. Substep 1. OTP Authentication - This is a one-time step for every user (for the first time) to be authenticated through the merchant’s application. This is a one-time activity post which user will not be able to change the phone number 2. Once user selects a reward, Payment locking should be handled. Card rewards would be associated with a card transaction only. Examples - (a)If Axis points are being redeemed, user should be restricted to Axis cards (b) voucher cannot be applied without selecting a Reward (c) Voucher plus reward shouldn’t be greater than order amount etc 3. Front End UI can be rendered basis the eligibility API response from Juspay ## 3. Eligibility and Authentication (Linking) APIs ### 3.1. Payment Methods API Substep API is called to fetch the list of configured merchant payment methods with Juspay. The response would contain a block with Payment Method as TWID and Payment Method Type as REWARD. #### Request Code Snippet: ```request {"success":false,"message":"No Data found for the given path"} ``` #### Response Code Snippet: ```response { "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" } ] } } ``` ### 3.2. Eligibility API - Process SDK Call for Rendering TWID Rewards Substep For an user, the list of rewards would be returned in “payment_methods_eligibility” block in Juspay’s Eligibility API response. 1. The best rewards are showcased under “reward_details” (“best_reward_type“ along with “sub_title“) 2. These rewards are segregated into “redeemable_info” (issuers are of 2 types - bank and brand) and “voucher_info”(coupons). 3. For Rewards, twid supports “BURN“ & “EARN“ methods. BURN operation would consume the rewards while EARN operation would fetch rewards. 1. “reward_type“:”BURN” - would contain the reward “value” that can be redeemed 2. “reward_type“:”EARN” - would contain the “earnable_points” that can be earned 4. For Vouchers, voucher_amount, voucher_id and expiry would be returned in the response. “Terms and conditions” would also be returned, needs to be showcased on the UI 5. For a first time user who wasn’t authenticated yet, “reward_details“ would contain “otp_verification_required“:true and would go through user linking flow (showcased in next section) 6. Post successful linking, eligibility call would then return user’s rewards. If the user has already exhausted all rewards, the response would be “is_eligible“:false 7. Response would also contain “payment_locking_payload” that talks about payment method coupling required for a given reward type. This can be treated as an input to handle UI rendering for a user accordingly. #### Request Code Snippet: ```request curl --location 'https://api.juspay.in/customers//eligibility' \ --header 'Authorization: ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'version: ' \ --- This is mandatory for Twid v2 (format - YYYY-MM-DD) --data-urlencode 'amount=100' \ --data-urlencode 'gateway_reference_id=refId' \ --data-urlencode 'order_id=orderId' \ --data-urlencode 'mobile_number=mobile_number' ``` #### Response Code Snippet: ```response { "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 } ``` ### 3.3. Wallet APIs Substep These API are used in succession for authenticating the customer for the first time on the application. This API will be needed only when the eligibility response contains “otp_verification_required“ : true and “is_eligible” : true. If merchant onboards users using phone number authentication, Twid_v2 PG will always respond with rewards in order to skip authentication (for all users). Here, merchant can directly render the rewards. Else, below OTP authentication steps will be required 1. Authenticate API - for triggering OTP 2. Link API - for validating and submitting OTP 3. Resend API - for triggering OTP again. Resend can be sent only after every 15 sec for 5 times in a span of 30min. This default setting for re-send wait time of 15sec can be configured on the Merchant dashboard. 4. Once customer is linked on the merchant application, there will not be a de-link option available #### Authenticate Request Code Snippet: ```authenticate request curl --location 'https://sandbox.juspay.in/customers/{customer_id}/wallets' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic OTNBQTlFNzdCM********==' \ --data-urlencode 'gateway=TWID_V2' \ --data-urlencode 'command=authenticate' \ --data-urlencode 'gateway_reference_id=testmode' \ --data-urlencode 'mobile_number=708****413' \ ``` #### Response Code Snippet: ```response { "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 Request Code Snippet: ```link request curl --location 'https://sandbox.juspay.in/wallets/{walletId}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic OTNBQTlFNzdCM*******UVBOEE4NjMwMDcxOg==' \ --data-urlencode 'command=link' \ --data-urlencode 'otp=2748' ``` #### Response Code Snippet: ```response {"success":false,"message":"No Data found for the given path"} ``` #### Curl for Resend Request Code Snippet: ```curl for resend request curl --location 'https://sandbox.juspay.in/wallets/{walletId}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic OTNBQTlFNzdCM*******UVBOEE4NjMwMDcxOg==' \ --data-urlencode 'command=resend' ``` ## 4. Order & Transaction APIs ### 4.1. Order API Substep Order API is called with gateway_reference_id (needed when there are multiple gateways configured on the dashboard). 1. “customer_id” or “customer_mobile” is mandatory to be passed 2. “amount” would be the total order amount * Create Customer - Reference specs: [https://docs.juspay.in/ec-api/docs/base-integration/creating-a-customer](https://docs.juspay.in/ec-api/docs/base-integration/creating-a-customer) #### Order Create Request Code Snippet: ```order create request 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=""' ``` #### Response Code Snippet: ```response { "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" } } ``` ### 4.2. Transaction API Substep Initiate transaction API with “additional_payment_details” that contain the reward/voucher details. A split payment (multiple transactions) is initiated for an order if “additional_payment_details“ is passed to Juspay. If merchant falls into the category, where it’s users do not have OTP authentication at the time of onboarding onto merchant app, then wallet APIs need to be called for OTP authentication (as mentioned in #3.3). In this case, direct wallet token (that merchant receives as a response to list/wallet API) needs to be passed in additional_payment_details, key is “direct_wallet_token”. Also, transaction API needs to be authenticated - passing an API key or Client Auth Token or Signature is mandatory. 1. “split_amount” is reward amount + voucher amount 2. reward chosen by the user should be passed in “reward_id“ (mandatory) 3. EARN or BURN would be sent in “reward_mode“ (mandatory) 4. voucher_id to be sent - mandatory key in case the user selects a voucher #### Request Code Snippet: ```request 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' ``` #### Response Code Snippet: ```response { "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" } ``` ### 4.3. Order Status and Webhooks Substep 1. Order Status Response would contain list of transactions and corresponding details. 2. Order Status Response and webhook response would be the same. 3. Useful links - [Juspay Reference Docs](https://docs.juspay.in/resources/docs/common-resources/transaction-status) #### Request Code Snippet: ```request curl --location 'https://api.juspay.in/ecr/orders/?options.add_full_gateway_response=true' \ --header 'Authorization: Basic Auth' ``` #### Failure Response Code Snippet: ```failure response { "customer_email": "aaa@aa.com", "customer_phone": "7093125824", "customer_id": "cth_8bfsiUVj96tiDzmx", "status_id": 27, "status": "AUTHORIZATION_FAILED", "id": "ordeh_95d6ce56681d44e096738514d75f3c50", "merchant_id": "azhar_test", "amount": 1500, "currency": "INR", "order_id": "twid_1732013163", "date_created": "2024-11-19T10:46:02Z", "last_updated": "2024-11-19T10:46:35Z", "return_url": "https://requestbin.juspay.net", "product_id": "", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "amount_refunded": 0, "effective_amount": 1500, "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:56:02Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page" }, "payment_page_client_id": "change" }, "txn_list": [ { "txn_id": "azhar_test-twid_1732013163-1-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2025", "card_reference": "", "saved_to_locker": false, "expiry_month": "12", "name_on_card": "Test", "card_issuer": "HDFC Bank", "last_four_digits": "1111", "using_saved_card": false, "card_fingerprint": "4t6fpp90t9ghlbvk0b0ahqo2lj", "card_isin": "411111", "card_type": "DEBIT", "card_brand": "VISA", "using_token": false, "tokens": [], "token_type": "CARD", "card_issuer_country": "INDIA", "juspay_bank_code": "JP_HDFC", "extended_card_type": "DEBIT", "payment_account_reference": "" }, "payment_method": "VISA", "refunded": false, "effective_amount": 1500, "resp_code": "BANK_DECLINED", "resp_message": "Transaction failed at issuer Bank's end", "bank_error_code": "227", "bank_error_message": "Your payment has been declined by your bank. Please try again or use a different method to complete the payment.", "txn_uuid": "mozgd8KRjtfVe8hnqVx", "txn_detail": { "txn_id": "azhar_test-twid_1732013163-1-1", "order_id": "twid_1732013163", "status": "AUTHORIZATION_FAILED", "error_code": "227", "net_amount": 1500, "surcharge_amount": null, "tax_amount": null, "txn_amount": 1500, "offer_deduction_amount": null, "gateway_id": 19, "currency": "INR", "express_checkout": false, "redirect": true, "txn_uuid": "mozgd8KRjtfVe8hnqVx", "gateway": "PAYTM_V2", "response_code": "BANK_DECLINED", "response_message": "Transaction failed at issuer Bank's end", "error_message": "Your payment has been declined by your bank. Please try again or use a different method to complete the payment.", "created": "2024-11-19T10:46:25Z", "last_updated": "2024-11-19T10:46:35Z", "txn_flow_type": "CARD_TRANSACTION", "is_cvv_less_txn": false, "txn_amount_breakup": [ { "name": "BASE", "amount": 1500, "sno": 1, "method": "ADD" } ] }, "payment_gateway_response": { "resp_code": "227", "rrn": "6877574014556983306097", "created": "2024-11-19T10:46:35Z", "epg_txn_id": "20241119011670000065666057479464334", "resp_message": "Your payment has been declined by your bank. Please try again or use a different method to complete the payment.", "auth_id_code": "", "txn_id": "azhar_test-twid_1732013163-1-1", "gateway_response": { "BANKNAME": "ICICI Bank", "BANKTXNID": "6877574014556983306097", "CHECKSUMHASH": "TfCIRPFe4pDmNzrEn9benriEmpnwlK349GdfdC2bdKD852cmULM7tUOoAyM79mAS8l8yK+dpwFdy1WhaV2uAUQFhjZWB85HLnOobKsQHWAU=", "CURRENCY": "INR", "GATEWAYNAME": "HDFCPAY", "MERC_UNQ_REF": "NA", "MID": "Juspay67815894107156", "ORDERID": "azhar_test-twid_1732013163-1-1", "PAYMENTMODE": "CC", "RESPCODE": "227", "RESPMSG": "Your payment has been declined by your bank. Please try again or use a different method to complete the payment.", "STATUS": "TXN_FAILURE", "TXNAMOUNT": "1500.00", "TXNDATE": "2024-11-19 16:16:27.0", "TXNID": "20241119011670000065666057479464334", "UDF_1": "NA", "UDF_2": "NA", "UDF_3": "NA" }, "network_error_message": null, "network_error_code": null, "arn": "", "gateway_merchant_id": null, "eci": null, "auth_ref_num": null }, "gateway_id": 19, "gateway_reference_id": "paytmv2_testing", "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:56:02Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page" }, "payment_page_client_id": "change" }, "offers": [], "status": "AUTHORIZATION_FAILED", "resp_category": "BUSINESS_ERROR" }, { "txn_id": "azhar_test-twid_1732013163-1-2", "payment_method_type": "REWARD", "auth_type": "", "payment_method": "TWID", "refunded": false, "effective_amount": 0, "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozbf27RTDDaTAnaTWF", "txn_detail": { "txn_id": "azhar_test-twid_1732013163-1-2", "order_id": "twid_1732013163", "status": "STARTED", "error_code": null, "net_amount": 1500, "surcharge_amount": null, "tax_amount": null, "txn_amount": 0, "offer_deduction_amount": null, "gateway_id": 92, "currency": "INR", "express_checkout": false, "redirect": false, "txn_uuid": "mozbf27RTDDaTAnaTWF", "gateway": "TWID_V2", "error_message": "", "created": "2024-11-19T10:46:24Z", "last_updated": "2024-11-19T10:46:24Z", "txn_flow_type": "REDIRECT_DEBIT", "txn_amount_breakup": [ { "name": "BASE", "amount": 0, "sno": 1, "method": "ADD" } ] }, "gateway_id": 92, "gateway_reference_id": "twid-s2s", "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:56:02Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_95d6ce56681d44e096738514d75f3c50/payment-page" }, "payment_page_client_id": "change" }, "offers": [], "status": "STARTED", "resp_category": null } ], "additional_info": {} } ``` #### Success Response Code Snippet: ```success response { "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" } ] } ``` ## 5. Refund APIs Refund requests (full/partial) can be initiated at a Transaction or Order level. Given that Twid V2 transactions are always split between an existing Gateway and Twid rewards, the merchant can choose between one of the two provisions - ### 5.1. Order Based Refunds (using Order_Id) Substep a. Merchant will have to pass order Id & refund amount to Juspay b. Each order would have a minimum of 2 transactions and Juspay internally handles the split refund initiation (full and partial), to both Twid and other configured gateway c. Juspay will ensure checks for eligible refund amount, split calculation etc d. Merchant will receive Juspay’s refund response accordingly (post PG processing) and is expected to handle the same (new key “split_refund_details”) ### 5.2. Transaction Based Refunds (using Txn_Id) Substep a. Merchant would initiate refunds against all transaction Ids, with transaction Id and amount to Juspay b. Mechant will ensure the amount checks and the refund split for both full and partial refunds. This refund split calculation will include an additional API call to Twid. Alternatively, split can also be calculated by first exhausting the gateway amount and then Twid amount (merchant to confirm with Twid). c. Juspay’s refund response will remain the same as what merchants currently see for transaction based refunds. No additional handling required. #### Order Based Refund Request Code Snippet: ```order based refund request 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' ``` #### Response Code Snippet: ```response { "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" } ``` #### Transaction Based Refund Request Code Snippet: ```transaction based refund request 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' ``` #### Failure Response Code Snippet: ```failure response { "customer_email": "aaa@aa.com", "customer_phone": "8892526772", "customer_id": "cth_k2bTwtMZFo1qKjpN", "status_id": 21, "status": "CHARGED", "id": "ordeh_3d316be64e4f4b16a8a47c9523b17d39", "merchant_id": "azhar_test", "amount": 1500, "currency": "INR", "order_id": "twid_1732013031", "date_created": "2024-11-19T10:43:50Z", "return_url": "https://requestbin.juspay.net", "product_id": "", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "refunded": true, "amount_refunded": 1500, "effective_amount": 1500, "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:53:50Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page" }, "payment_page_client_id": "change" }, "txn_list": [ { "txn_id": "azhar_test-twid_1732013031-1-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2025", "card_reference": "", "saved_to_locker": false, "expiry_month": "12", "name_on_card": "Test", "card_issuer": "HDFC Bank", "last_four_digits": "1111", "using_saved_card": false, "card_fingerprint": "4t6fpp90t9ghlbvk0b0ahqo2lj", "card_isin": "411111", "card_type": "DEBIT", "card_brand": "VISA", "using_token": false, "tokens": [], "token_type": "CARD", "card_issuer_country": "INDIA", "juspay_bank_code": "JP_HDFC", "extended_card_type": "DEBIT", "payment_account_reference": "" }, "payment_method": "VISA", "refunded": true, "amount_refunded": 1000, "effective_amount": 1000, "refunds": [ { "id": "refund_split_1732013483", "amount": 1000, "unique_request_id": "refund_split_1732013483", "ref": "20241119021670656684265775554570418", "created": "2024-11-19T10:51:23Z", "last_updated": "2024-11-19T10:55:53Z", "status": "Failure", "error_message": "Refund Failure", "sent_to_gateway": true, "gateway_refund_response": { "refund_break_up_details": [ { "card_scheme": "VISA", "issuing_bank_name": "ICICI Bank", "masked_card_number": "************1111", "pay_method": "CREDIT_CARD", "refund_amount": "1000.00", "refund_type": "TO_SOURCE", "rrn": "6974605507046771805045", "user_credit_expected_date": "2024-11-24 16:25:52.0" } ] }, "arn": "6974605507046771805045", "expected_refund_credit_time": "2024-11-24T17:00:00Z", "initiated_by": "API", "refund_source": "PAYTM_V2", "refund_type": "STANDARD", "pg_processed_at": "2024-11-19T10:55:53Z", "bank_processed_at": "2024-11-19T10:55:53Z", "error_code": "10" } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozr2oTGMt62uin1A7k", "txn_detail": { "txn_id": "azhar_test-twid_1732013031-1-1", "order_id": "twid_1732013031", "status": "CHARGED", "error_code": null, "net_amount": 1500, "surcharge_amount": null, "tax_amount": null, "txn_amount": 1000, "offer_deduction_amount": null, "gateway_id": 19, "currency": "INR", "express_checkout": false, "redirect": true, "txn_uuid": "mozr2oTGMt62uin1A7k", "gateway": "PAYTM_V2", "error_message": "", "created": "2024-11-19T10:44:01Z", "last_updated": "2024-11-19T10:44:09Z", "txn_flow_type": "CARD_TRANSACTION", "is_cvv_less_txn": false, "txn_amount_breakup": [ { "name": "BASE", "amount": 1000, "sno": 1, "method": "ADD" } ] }, "payment_gateway_response": { "resp_code": "01", "rrn": "6877574014556983306097", "created": "2024-11-19T10:44:07Z", "epg_txn_id": "20241119011670000065665453403220418", "resp_message": "Txn Success", "auth_id_code": "621494", "txn_id": "azhar_test-twid_1732013031-1-1", "gateway_response": { "authCode": "621494", "bankName": "ICICI Bank", "bankTxnId": "6877574014556983306097", "cardScheme": "VISA", "gatewayName": "HDFCPAY", "merchantUniqueReference": "NA", "mid": "Juspay67815894107156", "orderId": "azhar_test-twid_1732013031-1-1", "paymentMode": "CC", "refundAmt": "0.0", "resultCode": "01", "resultInfo": { "resultCode": "01", "resultMsg": "Txn Success", "resultStatus": "TXN_SUCCESS" }, "resultMsg": "Txn Success", "resultStatus": "TXN_SUCCESS", "rrnCode": "6877574014556983306097", "txnAmount": "1000.00", "txnDate": "2024-11-19 16:14:03.0", "txnId": "20241119011670000065665453403220418", "txnType": "SALE" }, "network_error_message": null, "network_error_code": null, "arn": "", "gateway_merchant_id": null, "eci": null, "auth_ref_num": null }, "gateway_id": 19, "gateway_reference_id": "paytmv2_testing", "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:53:50Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page" }, "payment_page_client_id": "change" }, "offers": [], "status": "CHARGED", "resp_category": null }, { "txn_id": "azhar_test-twid_1732013031-1-2", "payment_method_type": "REWARD", "auth_type": "", "payment_method": "TWID", "refunded": true, "amount_refunded": 500, "effective_amount": 500, "refunds": [ { "id": null, "amount": 500, "unique_request_id": "refund_split_1732013518", "ref": "RF-4177", "created": "2024-11-19T10:51:57Z", "last_updated": "2024-11-19T10:58:39Z", "status": "FAILURE", "error_message": "Failure", "sent_to_gateway": true, "expected_refund_credit_time": "2024-12-03T11:00:00Z", "initiated_by": "API", "refund_source": "TWID_V2", "refund_type": "STANDARD", "metadata": { "refund_pg_amount": null, "refund_points_amount": null, "refund_total_amount": null }, "pg_processed_at": "2024-11-19T10:58:39Z", "error_code": "Failure" } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "mozgcZT2s9YeF1UEbvX", "txn_detail": { "txn_id": "azhar_test-twid_1732013031-1-2", "order_id": "twid_1732013031", "status": "CHARGED", "error_code": null, "net_amount": 1500, "surcharge_amount": null, "tax_amount": null, "txn_amount": 500, "offer_deduction_amount": null, "gateway_id": 92, "currency": "INR", "express_checkout": false, "redirect": false, "txn_uuid": "mozgcZT2s9YeF1UEbvX", "gateway": "TWID_V2", "error_message": "", "created": "2024-11-19T10:44:00Z", "last_updated": "2024-11-19T10:44:09Z", "txn_flow_type": "DIRECT_DEBIT", "txn_amount_breakup": [ { "name": "BASE", "amount": 500, "sno": 1, "method": "ADD" } ] }, "payment_gateway_response": { "resp_code": "True", "rrn": null, "created": "2024-11-19T10:44:09Z", "epg_txn_id": "83671", "resp_message": "success", "auth_id_code": null, "txn_id": "azhar_test-twid_1732013031-1-2", "gateway_response": { "data": { "bill_amount": 1500, "bill_amount_remaining": 1000, "cashback_voucher_earned": null, "merchant_transaction_id": "azhar_test-twid_1732013031-1-2", "redeemed_points": 2000, "reward_amount_redeemed": 500, "reward_points_earned": 0, "total_amount_redeemed": null, "transaction_date": null, "twid_transaction_id": 83671, "voucher_amount_redeemed": null }, "error_code": null, "message": "success", "status": true }, "network_error_message": null, "network_error_code": null, "arn": null, "gateway_merchant_id": null, "eci": null, "auth_ref_num": null }, "gateway_id": 92, "gateway_reference_id": "twid-s2s", "metadata": { "PAYTM_V2:gateway_reference_id": "paytmv2_testing", "TWID_V2:gateway_reference_id": "twid-s2s", "order_expiry": "2024-11-19T10:53:50Z", "payment_links": { "iframe": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "mobile": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page", "web": "https://sandbox.juspay.in/orders/ordeh_3d316be64e4f4b16a8a47c9523b17d39/payment-page" }, "payment_page_client_id": "change" }, "offers": [], "status": "CHARGED", "resp_category": null } ], "additional_info": {} } ``` #### Success Response Code Snippet: ```success response { "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": "" } ```