--- title: Web SDK slug: web-sdk docTags: createdAt: 2024-05-23T08:39:41.979Z --- Judopay's Web SDK is a JavaScript library which includes a fully customisable hosted iframe solution enabling you to collect sensitive card information. You will not take on additional PCI scope, as sensitive card information such as: - card number (PAN) - expiry date - card security code will be submitted by your customers into fields hosted by Judopay. *** ### Web SDK Video Tutorials :::CtaButton{label=">>> Click to learn the basics of accepting payments with our Web SDK Video Tutorials >>>" docId="TEY_GEQbut9bneZO5mWgu" docAnchorId="#Nrq-M" openInNewTab="true"} ::: *** ### Payment Flow ![3ds2 payment flow](https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/AqtoABBBeoDZ6goooiP1o-20260511-113405.png) *** # Creating a 3D Secure 2 Payment with the Web SDK :::hint{type="info"} When authorising `/payments` or `/preauths` it is recommended to use **paymentSession**. ::: Web SDK Version **0.0.29** (and higher) fully supports 3D Secure 2 flows. No additional support is required, the SDK does the rest. :::hint{type="warning"} Make sure your account has **3D Secure 2 API credentials **enabled. Contact ​Customer Support​​ to set this up. ::: *** The following steps are **prerequisites for all the **[payment methods](docId:40dWE6LBub7vdKza1QYDC) available for integration using Judopay's Web SDK. ## Step One: Create a paymentSession :::hint{type="warning"} Make sure you are using Judopay's API version **6.0.0.0** or higher. ::: ### Important to Consider - The paymentSession can be used for up to **three transaction attempts** for the same transaction. - If the **block duplicate transactions** permission has been applied on your API tokens, the paymentSession can only be used for **one **transaction attempt. - If you want to have this permission removed, contact Customer Support. - A payment session can be used again to re-submit a failed transaction attempt. - Once a transaction attempt is successful, the paymentSession can **no longer be used** even if there are any remaining attempts available. - The paymentSession will expire in **30 minutes**, unless an **ExpiryDate **is set in the `/paymentsession` request body. - The expiry date must be within one year: `"ExpiryDate": "2028-10-06T17:43:21+01:00"` :::hint{type="info"} As soon as the payment session is used for the initial transaction attempt, this will initiate the **30 minute expiry time**. ::: *** To create a paymentSession: - Make a HTTP **POST **Request: `/paymentsession` :::hint{type="warning"} Merchants operating in specific money movement and financial services categories, as defined by the card schemes **must include** additional data in the [payment session](docId\:ylKW5coh5NQnfQ3j_Wjk2). For more information, see [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg). ::: :::CodeblockTabs Payment Session Request Example ```json { "judoId": "100100100", "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 10.99, "expiryDate": "2028-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes } ``` Response Reference Example ```json //Store the reference returned in your backend server: { "postUrl": "https://pay-sandbox.judopay.com/v2", "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj_XDg" } ``` ::: *For the full schema details and descriptions, see Transaction API: *[/paymentsession](docId\:bcXNM5keOk-nlNrZTafUT) :::hint{type="info"} Your backend server should store the **paymentSession response reference **returned by Judopay's API. Use this reference from the response to populate paymentSession when calling `/payments` and `/preauths` from your front-end client. See [Making a Transaction](docId:4DZoQ07rT7fyOlM0jUiBj). ::: The following parameters need to remain consistent between the `/paymentsession` requests and the `/payments` and `/preauths` requests, otherwise the transaction will fail: - YourPaymentReference - YourConsumerReference - JudoID - Currency - Amount This is used to cross reference the validity of the transaction. *** ## Step Two: Add the Payment Form to your Website ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/dtlO96hwckHIfb-LD0mdz_docs-quick-start-hres.png" size="32" width="500" height="277" position="flex-start" alt="example payment form" darkWidth="500" darkHeight="277" showCaption="false"} ### Create and customise the Judopay Web SDK iFrame ::::WorkflowBlock :::WorkflowBlockItem Add the code snippet in your web page \: `scriptsrc="https://web.judopay.com/js/0.1.0/judopay.min.js">` ** *This example will use jQuery for a promise, so include the following in your web page *\: `` ::: :::WorkflowBlockItem In your \ add a \
tag where you want the iframe to appear: `
` ** *This example uses the **id: payment-frame**. You can use whatever id you wish.* ::: :::WorkflowBlockItem In your \ add a \
tag where you want the errors in form entry to appear. *For the purpose of this exercise, the class is named** judopay-errors**, and sets a style to be **red**.* ** You can add any custom style you wish in your .CSS file: `
Error Location
` For more information on all errors that can be returned, see [Payment Form Error Messages](docId\:qfxaWPAQl_-2EVfP8y94d). ::: :::WorkflowBlockItem In your \ add a button call: **submit-payment-button** for the iframe submission to Judopay. Make sure you have set: `id="submit-payment-button"` This is required to perform form validation where the **Pay **button will be greyed out until all the information has been entered. `
``` ::: *** ## Handle the Response All the Judopay Web SDK transaction methods return a promise. Once the authorisation is complete, the promise will be either fulfilled or rejected. **Fulfilled** - You will receive a JSON object response (a Judopay receipt object). - For more information and schema on the JSON object, see [API Transaction Response](docId\:bcXNM5keOk-nlNrZTafUT). - Depending on the result the consumer should be redirected to the appropriate outcome page. - For example, if the result = SUCCESS redirect the consumer to the Success Page. - This page should display the necessary transaction information (found in the Judopay receipt object). **Rejected** - You will receive an error object - For more information on error responses returned, see [Web SDK Error Responses](docId\:qfxaWPAQl_-2EVfP8y94d). - The consumer should be redirected to an Error Page. :::CodeblockTabs Response Example ```json const onFulfillment = (receiptObject) => { const { result } = receiptObject //redirect to appropriate page depending on the result (success/failure/declined page) } const onRejection = (error) => { //redirect to error page and handle error } ``` ::: For more information on the response codes, see [Codes](docId:_zrsihomUEW-XnRQ4PBtJ). *** ## Voiding an Incremental Authorisation Transaction Each incremental authorisation generates its own `receiptId`. If an authorisation has been incremented, any subsequent void request **must **reference the `receiptId` of the **original pre-authorisation** transaction. :::hint{type="warning"} Using the `receiptId` returned following an incremental authorisation will result in an **error**. ::: The void amount **must **be the sum of the original authorisation amount and all successful increments. Any attempt to process a **partial void**, the sum of any but **not all authorisations** and increments, will result in an **error**. For example: - Initial preAuth: £100 - `incrementalAuth` request amount: £20 - `incrementalAuth` request amount: £30 - Total authorised amount after increments: £150 To void this transaction: 1. Use the `receiptId` of the Initial preAuth. 2. Submit a void request for **£150**. *** # Customisation and Displaying Payment Form Error Messages For more information on: - Customising your Web SDK integration, see [Customisation](docId\:FVh6jG8c0jC7Q7OC9uoac) - Displaying payment form error messages, see [Payment Form Error Messages](docId\:qfxaWPAQl_-2EVfP8y94d) *** # Testing your Integration Follow our [Testing your Web SDK Integration](docId:5TAFISDJ44kGcCiGW2z-w) test scenarios, to test your integration and generate: - Successful payments - Declined payments - Unexpected errors