---
title: Testing Card PreAuths
slug: testing-card-preauths
docTags:
createdAt: 2024-06-10T08:51:00.910Z
---
These scenarios do not include 3D Secure 2 authentication testing.
See [Testing 3D Secure 2 Flows](docId\:BdCGiYQDm3mlE-UBxp1yR) for 3D Secure 2 authentication testing for your app.
## Card PreAuth and Card Token PreAuth Scenarios (Positive Flow)
### Important to Consider
- **yourPaymentReference **is your unique reference for each transaction.
- When making token preauths, **yourConsumerReference **must match the original reference when the token was initially created.
| **Suggested Test Scenario** | **Expected Outcome** | **Tip** |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Process a Card preAuth with the CV2/CVV security code included in the request.
This will check the CV2/CVV is valid for that card. | 200
Successful | The CV2 field check will be performed during the transaction process. |
| Process a Card preAuth without the CV2/CVV security code included in the request. | Declined | The CV2 field check will not be performed during the transaction process.
|
| Process a Card Token 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 CV2 field check will be performed during the transaction process.
When making token preauths, **yourConsumerReference **must match the original reference when the token was initially created. |
| Process a Card Token preAuth without the CV2/CVV security code included in the request.
| 200
Successful | The CV2 field check will not be performed during the transaction process.
When making token preauths, **yourConsumerReference **must match the original reference when the token was initially created. |
| Process a Card preAuth with the billing address information (cardAddress block) included in the request.
This will validate the billing address is registered to that card. | 200
Successful | Ensure the **cardAddress** block has the correct fields:
- `address1`
- `address2`
- `town`
- `postCode`
- Required
- `countryCode`
- See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
Example cardAddress block:
:::BlockQuote
"cardAddress": \{
"address1": "CardHolder House",
"address2": "1 CardHolder Street",
"town": "CardHolder Town",
"postCode": "AB1 2CD",
"countryCode": 826,
"state": "FL",
},
:::
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**.
**The default setting = disabled**. |
| Process a Card preAuth without the billing address information (cardAddress block) included in the request. | 200
Successful | |
| Process a Card Token preAuth with the billing address information (cardAddress block) included in the request.
This will validate the billing address and card token are valid and match the stored card details. | 200
Successful | Ensure the **cardAddress** block has the correct fields:
* `address1`
* `address2`
* `town`
* `postCode`
- Required
* `countryCode`
- See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
Example cardAddress block:
:::BlockQuote
"cardAddress": \{
"address1": "CardHolder House",
"address2": "1 CardHolder Street",
"town": "CardHolder Town",
"postCode": "AB1 2CD",
"countryCode": 826,
"state": "FL",
},
:::
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**.
**The default setting = disabled**.
When making token preauths, **yourConsumerReference **must match the original reference when the token was initially created. |
| Process a Card Token preAuth without the billing address information (cardAddress block) included in the request. | 200
Successful | When making token preauths, **yourConsumerReference **must match the original reference when the token was initially created. |
| Process a Card preAuth using the different currencies you will be implementing on your app. | 200
Successful | If you do not provide a currency in the preauth request, the default value (GBP) will be sent.
Ensure you have the correct currencies configured for your app. |
| Process a Card preAuth for MCC 6012 merchants, with the primaryAccountDetails block included in the request.
It is **mandatory **for merchants who have an **MCC code of 6012** to submit additional Information about the primary account holder for payment pre-authorisation.
For use by **MCC 6012 merchants** only. | 200
Successful | Ensure you send the **primaryAccountDetails** block in your request:
* `name`
**This is the surname**
* `accountNumber`
* `dateOfBirth`
- Format: YYYY-MM-DD
* `postCode`
Example primaryAccountDetails block:
:::BlockQuote
"primaryAccountDetails": \{
"name": "Smith",
"accountNumber": "1234567890",
"dateOfBirth": "1980-01-01",
"postCode": "AB1 2CD"
}
::: |
For more information on API credentials and permissions, see [Permissions](docId\:S_8hOAMytkgY13t0P657-).
***
### Test Card Data
To simulate a successful preAuth use the [Test Cards](docId:_OBafnuC1Umhk-vIhHs5D).
***
### Card PreAuth and Card Token PreAuth Request Parameters
Sandbox endpoint:
`https://api-sandbox.judopay.com/transactions/preauths`
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** |
| **Authorization Method**:
PaymentSessionAuthToken
| **For Payment Session authentication**
In the Api-Token header:
* Supply the token used to authenticate the call to generate a payment session
The** Payment-Session header** value must also be supplied. |
| **Authorization Method**:
PaymentSessionAuthReference
| **For Payment Session authentication**
In the Payment-Session header:
* Supply the reference returned in the create payment session response
The** Api-Token header** value must also be supplied. |
***
**Body Parameters**:
**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. |
| `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 |
| `challengeRequestIndicator`
String
Optional
| 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`
String
Optional
| To apply for an exemption from SCA, for a customer initiated transaction.
Values:
* `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 including low value transactions, provided a robust risk analysis is performed. |
| `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. |
| `billingAddress`
Object
Optional | Card holder's billing address.
* `address1` (Recommended)*
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. |
| `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. |
| `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` |
| `initialRecurringPayment`
Boolean
Optional | Indicates if this initial payment is part of a recurring payment. |
:::CodeblockTabs
Card PreAuth Request Example
```json
{
"cardNumber": 4111111111111111,
"cv2": 123,
"expiryDate": "12/30",
"cardAddress": {
"address1": "CardHolder House",
"address2": "1 CardHolder Street",
"town": "CardHolder Town",
"postCode": "AB1 2CD",
"countryCode": 826
},
"judoId": 100100100,
"yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
"yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134",
"yourPaymentMetaData": {
"internalLocationRef": "Example",
"internalId": 99
},
"amount": 1.01,
"currency": "GBP",
"cardHolderName": "John Doe",
"mobileNumber": 7999999999,
"phoneCountryCode": 44,
"emailAddress": "test.user@judopay.com",
"shippingAddress": {
"isBillingAddress": true
},
"threeDSecure": {
"authenticationSource": "Browser",
"methodNotificationUrl": "https://api-sandbox.judopay.com/order/3ds/methodNotification",
"challengeNotificationUrl": "https://api-sandbox.judopay.com/order/3ds/challengeNotification",
"methodCompletion": false,
"challengeRequestIndicator": "challengeAsMandate"
}
}
```
Card Token PreAuth Request Example
```json
{
"yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408",
"yourPaymentReference": "34a73594-f3b2-414c-a5c9-58679530b418",
"judoId": 100502814,
"amount": 5.00,
"cardToken": "SOF-xFmZmEnoR_Sj9mtrCvrxhw",
"cv2": "838"
}
```
Response Example
```json
{
"receiptId": "914568453493526528",
"yourPaymentReference": "34a73594-f3b2-414c-a5c9-58679530b418",
"type": "Preauth",
"createdAt": "2022-11-28T17:28:32.0996+00:00",
"result": "Success",
"message": "AuthCode: 5",
"judoId": 100502814,
"merchantName": "Shodan - Cybersource Routing",
"appearsOnStatementAs": "APL*/ShodanCybersourceRo",
"originalAmount": "5.00",
"netAmount": "5.00",
"amount": "5.00",
"currency": "GBP",
"acquirerTransactionId": "7016984508",
"externalBankResponseCode": "0",
"authCode": "5",
"cardDetails": {
"cardLastfour": "1111",
"endDate": "1230",
"cardToken": "oALxtKjEIG9mJtTeNUPFNgNZoG62ryT9",
"cardType": 1,
"cardScheme": "VISA",
"cardFunding": "Credit",
"cardCategory": "",
"cardCountry": "US",
"bank": "JPMORGAN CHASE BANK, N.A."
},
"billingAddress": {
"address1": "32 Edward Street",
"address2": "Camborne",
"town": "Cornwall cowrnwall",
"postCode": "TR14 8PA",
"countryCode": 426
},
"consumer": {
"yourConsumerReference": "cv2 test"
},
"risks": {
"postCodeCheck": "UNKNOWN",
"cv2Check": "UNKNOWN",
"merchantSuggestion": "Allow"
}
}
```
:::
If your request was successful, you will receive a** code 200** and a **receiptId**.
A receiptId is Judopay's unique reference for the transaction. It is used to process refunds or cancellations and to help us investigate any issues with the transaction.
***
## Card PreAuth 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
To simulate an **unsuccessful flow**, use the following test card details:
| **Card Type** | **Card Name** | **Card Number** | **Expiry Date** | **Start Date** | **CV2** | **Address** |
| ------------- | ------------- | ---------------- | --------------- | -------------- | ------- | ----------------------------------------------------------- |
| Visa | Ian Lee | 4221690000004963 | 12/22 | 01/18 | 125 | 274 Grove Street,
Rayvale,
Vertland
VT22 6JN |
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 a preAuth with an invalid CV2 | 74 | The CV2 entered is invalid. |
| Attempt a preAuth with a missing CV2.
The sandbox token has CV2 enabled, the payment request has an empty CV2 field. | 31 | Sorry, you've not supplied the 3-digit card security code. Please check your details and try again.
This is a [model error](docId:_zrsihomUEW-XnRQ4PBtJ)**.** |
| Attempt a preAuth with insufficient funds in the account. | Declined.
| Card declined.
|
| **Simulate an error resulting from invalid data:** | | |
| Attempt a preAuth with an incorrect card number entered. | 166 | Unable to process transaction. No record of card number found by 3DS Server. |
| Attempt a preAuth with an invalid card expiry month = 14 | 161 | Sorry, but the card expiry date must be in the future. |
| Attempt a preAuth using the Incorrect card token. | 70 | Sorry, but it looks like the card token specified is not valid.
Please check your details and try again. |
| **Simulate an error resulting from incorrect API credentials:** | | |
| Attempt a preAuth using the Incorrect judoId. | 77 | Judo id not found, please check the judo id. |
| Attempt a preAuth with the Incorrect currency entered for the specified transaction.
| 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). |
:::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, seesee [Error Codes and Descriptions](docId:_zrsihomUEW-XnRQ4PBtJ).
***
### Next Steps
Using the successful preAuth test transactions, you can test the following scenarios:
- [Voiding the preAuth](docId\:DMBAKsKJll551SuxQIPuM)
- [Collecting the preAuth](docId\:yVjgZT2gxWBDxm3m0wEmu)