Twid_V2 (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

→ Production Dashboard Url - https://portal.juspay.in/

• Select TWID_V2 Gateway

• Enter Gateway Credentials

Step 2

Payment Method Configuration

Select Twid Rewards from payment Method Configurations

Step 3

Advanced Features

 In Advanced Features, enable Power Wallet

Step 4

Updating existing gateway account to add Twid_v2 from the Juspay Dashboard

The gateway can be modified for all fields except for Secret Key, which is non-editable.

Step 5

Enabling 'Rewards' as a Payment Method Type in Studio

Merchant has to enable Rewards as a Payment Method Type if not already done. Not required for merchants using TWID currently

2. End-to-end User flow

Authentication Flow

This is a one-time step for each user for the very first time they try to link their Twid account by logging in to their Twid Account from a merchant’s platform.

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

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.

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.

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. Handling Eligibility Failure Cases

Ineligible Case

Unable to find Rewards for you

It looks like you cannot use Rewards at this time, please try again later

Authentication Failed

Incorrect OTP

Entered OTP is incorrect, please retry.

Authentication Attempts Exhausted

Retry OTP attempts exhausted

OTP retry attempts are exhausted. Please try again after 30 minutes.

4. Sample Requests and Responses

With the existing implementation on Juspay , the transaction level details are available in the root structure of the orderStatus JSON block.

With Integration TWID_v2 and being a split transactions , you would get txn_list as an array block in which the 2 transactions (UPI + TWID). You need to make sure to consume the params from inside the txn_list array block.

Also, There will be a new status called as AUTO_REFUNDED case, in which your primary transaction fails, Juspay will auto-refund the TWID_v2 reward balance.

Order Status

Request

Order status request

Response

Order status response

Sample Webhook Response

Please find the sample webhook response.

Refund Calls

1. Refund requests (full/partial) can be initiated by a Juspay’s merchant at Transaction level or at Order level.

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

3. For Order based refunds, 

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

4. For Transaction based refunds

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

Request

Transaction based refund request

Response

Transaction based refund response

Request

Order based refund request

Response

Order based refund response

5. FAQs

1. How can payment page merchants avail new TWID flow ?

Update to package version 2.89 or above.

2. How do merchants transition smoothly from TWID redirection flow (referred as V1) to the S2S flow (referred as V1) ?

6. Testing Scenarios

For the final step towards completing your TWID Integration, Kindly perform the below mentioned test cases