This tutorial will guide you through invoking a transaction, when the consumer presses the payment-button on your web page. Then we will guide you on how to handle the response from the web SDK.
The transaction type to use can be a Payment or a Preauth, as the implementation for these, are very similar.
As a prerequisite, you should have completed the Creating A Payment Session tutorial, which took you through the steps to create a payment session by calling our Transaction API payment session endpoint, and storing the reference value returned in your backend server.
You will now need the stored payment session reference when calling the Web SDK functions. Please note, this tutorial is for your client-side. You will now need the payment session reference from where it is stored in your backend server. You will need to provide this value when calling the Web SDK functions from your client side, which will be covered in this tutorial.
You should have also completed the tutorial on adding the payment iFrame to your web page. As part of this, you would have imported and then created an instance of the Web SDK library, which you will use in this tutorial to call Web SDK functions.
In a script tag or javascript file, define a function called, for example, ‘handle payment button click’. Then inside the function, define your configuration object. This includes information needed for the transaction such as your judo ID, amount, currency and information you may have about the consumer, for example billing address and mobile number.
For more information on the fields in the configuration object, please see our Web SDK documentation.
Here, there is an example object, along with a table describing all fields that make up the configuration object. Ensure you include all the fields that are required. The same configuration object can be used for Payments and Preauths. Ensure the details used for the configuration object matches the information used to create the payment session for this transaction in your backend server.
If there is a mismatch between values, the transaction will fail.
Please see Creating A Payment Session tutorial for more information on this.
In the function where you have defined the configuration object, call the invoke payment function on the instance of the Judopay Web SDK library previously defined. Add the payment session reference as the first parameter. This is the value that was returned when making the server-side call to the payment session endpoint. Then, add the configuration object that we have just defined as the second parameter.
The invoke payment function returns a promise, therefore handle this accordingly.
For now, if the promise is resolved, we will just print the result. If the promise is rejected, we will print the error.
For a Preauth, simply change the function name to invoke Preauth.
On the payment button element that was previously defined, add a click event handler. This calls the function we have just defined.
When the payment button is clicked, the transaction will be triggered.
To test this, input the test card details, and press the payment button, to which we have added a loading animation. You should see a 3D Secure 2 transaction take place. Once complete, the result of the transaction should be printed in the console.
To get the test card details, see ‘Testing Your Integration’ in our developer documentation. There is a section detailing the test cards that can be used in the sandbox environment, which will trigger different transaction results, such as success or declined. There is also a specific section for 3D Secure 2 transactions. You will need to use the cardholder names listed to trigger the various 3D Secure 2 flows.
For example, for a challenge flow use the cardholder name: Challenge Required.
If your transaction is not going through, and you see an error printed in the console, here are some common mistakes to help you troubleshoot.
When the promise returned from the invoke payment or preAuth call is resolved, a Judopay receipt object is returned. Even if the request has a status response of 200, it does not necessarily mean that the result of the transaction was successful. You will need to look at the receipt object's result field to see the transaction result.
This example shows a Frictionless Issuer Reject scenario, which is one of the negative scenarios where 3D Secure 2 authorisation is rejected. Alternatively, when the promise is rejected, an error object is returned. This means the transaction did not go through successfully.
The Testing Your Integration documentation also contains examples of the response object returned, when the transaction request is successful and the promise is fulfilled.
The response object contains information around the transaction, and importantly the result of the transaction, which can be, for example, success, error or declined.
You should handle the transaction result using the information in this object, and also display back to the consumer the result of the transaction.
Typically you may want to redirect to an outcome screen, where the result of the transaction is displayed to the consumer, along with information such as the amount and receipt ID.
Here, we are de-structuring the response object, to extract the properties that we recommend you present to the consumer. Depending on the result of the transaction, we redirect to the relevant result page.
In this example, we pass the properties as URL parameters, so they can be rendered on the result page. However, you may handle the response object in any way you wish.
As this is a client-side operation, it is highly recommended you also use server-to-server calls, in order to validate the success or failure of the transaction. For example, you can share the receipt ID received on your client-side with your server-side. Your server-side can then call the Judopay Transaction API endpoint, using the receipt ID. The Judopay Transaction API will return the Judopay receipt object of the transaction related to this receipt ID. You can then compare this object with the one received on your client-side, to validate the transaction.
For more information on the calls you can make to Judopay's Transaction API, see our API reference documentation.
When the promise is rejected, the error response object returned from the transaction function can come in 2 different forms.
There are the error responses, passed on from our Transaction API, and there are errors thrown by the Web SDK code. You will want to ensure you handle both types of errors.
Here are some examples of the error objects thrown by the Web SDK code.
They can be caused by providing incorrect values, the consumer cancelling a transaction, and time-outs.
Here are some examples of the errors that originate from our Transaction API.
The Web SDK re-formats the error and passes it back to you.
These errors are caused by the transaction itself. For example, incorrect payment credentials, or failure of 3D Secure 2.
For more information on the error responses returned, see the Web SDK Error Responses section in the developer documentation.
Here, it describes the 2 error types that are returned from Web SDK functions, along with a more detailed description of the format of the API errors.
For card transactions, the Web SDK also has functionality for check card and token payments. These can be useful if you have a stored card-wallet for existing consumers.
The implementation required to use these is very similar to what you have implemented so far for payments. Instead, call their specific Web SDK method, rather than invoke payment and supply their specific configuration object. Handle the response from the Web SDK, as described in this tutorial.
For more information on how to implement these, see the relevant sections in the Web SDK documentation.
Here there is information on their implementation, such as the fields that make up their configuration object.
Following completion of this tutorial, you should have the correct behaviour implemented, so that when the consumer presses the payment button, a card transaction is invoked using the payment session reference created.
You should also be able to handle the response object, or error, that is returned.
.png)
