--- title: Testing Web SDK - Card Payments slug: testing-web-sdk-card-payments docTags: createdAt: 2024-06-10T13:52:22.352Z --- With Judopay’s Web SDK solution, a minimal integration is all that is required to enable you to: - Take a card payment - Take a card preAuth - Take a card token payment - Take a card token preAuth - Check the validity of a card, using checkCard *** ## Prerequisites Before attempting Web SDK test transactions, ensure the following steps have been implemented: - [Step One: Create a paymentSession](docId:40dWE6LBub7vdKza1QYDC) - [Step Two: Add the Payment Form to your Website](docId:40dWE6LBub7vdKza1QYDC) - Defined the **payment configuration**, **token configuration **and **check card configuration **objects as required. *** ## Card Payment Scenarios (Positive Flow) ### Important to Consider - **yourPaymentReference **is your unique reference for each transaction. - Ensure you generate a unique **yourPaymentReference **and unique **paymentSession **for each transaction. - This will avoid duplicate transactions. - When making token payments, **yourConsumerReference **must match the original reference when the token was initially created. - Ensure the following information in your **configuration object(s)** matches the information in the **paymentSession**: - judoId - currency - amount - yourConsumerReference - yourPaymentReference If this does not match, you will receive an **error**. | **Suggested Test Scenario** | **Expected Outcome** | **Tip** | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Process a successful Web SDK card checkCard request.
This will check the card is valid. | 200
Successful | Ensure you have defined the **check card configuration **object.
The checkCard response provides the:
- cardToken - yourConsumerReference
Ensure you use the correct **cardToken** and **yourConsumerReference** to make future** token payments**, otherwise they will fail. | | Process a successful Web SDK card payment / preAuth request.
| 200
Successful | Ensure you have defined the **payment configuration **object.
The payment /preAuth response provides the:
- cardToken - yourConsumerReference | | Process a Web SDK card token payment / preAuth with the CV2 / CVV security code included in the request.
This will check the CV2 / CVV and card token are valid and match the stored card details. | 200
Successful | The consumer will not be prompted to enter the security code.
Ensure you have defined the **token configuration **object. where **securityCode **is set and **shouldVerifySecurityCode**=**false**
When making token payments or preAuths, the **cardToken** and **yourConsumerReference **must match the original reference when the token was initially created. | | Process a Web SDK card token payment prompting the consumer to enter **just **their cardholder name. | | Set:
- shouldVerifyCardholderName: **true** - shouldVerifySecurityCode: **false**
If **cardHolderName **is provided in the configuration object, it will be overwritten with the value entered here.
When making token payments or preAuths, the **cardToken** and **yourConsumerReference **must match the original reference when the token was initially created. | | Process a Web SDK card token payment prompting the consumer to enter **just **their card security code. | | Set:
- shouldVerifySecurityCode: **true** - shouldVerifyCardholderName: **false**
If **securityCode **is provided in the configuration object, it will be overwritten with the value entered here.
When making token payments or preauths, the **cardToken** and **yourConsumerReference **must match the original reference when the token was initially created. | | Process a Web SDK card token payment prompting the consumer to enter **both **their cardholder name and security code. | | Set:
- shouldVerifyCardholderName: **true** - shouldVerifySecurityCode: **true**
When making token payments or preauths, the **cardToken** and **yourConsumerReference **must match the original reference when the token was initially created. | | **3D Secure 2 Flows**
For each 3D Secure 2 scenario, different calls are made from the front end to the back end.
It is advised to be aware of the different results from each flow and how your app will handle these. | | | | Process a Web SDK card payment prompting the frictionless flow.
[Testing 3D Secure 2 Flows (Frictionless Flow)](docId\:BdCGiYQDm3mlE-UBxp1yR) | | Ensure Judopay has enabled 3D Secure 2 on your sandbox tokens.
If 3D Secure 2 is not enabled on your tokens, the test transaction will be successful, however it will not have followed the 3D Secure 2 verification process. | | Process a Web SDK card payment prompting the non-frictionless flows.
[Testing 3D Secure 2 Flows (Non-Frictionless Flow)](docId\:BdCGiYQDm3mlE-UBxp1yR) | | Ensure Judopay has enabled 3D Secure 2 on your sandbox tokens.
If 3D Secure 2 is not enabled on your tokens, the test transaction will be successful, however it will not have followed the 3D Secure 2 verification process. | For more information on API credentials and permissions, see [Permissions](docId\:S_8hOAMytkgY13t0P657-). *** ### Test Data To simulate a successful web payments request, use the [Test Cards](docId:_OBafnuC1Umhk-vIhHs5D). :::hint{type="info"} To trigger specific **3D Secure 2 user journeys**, include the **cardHolderName **as specified in the [CardHolderName Table](docId\:BdCGiYQDm3mlE-UBxp1yR). The **cardHolderName **is case sensitive and corresponds to an **expected transaction result**. ::: *** ### Request Parameters **Taking a card payment or preAuth:** - Define the configuration object for the **payment **or **preAuth**. - Add the `.invokePayment` call to invoke a payment using the paymentSession and configuration object. - Add the `.invokePreauth`call to invoke a preAuth using the paymentSession and configuration object. **Making a check card request:** - Define the configuration object for the **checkCard**. - Add the `.invokeCheckCard` call to make a Check Card request using the paymentSession and configuration object. **Taking a card token payment or token preAuth:** - Define the configuration object for the** token payment** or **token preAuth**. - Add the `.invokeTokenPayment` call to invoke a payment using the paymentSession and configuration object. - Add the `.invokeTokenPreauth` call to invoke a preAuth using the paymentSession and configuration object. **Header Parameters:** These header parameters are to be used when creating the [paymentSession - (Prerequisite)](docId\:a33b4PWt6BRoFeJpgHDH2) request to our Transaction API. For more information, see [Authentication Methods](docId\:ylKW5coh5NQnfQ3j_Wjk2). | API-Version: | 6.26
For the latest version of the Judopay Transaction API, see [Latest Version](docId\:bcXNM5keOk-nlNrZTafUT). | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Content-Type: | application/json | | Accept: | application/json | | **Authorization Method**:
TokenSecretAuth | In the Authorization Header:
* Supply: **Basic** \{`authstring`}
Example:
**Basic**`TXpFdPdRSzWmSGk4djhxeTpjBTS4YjQ5OTdkZmO7CTk1YTE0OWEyMDg1MmY3YWYyZWEyZTcwYmQyZGY3O`
Replace \{`authstring`} with **base64 encoding** of:
* **API Token** (username) * **Colon** * **API Secret** (password)
Example:
**MzPdkQK1mGi8v3ky****:****y158n4732dfc7595a149a20381f7af2ea2e70gr6df794b8rnwc019cc5f799kk3** | *** **Body Parameters:** **Web SDK Payment / preAuth / CheckCard / Token Payment Configuration Parameter Descriptions:** :::hint{type="warning"} **\*Mastercard Recommends:** These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow). ::: | **Parameter** | **Description** | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `judoId`
String
Required

| Unique ID supplied by Judopay.
Specific to a merchant and/or location.
Format:
* 100100100 * Maximum length 9 characters. * Do not include spaces or dashes. | | `amount`
Decimal
Required

| The amount to process.
Format:
* Two decimal places
For currencies using a different structure please contact Judopay for support. | | `currency`
String
Required
| The currency of the transaction.
Any ISO 4217 alphabetic currency code:
* GBP * USD * EUR | | `yourConsumerReference`
String
Required | Unique reference to anonymously identify your customer.
Advisable to use GUIDs.
Must be below 40 characters. | | `yourPaymentReference`
String
Required

| Your unique reference for this payment.
Format:
* Maximum length 50 characters.
This value should be unique in order to protect your customers against duplicate transactions.
With a server side integration, if a payment reference is not supplied, the transaction will not be processed. | | `phoneCountryCode`
String
Recommended *

| The country code of the consumer's phone.
Format:
* Maximum length 3 characters. * Only numbers allowed. * Do not include special characters or spaces.
Must be set if **mobileNumber** is set.
If not set, default = 44 | | `mobileNumber`
String
Recommended *

| Consumer’s valid mobile number.

Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.
Format:
* Maximum length 15 characters. * Only numbers allowed. * Do not include special characters or spaces.
Must be set if **phoneCountryCode** is set. | | `cardHolderName`
String
Recommended *
| The card name of the consumer.
If the cardHolderName field is displayed to the user in the payment form (**isCardHolderNameVisible: true** is set in the iFrame config), the value entered in the payment form will overwrite this value. | | `challengeRequestIndicator`
String
Optional


| Indicates the type of challenge request you wish to apply.
Set this to one of the following strings:
* `noPreference` * `noChallenge` - No challenge required. * `challengePreferred` - A challenge is preferred for this transaction. * `challengeAsMandate` - Must challenge this transaction.
This **should not **be included in the same configuration object as **scaExemption**. | | `initialRecurringPayment`
Boolean
Optional | Indicates if this initial payment is part of a recurring payment. | | `billingAddress`
Object
Optional

| Card holder's billing address.
Properties:
* `address1` (Recommended)* * `address2` (optional) * `town` * `state`(only required if country is USA/Canada) - Format: - string - ISO Alpha-2 Code (e.g. California = "**CA**") * `country` - Format: - string - See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes. - `postCode`
If the billingAddress is provided, the postcode is **required**. | | `emailAddress`
String
Recommended * | Consumer’s valid email address.

Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions. | | `primaryAccountDetails`
Object
Optional

| This is **Mandatory** for merchants who have an MCC code of **6012**.
Properties:
* `name` **This is the surname.** * `accountNumber` * `postCode` * `dateOfBirth` - Format: YYYY-MM-DD | | The configuration object for **token **payments takes the same parameters as the **paymentConfiguration **object, along with the additional **token specific parameters **to be included, as listed below: | | | `cardToken`
String
Required | A randomly generated string linked to the saved card stored in Judopay’s system. | | `shouldVerifySecurityCode`
Boolean
Optional | Indicates if the consumer will be prompted to enter their security code.
Default value = **true**. | | `securityCode`
String
Optional | The 3/4 digit security code associated with the consumer’s saved card.
This value will be overwritten if the user is prompted to enter their own value: (**shouldVerifySecurityCode=true**). | | `shouldVerifyCardHolderName`
Boolean
Optional | Indicates if the consumer will be prompted to enter their card holder name.
If the user is prompted to enter their card holder name AND you have provided cardHolderName in the config, the config value will be overwritten.
Default value = **false**. | :::CodeblockTabs Request Example ```javascript const paymentConfiguration = { judoId: "yourJudoId", amount: 1.01, currency: "GBP", phoneCountryCode: "44", challengeRequestIndicator: "challengeAsMandate", initialRecurringPayment: false, yourConsumerReference: "yourConsumerReference", yourPaymentReference: "yourPaymentReference", billingAddress: { address1: "My house", address2: "My street", town: "My town", postCode: "TR14 8PA", country: "826" }, mobileNumber: "07999999999", emailAddress: "contact@judopay.com", primaryAccountDetails: { name: "Doe", accountNumber: "9999999", dateOfBirth: "1989-09-19", postCode: "AB1 2CD" } } ``` Response Example ```none 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 } ``` ::: *** ## Card Payment Scenarios (Negative Flow) Declines can occur for various reasons, it can be impossible to simulate all the negative flows in a sandbox environment. ### Important to Consider - How your app handles negative flows - Your customer's experience should a negative flow occur: - Logic to communicate error messages - Customise how your app responds - How to maintain application consistency Follow our suggested guidelines to simulate negative scenarios, to test your app’s error handling: | **Suggested Negative Test Scenario** | **Expected Error Code** | **Error Description** | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Attempt to perform a Web SDK card payment / preAuth / checkCard request decline using the following:
* **cardNumber**: 4221690000004963 * **cv2**: 452 * **expiryDate**: 12/24 | Declined
| Card declined. | | Attempt to perform a Web SDK card payment / preAuth / checkCard request gateway error
using the following:
* **cardNumber**: 4976350000006891 * **cv2**: 341 * **expiryDate**: 12/30
The transaction request has passed all Judopay's validation checks.
The next step in the payment flow is for the gateway to perform their checks.
A gateway error occurs when for example, the gateway verifies the request details with the issuing bank, who declines the request as there are not enough funds in the account.
**This response contains the receiptId.** | Declined
| Card declined. | | Attempt a Web SDK card payment / preAuth with the Incorrect currency entered for the specified transaction.
**Default currency = GBP** | 72 | Sorry, we're currently unable to route this transaction. Please check your account details and try again.
If this issue persists, please contact customer services.
This is a [processing error](docId:_zrsihomUEW-XnRQ4PBtJ). | | Attempt to perform a Web SDK card payment 3D Secure 2 challenge flow, where the user taps the cancel button on the challenge screen.
Ensure you have set the correct flags to control the 3D Secure 2 challenge scenarios. | 165 | Unable to process transaction. Card authentication failed with 3DS Server.
| | Attempt to perform a Web SDK card payment / preAuth / checkCard request with the incorrect environment (live or sandbox) for your API Token and API Secret and configuration. | 7 | Sorry, we were unable to authorize this request. Please check your details and permissions before trying again. | | Attempt to perform a duplicate transaction, re-using a **yourPaymentReference **that has already been used in a previous transaction. | 86 | Sorry, this payment has been stopped as it is a duplicate transaction. | | Attempt to perform a Web SDK card payment / preAuth / checkCard request where the amount set in the configuration object is different to the amount set in the paymentSession. | 12 | Sorry, we were unable to process your payment. Please check your details and try again. | | Attempt to perform a Web SDK card payment / preAuth / checkCard request where the card type used, is not supported on your Judopay account.
For example, if AMEX is not enabled on your account, use card type = AMEX. | 73 | Sorry, but this card type is not currently supported on this account. | | Attempt to perform a Web SDK card payment / preAuth / checkCard request where the card scheme used, is not defined in the iFrame configuration object.
For example, if AMEX is not defined, use card scheme = AMEX.
//An array of card schemes that are accepted by the merchant.
//If this field is set, an error will appear if an unsupported card scheme is entered.
**allowedCardSchemes: \['visa','mastercard'],** | | 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, see [Step Two: Add the Payment Form to your Website.](docId:40dWE6LBub7vdKza1QYDC) | :::hint{type="warning"} Where the codes remain fixed, the descriptions may change. You **should not **build any error handling logic based on these descriptions. ::: For a list of possible error codes, types and descriptions, see [Error Codes and Descriptions](docId:_zrsihomUEW-XnRQ4PBtJ).