--- title: Testing Merchant Initiated Transactions slug: testing-merchant-initiated-transactions docTags: createdAt: 2024-06-10T10:42:52.099Z --- 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. ## Merchant Initiated Transactions (MIT) Scenarios (Positive Flow) The **first subscription payment** must have followed the **3D Secure 2 flow**. Contact [Developer Support](mailto\:developersupport@judopay.com) if you have any queries on **initial **MIT payments. See [Merchant Initiated Transactions](docId\:ek1dldO8cGr9DI226zlyf) for more information. *** ### Important to Consider - Provide the following fields and associated values in your MIT requests: - **recurringPayment** - Indicates if this is a recurring payment. - **relatedReceiptId** - The receiptId returned from the first subscription payment. - Must be as a result of the initial transaction being processed through a 3D Secure 2 flow. - **recurringPaymentType** - Indicates the type of recurring payment. - This can be set to 'RECURRING' (for scheduled payments) or 'MIT' (for unscheduled payments). - Store the** cardToken** and** relatedReceiptId**, as they will be required for future transactions. - The relatedReceiptId must be as a result of an initial transaction processed from a** 3D Secure 2 flow**. - You need to tag your MIT / recurring transactions correctly using the** relatedReceiptId**. This is to ensure your transactions are not declined by your customers’ issuing bank. - The relatedReceiptId is the receiptId returned from the **first subscription payment**. It references all subsequent recurring transactions to the original transaction. :::hint{type="warning"} Following testing MIT transactions in the sandbox environment, it is **critical these are tested again with live transaction tests prior to formally going live**, as sandbox behaviour differs slightly to live. ::: ### Batch Based MIT Tests Due to rate limits applied in both sandbox and production, we recommend adding **pauses **between each MIT batch transaction. Otherwise the quota limit **may block transactions** and cause undesirable results. | **Suggested Test Scenario** | **Expected Outcome** | **Tip** | | --------------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Perform a Card Token Payment.
This will check the card token is valid and matches the stored card details. | 200
Successful | Ensure you have provided the following fields:
* `relatedReceiptId : {{receiptId}}` * `recurringPayment : true` * `recurringPaymentType : MIT`
Example Schema:
:::BlockQuote \{ "cardToken": "Va8hCyhAPcNeKJLMQcymfFdLU7njkZ9A", "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 1.01, "recurringPayment": true, "recurringPaymentType": "MIT", "relatedReceiptId": "689469972283396100" } :::
When making token payments, **yourConsumerReference **must match the original reference when the token was initially created. | | Perform a Card PAN Payment. | 200
Successful | Ensure you have provided the following fields:
* `relatedReceiptId : {{receiptId}}` * `recurringPayment : true` * `recurringPaymentType : MIT`
Example Schema:
:::BlockQuote \{ "cardNumber": "4111111111111111", "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 1.01, "recurringPayment": true, "recurringPaymentType": "MIT", "relatedReceiptId": "689469972283396100" } ::: | | Perform a Card Token preAuth.
This will check the card token is valid and matches the stored card details. | 200
Successful | Ensure you have provided the following fields:
* `relatedReceiptId : {{receiptId}}` * `recurringPayment : true` * `recurringPaymentType : MIT`
Example Schema:
:::BlockQuote \{ "cardNumber": "4111111111111111", "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 1.01, "recurringPayment": true, "recurringPaymentType": "MIT", "relatedReceiptId": "689469972283396100" } :::
When making token preAuths, **yourConsumerReference **must match the original reference when the token was initially created. | | Perform a Card PAN preAuth. | 200
Successful | Ensure you have provided the following fields:
* `relatedReceiptId : {{receiptId}}` * `recurringPayment : true` * `recurringPaymentType : MIT`
Example Schema:
:::BlockQuote \{ "cardToken": "Va8hCyhAPcNeKJLMQcymfFdLU7njkZ9A", "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 1.01, "recurringPayment": true, "recurringPaymentType": "MIT", "relatedReceiptId": "689469972283396100" } ::: | *** ### Test Card Data To simulate a successful MIT payment use the [Test Cards](docId:_OBafnuC1Umhk-vIhHs5D). *** ### MIT Request Parameters Sandbox endpoint: `https://api-sandbox.judopay.com/transactions/payments` 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** | **Parameter** | **Description** | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cardToken`
String
Required | A randomly generated string linked to a card saved securely within the Judopay Card Vault. | | `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. | | `recurringPayment`
String
Optional | Indicates if this is a recurring payment. | | `recurringPaymentType`
String
Optional | Indicates the type of recurring payment that the merchant is attempting to process.
This can be set to:
* RECURRING (for scheduled payments) or * MIT (for unscheduled payments). | | `relatedReceiptId`
String
Optional | The `receiptId `returned from the first subscription payment.
Adding the `relatedReceiptId `references the subsequent recurring transactions to the original transaction. | :::CodeblockTabs MIT Request Example ```json { "cardNumber": 4111111111111111, "cv2": "838" "expiryDate": "12/30", "cardAddress": { "address1": "CardHolder House", "address2": "1 CardHolder Street", "town": "CardHolder Town", "postCode": "AB1 2CD", "countryCode": 826 }, "judoId": 100502814, "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" } } ``` Response Example ```json { "receiptId": "914568453493526528", "yourPaymentReference": "34a73594-f3b2-414c-a5c9-58679530b418", "type": "Payment", "result": "Success", "judoId": 100502814, "originalAmount": "5.00", "netAmount": "5.00", "amount": "5.00", "currency": "GBP", "cardDetails": { "cardLastfour": "1111", "endDate": "1230", "cardToken": "SOF-xFmZmEnoR_Sj9mtrCvrxhw", "cardType": 1, "cardScheme": "VISA", "cardFunding": "Credit", "cardCategory": "", "cardCountry": "US", "bank": "JPMORGAN CHASE BANK, N.A." }, "cardAddress": { "address1": "CardHolder House", "address2": "1 CardHolder Street", "town": "CardHolder Town", "postCode": "AB1 2CD", "countryCode": 826 }, "consumer": { "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", }, } ``` ::: *** ## Merchant Initiated Transactions (MIT) 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 a payment with an invalid relatedReceiptId. | 20026
| The receipt ID specified is not valid for the request you are attempting. | | Attempt a payment where the relatedReceiptId for the original transaction, did not follow the 3D Secure 2 flow. | 185 | Authentication rejected by the Issuer as card authentication has failed. | | Attempt a payment with an incorrect yourConsumerReference. | 154 | Your provided consumer reference is incorrect, please check your details and try again. | :::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).