Pay-V3 Integration
Checkout using Javascript Integration
Javascript based integration helps merchants overcome the PCI compliance overheads while it gives them the ultimate flexibility to define the checkout experience for the customer.
In this mode of integration, Juspay provides a card form that merchants can embed in their page. Doing so ensures that the card details are effectively collected on Juspay's page.
As per PCI DSS guidelines, non compliant merchants cannot store users' card number on their server. The Pay-V3.js implementation on web platform is alternative provided by Juspay through which your website is completely shielded away from getting any sensitive card information.
Create Order
Order creation must be done with Juspay via a backend server to server call. For the API reference, please refer here
.
Pay-V3.js
pay-v3.js is the recommended mode of checkout. This latest version uses iFrame elements to take the card input from the user, and a hidden iFrame to send the card information to Juspay servers. This offers better security and reduces the compliance overheads for you.
Implementing Checkout Payment Form
Before we get to the details, let's take a quick look at a typical payment form. This is the part you can build with your web framework, or in HTML - whichever way you are used to building forms on web platform.
For New Cards
In the above form, you need to write the <div> elements for card_number, card_exp_month, card_exp_year, security_code and name_on_card (optional) fields. You need to assign a unique class name for each div as given in above example.
The key tokenize should be passed only when tokenization consent screen is hosted by merchant. The value should be passed as true, only if customer has given consent for tokenization.
The key offers should be passed only when juspay offers are being used. The value for this key can set as the offerID which is received from List Offers
The key payment_channel is an optional field. The values for the same can be - MWEB, WEB, ANDROID or IOS.
For using card mandate via Payv3.js, merchants can add the below line along with the other input details, the value can be true or false based on the consent provided by the customer
<input type="hidden" class="should_create_mandate" value="true" />
Pay-V3.js listens to the form submit event and transports the card information securely to process it for payment. It also supports card tokenization which will tokenize the card information and provide a short-lived token. This token can then be used to initiate the transaction. This is accomplished by the following snippet.
Async Form Submission
There are cases where you might want to delay a transaction from happening when the user clicks on the “Make Payment” button. One use case for this would be if order ID needs to be generated only when the user clicks on the “Make Payment ” and not for every single page load.
Step 1: Ensure the submit button’s type attribute is changed to “button” instead of “submit”.
Step 2: Perform async tasks
Making the button type to button will ensure PayV3 won’t be handling the submit functionality anymore. You now need to add a custom onClick event handler for the above button. Any async actions that need to be performed can be done in this event handler.
If orderID was generated at this point, then the hidden input’s value attribute can be updated at this point.
Step 3: Once async tasks are performed, you can ask PayV3 to perform submit action like:
For Saved Cards
In the above case, all the forms will have the same class name for common styling and different ids for identification. In the above form, you need to write the <div> element for security_code fields. All the saved card forms should have the same class name for security_code divs.
The parameter "name_on_card" is mandatory for calling tokenize function. If not passed, you might encounter CORS issue.
There is no need to write input elements here, since Juspay will be inserting their iframe elements inside the div, which will have the input element.
Card Form Validation
Juspay JS will validate the card elements. Merchants are only expected to handle the validation events.
|
Event
|
Possible Values
|
Description
|
|---|---|---|
event.target_element
| card_number/ name_on_card/ card_exp_month/ card_exp_year/ security_code
| Name of the field which generated this event
|
event.type
| focus/ blur/ keyup/ change
| This field explains the event type which triggered the event callback
|
event.valid
| true/ false
| This field explains whether the value inside the input field of target_element is valid or not
|
event.empty
| true/ false
| This field explains whether the input field of target_element is empty or not
|
event.card_isin
| Card bin value of the card number (Available only when target_element is card_number)
|
|
event.card_brand
| MASTERCARD/ VISA/ MAESTRO/ AMEX/ DINERS/ DISCOVER/ JCB/ RUPAY
| Card brand value of the card number (Available only when target_element is card_number)
|
event.card_type
| DEBIT/ CREDIT
| Card type identifier of the card number (Available only when target_element is card_number)
|
event.card_sub_type
| (Only available for >= 9 digit card bin requests)
|
|
event.partially_valid
| This field explains whether the user is typing the card number correctly (Available only when target_element is card_number)
|
|
event.expiry_valid
| This field explains whether the combination of month or year is valid or not. There may be a case when the input year is the current year and the input month is any month before the current month, then you will get valid=true for both month and year separately, but together they are not valid. To keep such cases in mind, you need to validate whether expiry_valid is true or not. (Available only when target_element is either card_exp_month or card_exp_year)
|
|
event.mandate_support
| true/ false
| This field explains whether the card number entered is eligible for the mandate transaction
|
event.bank
| (Only available for >= 9 digit card bin requests)
|
|
event.tokenize_support
| true/ false
| This field provides tokenize support response for a particular card bin
|
Encoding the Card Details
The card_encoding_key can be found on Juspay's dashboard under Settings--> Security tab.
And the card_encoding_version is 2017-04-26.
For Netbanking, Wallets and UPI
Input type - Offers and Payment_Channel are optional fields. Will be required if you use Juspay Offers Module. Learn more about here
Besides the usual fields, there are some Juspay specific fields which will enable us to process the payment when the form is submitted.
order_id field represents the order_id of the order object that you have just created.
merchant_id field represents the merchant_id of your account. This will be provided by the Juspay team.
payment_method_type field identifies the category of the payment instrument being used. It can be one of CARD, NB, WALLET, etc.
payment_method field identifies the actual payment instrument being used. (Sample list of payment methods for NetBanking is shown in the form above)
juspay_locker_save field indicates to Juspay whether we need to store this card after the payment is successful.
If redirect is true, then we will choose the redirection flow for authentication. Otherwise, a popup window will be used for authentication. By default, popup window will be chosen for authentication.
Using EMI
To support EMI the pay-v3.js has been enhanced to take additional parameters:
is_emi: Indicates if EMI is applicable for this transaction. Valid values are true and false.
emi_bank: Issuing bank of the card
emi_tenure: Tenure of EMI in months
emi_type: Type of EMI ie STANDARD_EMI or NO_COST_EMI
It is an error to pass is_emi and not pass emi_bank and emi_tenure.
Sample form with EMI support: