Testing Web Payments - Card Payments

Testing Web Payments - Card Payments
With Judopay’s Web Payments solution, the 3D Secure 2 flows are handled on your behalf.
For example, you will not see the conditional device details check step, as this occurs in the background.
It is useful to have an understanding of the full 3DS 2 payment flow, including the conditional steps, to verify how it relates to the user journey in your app. 
For more information, see Overview of the Frictionless and Challenge Flows﻿.
When processing live transactions, in order to minimise declines we recommend setting the challengeRequestIndicator to challangeAsMandate.
For more information on the different authentication flows, see Challenge Request Indicator﻿.
For checkCard requests, a challenge flow will always be forced, regardless of the challengeRequestIndicator flag setting.
The web payments card payment journey consists of the following steps:
Select payment method
Enter billing information (Optional)
Enter card details
Review and Confirm (Optional)
You can customise whether to display the billing information and the Review & Confirm screens to the consumer during their payment journey.
﻿
Card Payment Scenarios (Positive Flow)
Important to Consider
Ensure the Create Web Payment and Retrieve Web Payment permissions are enabled on your API credentials.
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. 
Contact Customer Support to set this up.
Ensure Judopay has enabled the Enforce AVS checks on your sandbox tokens.
This will validate the billing address is registered to that card.
Ensure you have set up the successUrl and cancelUrl landing pages in the Judopay Portal. 
You can also contact Customer Support to set this up.
If these are not set up a default landing page will be presented to the consumer. 
The merchant will not have visibility of the transaction details and will need to create a GET transaction query, or set up webhooks﻿  in order to be notified of the event.
You can determine which screens are displayed to the consumer during the payment flow.
Set the hideBillingInfo and hideReviewInfo flags accordingly.
﻿
﻿
Suggested Test Scenario
Process a web payments card payment / preAuth / checkCard request with the Billing information screen displayed to the consumer.
﻿
﻿TIP: 
Set the hideBillingInfo flag when creating the payment session.
Create a web payment session where hideBillingInfo = false
Default setting = true.
The consumer is directed to the Billing information screen during the payment flow.
  
Expected Outcome
﻿
﻿
Suggested Test Scenario
Process a web payments card payment / preAuth / checkCard request with the Review & Confirm screen displayed to the consumer.
﻿
﻿TIP: 
Set the hideReviewInfo flag when creating the payment session. The Review & Confirm screen will be hidden.
Create a web payment session where hideReviewInfo = false
Default setting = true.
The consumer is directed to the Review & Confirm screen during the payment flow.
Expected Outcome
﻿
﻿
Suggested Test Scenario
Process a web payments card payment / preAuth / checkCard request with the Billing information screen hidden to the consumer.
﻿
﻿TIP: 
Set the hideBillingInfo flag when creating the payment session.
Create a web payment session where hideBillingInfo = true
Default setting = true.
The consumer is directed to the Pay with card screen, as the Billing information screen is hidden during the payment flow.
Expected Outcome
﻿
﻿
Suggested Test Scenario
Process a successful web payments card payment and re-direct to your successUrl landing page.
﻿
﻿TIP: 
Ensure you have set up the successUrl landing page in the Judopay Portal.
If this is not set up a default landing page will be presented to the consumer.
When re-directing the POST call to the successUrl, the payload will also contain the:
receiptId 
cardToken 
reference 
yourConsumerReference
yourPaymentReference 
Store the cardToken for future transactions.
Use the receiptId to GET information on the transaction.
﻿
Expected Outcome
﻿
﻿
Suggested Test Scenario
Process a successful web payments card preAuth and re-direct to your successUrl landing page.
﻿
﻿TIP: 
Ensure you have set up the successUrl landing page in the Judopay Portal.

If this is not set up a default landing page will be presented to the consumer.
The Send and Download Receipt buttons will be hidden as it is a preAuth request.
Expected Outcome
﻿
﻿
Suggested Test Scenario
Process a successful web payments checkCard validation request and re-direct to your successUrl landing page.
﻿
﻿TIP:
Ensure you have set up the successUrl landing page in the Judopay Portal.

If this is not set up a default landing page will be presented to the consumer.
The CheckCard request is similar to the Payments and PreAuths request, just remove the amount field.
Expected Outcome
﻿
﻿
Suggested Test Scenario
Set an expiry date for the payment session.
﻿
﻿TIP: 
The paymentSession will expire in 30 minutes, unless an ExpiryDate is set in the /paymentsession request body.
Update the expiryDate field in the request body to set an expiry date in the future.
Default = 30 minutes.
You can then store the session to use at a later date.
﻿
Expected Outcome
"expiryDate": "2023-11-05T16:28:32.8596+00:00",
﻿
Suggested Test Scenario
Cancel an open payment session.
﻿
﻿TIP: 
Update the status of an Open payment session to Cancelled, preventing it from being used in the future.

Use the endpoint: PUT 
/paymentsession/{reference}/cancel
The reference returned in response to the creation of the payment session.
﻿
Expected Outcome
},
  "status":   "Cancelled",     
  "transactionType": "Payment",
},
﻿
Suggested Test Scenario
Check the status of a payment session.
﻿
﻿TIP: 
Use the endpoint: GET
/webpayments/{reference}
The reference returned in response to the creation of the payment session.
Possible status values:
Open
Success
Expired
Cancelled
You can determine the number of Open attempts that are remaining for that payment session from the response.
The paymentSession can be used for up to three transaction attempts for the same transaction.
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.
Expected Outcome
Example 1
Status Open:
"status": "Open",
 "transactionType": "Payment",
 "yourConsumerReference": "ab60f4e1-42a4-42e9-b2c5-6f1eb295f979",
 "yourPaymentMetaData": {
 "examplefield1": "value1",
 "examplefield2": "value2"
 },
 "yourPaymentReference": "66c7c4ee-0888-48b3-9ac3-b6a63113f9cb",
 "webPaymentOperation": 0,
 "isJudoAccept": false,
 "isThreeDSecureTwo": true,
 "noOfAuthAttempts": 0,
 "mobileNumber": "7777777777",
 "phoneCountryCode": "44",
 "emailAddress": "contact@judopay.com",
 "shortReference": "qoEeWo"
﻿
Example 2 
Status Expired:
"status": "Expired",
 "transactionType": "Payment",
 "yourConsumerReference": "b4f34320-f3d5-4464-82df-335195f8d59d",
 "yourPaymentMetaData": {
 "examplefield1": "value1",
 "examplefield2": "value2"
 },
 "yourPaymentReference": "4a04b9a2-fdbf-4ab2-b42d-5ff3a9016e1a",
 "webPaymentOperation": 0,
 "isJudoAccept": false,
 "isThreeDSecureTwo": true,
 "noOfAuthAttempts": 0,
 "mobileNumber": "7777777777",
 "phoneCountryCode": "44",
 "emailAddress": "contact@judopay.com",
 "shortReference": "L8xEK6"
﻿
Example 3
Status Success:
When you see status = Success, the receiptId will also be in the response. 
Use the receiptIdto GET information on the transaction.
"status": "Success",
 "transactionType": "Payment",
 "yourConsumerReference": "f5553f35-8826-49ff-894d-4522b52c9784",
 "yourPaymentMetaData": {
 "examplefield1": "value1",
 "examplefield2": "value2"
 },
 "yourPaymentReference": "30ba117e-415d-4445-9114-8dc4d23846c7",
 "webPaymentOperation": 0,
 "isJudoAccept": false,
 "isThreeDSecureTwo": true,
 "noOfAuthAttempts": 1,
 "receipt": {
 "receiptId": "966323098188161024",
 },
﻿
Example 4
Status Cancelled:
{
 "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj_XDg",
 "status": "Cancelled"
}
﻿
For more information on API credentials and permissions, see Permissions﻿.
﻿
Card Data
To simulate a successful web payments request, use the Test Cards﻿.
﻿
Request Parameters
Sandbox endpoint:
https://api-sandbox.judopay.com/webpayments/preauths
For the full schema details and descriptions, see Transaction API /webpayments/preauths.﻿
Sandbox endpoint:
https://api-sandbox.judopay.com/webpayments/checkcard
For the full schema details and descriptions, see Transaction API /webpayments/checkcard.﻿
Sandbox endpoint:
https://api-sandbox.judopay.com/webpayments/payments
For the full schema details and descriptions, see Transaction API/webpayments/payments.﻿
HTTP Method: POST
Header Parameters:
Depending on how you integrate with Judopay, you can authenticate requests by:
/paymentsession, or
TokenSecretAuth
The token and secret pair
For more information, see Authentication Methods﻿.
API-Version:
6.23
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
﻿
﻿
Body Parameters:
Web Payments Configuration Property Descriptions
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, remove the amount field.
currency
String
Required﻿
﻿
﻿
The currency of the transaction. 
Any ISO 4217 alphabetic currency code:
GBP
USD
EUR
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.
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.
cardAddress
Object
Optional﻿
﻿
﻿
Card holder's address.
Values:
address1
address2 (optional)
town
state (only required if country is USA/Canada)
country
See here﻿ for the list of valid ISO 3166-1 format country codes.
postcode
If the billingAddress is provided, the postcode is required.
mobileNumber
String
Optional﻿
Consumer’s valid mobile number.
Format:
Maximum length 15 characters.
Only numbers allowed.
Do not include special characters or spaces.
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, 6051 and 7299.
Primary Account Holder Details:
name
This is the surname.
accountNumber
dateOfBirth
Format: YYYY-MM-DD
postCode
expiryDate
String
Optional﻿
Date and time of expiry.
The default is 30 minutes from creation.
isPayByLink
Boolean
Optional﻿
Flag indicating whether this session should be shown in the Pay By Link section in the Judopay Portal.
Default = false
isJudoAccept
Boolean
Optional﻿
Flag indicating whether this session should be shown in the Judo Accept section in the Judopay Portal.
Default = false
successUrl
String
Optional﻿
﻿
﻿
This is the URL to which the consumer is redirected if their transaction is successful.
If not set, then the default success url specified on your account is used.
Format:
Maximum length 2048 characters.
cancelUrl
String
Optional﻿
﻿
﻿
This is the URL to which the consumer is redirected if they cancel the transaction or if the transaction fails. 
If not set, then the default cancel url specified on your account is used.
Format:
Maximum length 2048 characters.
hideBillingInfo
Boolean
Optional﻿
This flag can be used to determine whether the 'Billing information' page is shown on the Webpayments UI.
Default = true
hideReviewInfo
Boolean
Optional﻿
This flag can be used to determine whether the 'Review and Confirm' page is shown on the Webpayments UI.
Default = true
threeDSecure
Object
Optional﻿
challengeRequestIndicator

Indicates the type of challenge request you wish to apply.
Values:
noPreference
noChallenge
No challenge required.
challengePreferred
A challenge is preferred for this transaction.
challengeAsMandate
Must challenge this transaction.
scaExemption
To apply for an exemption from SCA, for a customer initiated transaction.
Values:
lowValue
Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
trustedBeneficiary
Provides the cardholder the option to add the merchant to their trusted list.
transactionRiskAnalysis
Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.
﻿
Web Payments Request Example
Response Example
{
"judoId": "yourJudoId",
  "yourConsumerReference": "yourConsumerReference",
  "yourPaymentReference": "yourPaymentReference",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99,
    "hideBackButton": true
  },
  "currency": "GBP",
  "amount": 12.99,
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": 826,
    "state": "FL",
    "cardHolderName": "John Doe"
  },
  "expiryDate": "2021-02-05T16:28:32.8596+00:00",
  "isPayByLink": false,
  "isJudoAccept": false,
  "successUrl": "https://my.site.com/success",
  "cancelUrl": "https://my.site.com/cancel",
  "emailAddress": "test.user@judopay.com",
  "mobileNumber": "7999999999",
  "phoneCountryCode": "44",
  "threeDSecure": {
    "challengeRequestIndicator": "challengeAsMandate"
  },
  "hideBillingInfo": true,
  "hideReviewInfo": true,
  "primaryAccountDetails": {
    "name": "Doe",
    "accountNumber": "12345678",
    "dateOfBirth": "1980-01-31",
    "postCode": "AB1 2CD"
  }
}
{
"judoId": "yourJudoId",
  "yourConsumerReference": "yourConsumerReference",
  "yourPaymentReference": "yourPaymentReference",
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99,
    "hideBackButton": true
  },
  "currency": "GBP",
  "amount": 12.99,
  "cardAddress": {
    "address1": "CardHolder House",
    "address2": "1 CardHolder Street",
    "town": "CardHolder Town",
    "postCode": "AB1 2CD",
    "countryCode": 826,
    "state": "FL",
    "cardHolderName": "John Doe"
  },
  "expiryDate": "2021-02-05T16:28:32.8596+00:00",
  "isPayByLink": false,
  "isJudoAccept": false,
  "successUrl": "https://my.site.com/success",
  "cancelUrl": "https://my.site.com/cancel",
  "emailAddress": "test.user@judopay.com",
  "mobileNumber": "7999999999",
  "phoneCountryCode": "44",
  "threeDSecure": {
    "challengeRequestIndicator": "challengeAsMandate"
  },
  "hideBillingInfo": true,
  "hideReviewInfo": true,
  "primaryAccountDetails": {
    "name": "Doe",
    "accountNumber": "12345678",
    "dateOfBirth": "1980-01-31",
    "postCode": "AB1 2CD"
  }
}
﻿
﻿
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
Process an unsuccessful web payments card payment / preAuth and re-direct to your cancelUrl landing page.
Use the following:
cardNumber: 4221690000004963
cv2: 452
expiryDate: 12/24
Expected Error Code and Description
Ensure you have set up the cancelUrl landing page in the Judopay Portal.

If this is not set up a default landing page will be presented to the consumer.
The cardToken value = null.
﻿
﻿
Suggested Negative Test Scenario
Process an unsuccessful web payments card checkCard validation request and re-direct to your cancelUrl landing page.
Use the following:
cardNumber: 4221690000004963
cv2: 452
expiryDate: 12/24
Expected Error Code and Description
Ensure you have set up the cancelUrl landing page in the Judopay Portal
If this is not set up a default landing page will be presented to the consumer.
﻿
﻿
Suggested Negative Test Scenario
Attempt to perform a web payments card:
payment
preAuth 
request using an Expired payment session.
﻿
Expected Error Code and Description
667003

WebPayment reference is invalid.

﻿
Suggested Negative Test Scenario
Attempt to perform a web payments card:
payment
preAuth
checkCard 
request using an invalid card number.
﻿
Expected Error Code and Description
196

Unable to process transaction as the card number is invalid. Please try again with a different card.

﻿
Suggested Negative Test Scenario
Attempt to perform a web payments card:
payment
preAuth
checkCard 
request using an invalid billing address.
To validate the card is registered to the correct post code, ensure the following permission on your sandbox API credentials is enabled:
Enforce AVS checks.
Default setting = disabled.
﻿
Expected Error Code and Description
158

Sorry, but your card authentication has failed.
﻿
Suggested Negative Test Scenario
Attempt to perform a web payments card:
payment
preAuth
checkCard 
request using an expiry date that is in the past.
﻿
Expected Error Code and Description
155

Sorry, but the Web Payment expiry date must be in the future.
﻿
Suggested Negative Test Scenario
Attempt to perform a checkCard request decline using the following:
cardNumber: 4221690000004963
cv2: 452
expiryDate: 12/24
﻿
Expected Error Code and Description
Declined

Card declined.
﻿
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 Codes﻿. 

API-Version:	6.23 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

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, remove the amount field.
currency String Required	The currency of the transaction. Any ISO 4217 alphabetic currency code: GBP USD EUR
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.
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.
cardAddress Object Optional	Card holder's address. Values: address1 address2 (optional) town state (only required if country is USA/Canada) country See here for the list of valid ISO 3166-1 format country codes. postcode If the billingAddress is provided, the postcode is required.
mobileNumber String Optional	Consumer’s valid mobile number. Format: Maximum length 15 characters. Only numbers allowed. Do not include special characters or spaces.
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, 6051 and 7299. Primary Account Holder Details: name This is the surname. accountNumber dateOfBirth Format: YYYY-MM-DD postCode
expiryDate String Optional	Date and time of expiry. The default is 30 minutes from creation.
isPayByLink Boolean Optional	Flag indicating whether this session should be shown in the Pay By Link section in the Judopay Portal. Default = false
isJudoAccept Boolean Optional	Flag indicating whether this session should be shown in the Judo Accept section in the Judopay Portal. Default = false
successUrl String Optional	This is the URL to which the consumer is redirected if their transaction is successful. If not set, then the default success url specified on your account is used. Format: Maximum length 2048 characters.
cancelUrl String Optional	This is the URL to which the consumer is redirected if they cancel the transaction or if the transaction fails. If not set, then the default cancel url specified on your account is used. Format: Maximum length 2048 characters.
hideBillingInfo Boolean Optional	This flag can be used to determine whether the 'Billing information' page is shown on the Webpayments UI. Default = true
hideReviewInfo Boolean Optional	This flag can be used to determine whether the 'Review and Confirm' page is shown on the Webpayments UI. Default = true
threeDSecure Object Optional	challengeRequestIndicator Indicates the type of challenge request you wish to apply. Values: noPreference noChallenge No challenge required. challengePreferred A challenge is preferred for this transaction. challengeAsMandate Must challenge this transaction. scaExemption To apply for an exemption from SCA, for a customer initiated transaction. Values: lowValue Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100. trustedBeneficiary Provides the cardholder the option to add the merchant to their trusted list. transactionRiskAnalysis Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

Testing your Web Payments Integration

Testing your Mobile SDK Integration