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

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

• Select TWID_V2 Gateway

• Enter Gateway Credentials

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

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. Sample Requests and Responses

getPaymentMethods for Twid:

Request:

Response:

Process SDK Call for Rendering TWID Rewards

Eligibility Request

Eligibility Response

Note:

Twid Reward consent & linking (Only for Linking Flow**)

Authenticate (Create Wallet) Request: (Only for Linking Flow**)

Sample Response: (Only for Linking Flow**)

Link Wallet Request: (Only for Linking Flow**)

Sample Response: (Only for Linking Flow**)

Order Create

Sample Request

Sample Response

Transaction Create

Sample Txns Process Payload

Sample Txns Process Response

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

Sample Txns Response

Order Status

Sample Request

Sample Response

Transaction Sync

Sample Request

Sample Response

Refund (Transaction Based)

Sample Request

Sample Response

Refund (Order Based)

Sample Request:

Sample Response:

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