--- title: Testing Web Payments - Card Payments slug: testing-web-payments-card-payments docTags: createdAt: 2024-06-10T11:52:36.852Z --- 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](docId\:K7FnZbol73SsCtbct4NXM). - 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](docId\:SaSeq4PpWBNsJt_if_0kX). :::hint{type="warning"} 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: 1. Select payment method 2. Enter billing information (Optional) 3. Enter card details 4. Review and Confirm (Optional) :::hint{type="info"} 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](mailto\:help@judopay.com) 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](mailto\:help@judopay.com) 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](docId\:mQjiiZXmCRo1cpvAUaWuD) 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. *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/O-aJYGmUVUqcURdnPbIVg_billing-info-screen.png" size="56" width="448" height="844" position="flex-start" alt="billing info screen" darkWidth="448" darkHeight="844" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/-_I6EpRUbpATh63qbXphr_randc-screen.png" size="56" width="448" height="583" position="flex-start" alt="review and confirm screen" darkWidth="448" darkHeight="583" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/wT-ZSxAoSVOOAGyCLysum_card-payment-screen.png" size="56" width="448" height="697" position="flex-start" alt="card payment screen" darkWidth="448" darkHeight="697" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/NGcnRhq8ZoM9CBrOqrcyH_payment-successful.png" size="68" width="180" height="238" position="flex-start" alt="payment successful" darkWidth="180" darkHeight="238" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/iYHNKrheJgehtPU_pN_6V_preauth-successful.png" size="56" width="179" height="186" position="flex-start" alt="preauth successful page" darkWidth="179" darkHeight="186" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: :::VerticalSplitItem **Expected Outcome** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/yqZl-y6ixKCELMvciPgQB_validation-successful.png" size="56" width="163" height="150" position="flex-start" alt="validation successful page" darkWidth="163" darkHeight="150" showCaption="false"} ::: :::: *** :::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: ::::VerticalSplitItem **Expected Outcome** :::BlockQuote "expiryDate": "2028-11-05T16:28:32.8596+00:00", ::: :::: ::::: *** :::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: ::::VerticalSplitItem **Expected Outcome** :::BlockQuote }, "status": "Cancelled", "transactionType": "Payment", }, ::: :::: ::::: *** :::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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. ::: ::::VerticalSplitItem **Expected Outcome** **Example 1** **Status Open:** :::BlockQuote "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:** :::BlockQuote "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 `receiptId`to **GET **information on the transaction. :::BlockQuote "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:** :::BlockQuote \{ "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj\_XDg", "status": "Cancelled" } ::: :::: ::::: *** For more information on API credentials and permissions, see [Permissions](docId\:S_8hOAMytkgY13t0P657-). *** ### Card Data To simulate a successful web payments request, use the [Test Cards](docId:_OBafnuC1Umhk-vIhHs5D). *** ### Request Parameters Sandbox endpoint: `https://api-sandbox.judopay.com/webpayments/preauths` For the full schema details and descriptions, see[ Transaction API /webpayments/preauths.](https://docs.judopay.com/api-reference) Sandbox endpoint: `https://api-sandbox.judopay.com/webpayments/checkcard` For the full schema details and descriptions, see[ Transaction API /webpayments/checkcard.](https://docs.judopay.com/api-reference) Sandbox endpoint: `https://api-sandbox.judopay.com/webpayments/payments` For the full schema details and descriptions, see[ Transaction API/webpayments/payments.](https://docs.judopay.com/api-reference) 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](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 Payments Configuration Property 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.
**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
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 | | `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` (Recommended)* * `address2` (optional) * `town` * `state` (only required if country is USA/Canada) * `country` See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes. * `postcode`
If the cardAddress is provided, the postcode is **required**. | | `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. | | `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**, **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. | :::CodeblockTabs Web Payments Request Example ```json { "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": "2028-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" } } ``` Response Example ```json //Store the reference returned in your backend server: { "payByLinkUrl": "https://pay-sandbox.judopay.com/ABC123", "postUrl": "https://pay-sandbox.judopay.com/v2", "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj_XDg" } ``` ::: *** ## 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. *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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 ::: :::VerticalSplitItem **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**. ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/qdlvH1FJkfYznKG6y8KKC_payment-declined.png" size="62" width="160" height="176" position="flex-start" alt="payment declined screen" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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 ::: :::VerticalSplitItem **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. ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/VqLxZVtp9ZpWHyDN8ss3j_validation-failed.png" size="62" width="160" height="151" position="flex-start" alt="validation failed screen" showCaption="false"} ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **Suggested Negative Test Scenario** Attempt to perform a web payments card: - payment - preAuth request using an **Expired **payment session. ::: :::VerticalSplitItem **Expected Error Code and Description** 667003 WebPayment reference is invalid. ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **Suggested Negative Test Scenario** Attempt to perform a web payments card: - payment - preAuth - checkCard request using an invalid card number. ::: :::VerticalSplitItem **Expected Error Code and Description** 196 Unable to process transaction as the card number is invalid. Please try again with a different card. ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **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**. ::: :::VerticalSplitItem **Expected Error Code and Description** 158 Sorry, but your card authentication has failed. ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **Suggested Negative Test Scenario** Attempt to perform a web payments card: - payment - preAuth - checkCard request using an expiry date that is in the past. ::: :::VerticalSplitItem **Expected Error Code and Description** 155 Sorry, but the Web Payment expiry date must be in the future. ::: :::: *** ::::VerticalSplit{layout="middle"} :::VerticalSplitItem **Suggested Negative Test Scenario** Attempt to perform a checkCard request decline using the following: - **cardNumber**: 4221690000004963 - **cv2**: 452 - **expiryDate**: 12/24 ::: :::VerticalSplitItem **Expected Error Code and Description** Declined Card declined. ::: :::: *** :::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 [Codes](docId:_zrsihomUEW-XnRQ4PBtJ).