Testing Web SDK - Card Payments

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:

 

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)

 

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)

 

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.

 

Test Data

To simulate a successful web payments request, use the test card details here.

 

To trigger specific 3D Secure 2 user journeys:

  • Include the cardHolderName as specified in the CardHolderName Table

    The cardHolderName 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.

 

These header parameters are to be used when creating the paymentSession - (Prerequisite) request to our Transaction API.

API-Version:

6.20

 

For the latest version of the Judopay Transaction API, see Latest Version.

Content-Type:

application/json

Accept:

application/json

Authorization Method

TokenSecretAuth

In the Authorization Header:

  • Supply: Basic {authstring}

Example:

BasicTXpFdPdRSzWmSGk4djhxeTpjBTS4YjQ5OTdkZmO7CTk1YTE0OWEyMDg1MmY3YWYyZWEyZTcwYmQyZGY3O

 

 

Replace {authstring} with base64 encoding of:

  • API Token (username)

  • Colon

  • API Secret (password)

Example:

MzPdkQK1mGi8v3ky:y158n4732dfc7595a149a20381f7af2ea2e70gr6df794b8rnwc019cc5f799kk3

For more information, see Authentication Methods.

 

 

Body Parameters:

 

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.

For checkCard requests, you do not need to include the amount field in your request body.

 

currency

String

Required

The currency of the transaction. 

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

For checkCard requests, you do not need to include the currency field in your request body.

 

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

Optional

The country code of the consumer's phone.

Format:

  • Maximum length 3 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Should be set if mobileNumber is set.
If not set, default = 44 

mobileNumber

String

Optional

Consumer’s valid mobile number.

Format:

  • Maximum length 15 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Must be set if phoneCountryCode is set.

 

cardHolderName

String

Optional

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

    string

  • address2 (optional)

    string

  • address3(optional)

    string

  • town

    string

  • state(only required if country is USA/Canada)

    • Format:

      • string

      • ISO Alpha-2 Code (e.g. California = "CA")

  • country

    • Format:

      • string

      • ISO Numeric Code (e.g. United Kingdom = "826")

  • postCode

    string

If the billingAddress is provided, the postcode is required.

 

emailAddress

String

Optional

Consumer’s valid email address.

It is recommended but not required for 3D Secure 2 authentication.

 

primaryAccountDetails

Object

Optional

This is Mandatory for merchants who have an MCC code of 6012

Properties:

  • name

    string

This is the surname.

  • accountNumber

    string

  • dateOfBirth

    string

    • Format: YYYY-MM-DD

  • postCode

    string

 

delayedAuthorisation

Boolean

Optional

For preAuths only.

Set to true to authenticate a card holder with 3D secure, without performing payment authorisation.

When set to true, the 3D Secure authentication status is returned in the response.

 

The payment authorisation is carried out at the stage when you are ready to collect the amount from the consumer.

  • The default value = false

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 *

 

 

Request Example:

 

Response

Response Reference Example:

 

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/25

 

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.

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.

<div class="judopay-errors" style="color:red">Error Location</div>

For more information, see Step Two: Add the Payment Form to your Website

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