JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Twid_V2 Onboarding (EC Merchants)

1. Pre-requisites

Configuring a new gateway account for Twid_v2 on the Juspay Dashboard

Step 1: Dashboard

Sandbox Dashboard Url - https://sandbox.portal.juspay.in

Production Dashboard Url - 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

2. Front-End Design Guidelines

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
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
Front End UI can be rendered basis the eligibility API response from Juspay

3. Eligibility and Authentication (Linking) APIs

3.1. Payment Methods API

3.2. Eligibility API - Process SDK Call for Rendering TWID Rewards

For an user, the list of rewards would be returned in “payment_methods_eligibility” block in Juspay’s Eligibility API response.

The best rewards are showcased under “reward_details” (“best_reward_type“ along with “sub_title“)
These rewards are segregated into “redeemable_info” (issuers are of 2 types - bank and brand) and “voucher_info”(coupons).
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
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
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)
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
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.

3.3. Wallet APIs

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

Authenticate API - for triggering OTP

Link API - for validating and submitting OTP
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.
Once customer is linked on the merchant application, there will not be a de-link option available

4. Order & Transaction APIs

4.1. Order API

Create Customer - Reference specs: https://docs.juspay.in/ec-api/docs/base-integration/creating-a-customer

4.2. Transaction API

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.

“split_amount” is reward amount + voucher amount
reward chosen by the user should be passed in “reward_id“ (mandatory)
EARN or BURN would be sent in “reward_mode“ (mandatory)
voucher_id to be sent - mandatory key in case the user selects a voucher

4.3. Order Status and Webhooks

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)

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)

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.