--- title: Testing Digital Wallet Payments - via API slug: testing-digital-wallet-payments-via-api docTags: createdAt: 2024-06-10T15:23:53.590Z --- Testing Card payments for your Digital Wallet payments **via direct API integration.** :::hint{type="warning"} **Decline scenarios** for wallet payments cannot be tested in the sandbox environment. ::: The payment or preAuth request can be sent with wallet details from Apple Pay™ or Google Pay™: - The payment token provided by the Apple Pay session. - The payment token generated by the Google Pay API. ### Apple Pay™ Prerequisites - Before you can process Apple Pay™ payments and preAuths with Judopay, you will need to [Set up Apple Pay™](docId:09p1crU0CbxJkzEa-0ZPI) to get your **Merchant IDs**. - Contact [Support](mailto\:developersupport@judopay.com) to configure your wallet payments credentials. *** ### Google Pay™ Prerequisites - Before you can process Google Pay™ payments and preAuths with Judopay, you will need to[ Create a Google Pay Payments Profile](https://support.google.com/googleplay/android-developer/answer/7161426?hl=en-GB) to get your **Merchant IDs**. - Contact [Support](mailto\:developersupport@judopay.com) to configure your wallet payments credentials. *** ## Wallet Payment Scenarios (Positive Flow) The digital wallet payment flow provides consumers with an extra layer of security, encrypting and decrypting the card details sent in the payload by replacing the consumer's card details with a device token, or dynamic security code. ### What is the difference between DPAN and FPAN? - Device Primary Account Number (**DPAN**) - A device token is sent in the payload, instead of the card number. - SCA compliant. - Funding Primary Account Number (**FPAN**) - The card number is sent in the payload. - Requires 3D Secure 2 authentication to become SCA compliant. - Judopay's Transaction API** triggers the 3D Secure 2 flow**, to validate the transaction. *** ### Important to Consider for Apple Pay™and Google Pay™(DPAN) We **recommend **generating a **unique **Apple Pay™ and Google Pay™ payload for each test, to mimic the production environment where payloads can only be** used once**. We **do not** recommend making Merchant Initiated Transactions using card tokens that were generated by Apple Pay™ or Google Pay™ DPAN. You may experience a lower transaction success ratio. **Apple Pay™** (**DPAN**) - Mobile and Web integrations - SCA compliant - For a successful end-to-end wallet payment testing journey, it is recommended to: - Perform wallet test scenarios in a production environment - Use **live **cards to process test payments and preAuths - Ensure you have set up your Apple Pay™ certificate: - See, [Create an Apple Pay™ Certificate](docId:40dWE6LBub7vdKza1QYDC). **Google Pay™** (**DPAN**) - Mobile integration - SCA compliant - For a successful end-to-end wallet payment testing journey, it is recommended to: - Perform wallet test scenarios in a production environment - Use **live **cards to process test payments and preAuths. - The payload is the same when using Google Pay™ DPAN, or FPAN. - When sending the **judoId **in the payload to your Google Pay account, the field is displayed as **gatewayMerchantId **in the tokenization object. For example, the value used in gatewayMerchantId is the same value as your judoId: - " judoId" :"**100781350**" - "gatewayMerchantId":"**100781350**" *** ### Apple Pay™ and Google Pay™ (DPAN) Scenarios | **Suggested Test Scenario** | **Expected Outcome** | | ------------------------------------- | -------------------- | | Process an Apple Pay™ Wallet payment. | 200
Successful | | Process an Apple Pay™ Wallet preAuth. | 200
Successful | | Process a Google Pay™ Wallet payment. | 200
Successful | | Process a Google Pay™ Wallet preAuth. | 200
Successful | *** ### Important to Consider for Google Pay™ (FPAN) - Web integration - Requires 3D Secure 2 authentication to become SCA compliant. - Judopay's Transaction API** triggers the 3D Secure 2 flow**, to validate the transaction. - For more details on the 3D Secure 2 flow, see [How 3D Secure Works](docId\:K7FnZbol73SsCtbct4NXM). - To add your **test card suite** to your Digital Wallet to process test payments and preAuths, register your [Google Pay Wallet.](https://developers.google.com/pay/api/android/guides/resources/test-card-suite) - Details for the cards in your test card suite are hard coded into the test wallet, therefore some negative scenarios cannot be simulated, due to limitations to Google Pay™s test environment. For example you cannot simulate an incorrect cv2, or insufficient funds. - You will only receive a success response. - No charge will be made on the test cards. - The payload is the same when using Google Pay™ FPAN, or DPAN. - When sending the **judoId **in the payload to your Google Pay account, the field is displayed as **gatewayMerchantId **in the tokenization object. - " judoId" :"**100781350**" - "gatewayMerchantId":"**100781350**" - We recommend generating a **unique **Google Pay™ payload for each test, to mimic the production environment where payloads can only be** used once**. *** ### Google Pay™ (FPAN) Scenarios Judopay's Transaction API** triggers the 3D Secure 2 flow**, to validate the transaction when sending the **FPAN**. For each 3D Secure 2 scenario, different calls are made from the front end to the back end. Using a specific **cardHolderName** as specified in the [CardHolderName Table](docId\:BdCGiYQDm3mlE-UBxp1yR), will correspond to an** expected transaction result**. 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: - [Testing 3D Secure 2 Flows (Frictionless Flow)](docId\:BdCGiYQDm3mlE-UBxp1yR) - [Testing 3D Secure 2 Flows (Non-Frictionless Flow)](docId\:BdCGiYQDm3mlE-UBxp1yR) | **Suggested Test Scenario** | **Expected Outcome** | **Tip** | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Process a Google Pay™ Wallet payment, prompting the **frictionless **flow. | :::BlockQuote var googlePayConfiguration = \{ transactionMode: 'payment', scaExemption: null, challengeRequestIndicator: 'noChallenge' } ::: | As the **cardHolderName **is hard coded in your test card suite, you will not be able to use this field to determine the 3D Secure 2 flow.
You will need to set the **challengeRequestIndicator**, to determine the frictionless flow.
Type of challenge request:
* No Preference * No Challenge | | Process a Google Pay™ Wallet payment, prompting the** non-frictionless** flow. | :::BlockQuote var googlePayConfiguration = \{ transactionMode: 'payment', scaExemption: null, challengeRequestIndicator:'ChallengeAsMandate' } ::: | As the **cardHolderName **is hard coded in your test card suite, you will not be able to use this field to determine the 3D Secure 2 flow.
You will need to set the **challengeRequestIndicator**, to determine the non-frictionless flow.
Type of challenge request:
* Challenge Preferred * Challenge As Mandate | | Process a Google Pay™ Wallet preAuth, prompting the **frictionless **flow. | :::BlockQuote var googlePayConfiguration = \{ transactionMode: 'preAuth', scaExemption: null, challengeRequestIndicator: 'noChallenge' } ::: | As the **cardHolderName **is hard coded in your test card suite, you will not be able to use this field to determine the 3D Secure 2 flow.
You will need to set the **challengeRequestIndicator**, to determine the frictionless flow.
Type of challenge request:
* No Preference * No Challenge | | Process a Google Pay™ Wallet preAuth, prompting the** non-frictionless** flow. | :::BlockQuote var googlePayConfiguration = \{ transactionMode: 'preAuth', scaExemption: null, challengeRequestIndicator: 'ChallengeAsMandate' } ::: | As the **cardHolderName **is hard coded in your test card suite, you will not be able to use this field to determine the 3D Secure 2 flow.
You will need to set the **challengeRequestIndicator**, to determine the non-frictionless flow.
Type of challenge request:
* Challenge Preferred * Challenge As Mandate | For more information on API credentials and permissions, see [Permissions](docId\:S_8hOAMytkgY13t0P657-). *** ### Request Parameters The payment or preAuth request can be sent with wallet details from Apple Pay™ or Google Pay™. Sandbox endpoint: `https://api-sandbox.judopay.com/transactions/payments` Sandbox endpoint: `https://api-sandbox.judopay.com/transactions/preauths` HTTP Method: **POST** **Header Parameters:** 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**:
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**: **paymentRequestApplePay:** | **Parameter** | **Description** | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pkPayment`
Object
Required | Value:
* token (Required)
For information on how to generate your token, see [Apple Pay Payment Token](https://developer.apple.com/documentation/passkit/pkpaymenttokencontext). | | `cardAddress`
Object
Optional

| Card holder's address.
Values:
* `address1` * `address2` (optional) * `town` * `state` (only required if country is USA/Canada) * `country` * `postcode`
If the billingAddress is provided, the postcode is **required**. | | `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. | | `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. | | `yourConsumerReference`
String
Required | Unique reference to anonymously identify your customer.
Advisable to use GUIDs.
Must be below 40 characters. | | `currency`
String
Optional | The currency of the transaction.
Any ISO 4217 alphabetic currency code:
* GBP * USD * EUR | | `amount`
Number
Required | The amount to process.
Format:
* Two decimal places
For currencies using a different structure please contact Judopay for support. | | `webPaymentReference`
String
Optional | The unique reference of the Judopay payment session associated with this transaction. | | `initialRecurringPayment`
String
Optional | Indicates if this initial payment is part of a recurring payment. | | `primaryAccountDetails`
Object
Optional | This is **Mandatory **for merchants who have an MCC code of **6012**
Primary Account Holder Details:
* `Name` **This is the surname**. * `accountNumber` * `dateOfBirth` - Format: YYYY-MM-DD * `postCode` | *** **paymentRequestGooglePay** | **Parameter** | **Description** | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `googlePayWallet`
Object
Required
| Values:
* token (Required) - String - JSON serialized payment token generated by Google Pay API For information on how to generate your token, see [Google Pay Payment Token](https://developers.google.com/wallet/generic/web#saving_to). * cardNetwork (Optional) - String - Value Example: VISA - The payment card network returned by Google Pay API. Value should match one of the allowedCardNetworks in: `https://developers.google.com/pay/api/web/reference/request-objects#CardParameters` * cardDetails (Optional) - The details about the card returned by Google Pay API. This value is commonly the last four digits of the selected payment account number. | | `cardAddress`
Object
Optional

| Card holder's address.
Values:
* `address1` * `address2` (optional) * `town` * `state` (only required if country is USA/Canada) * `country` * `postcode`
If the billingAddress is provided, the postcode is **required**. | | `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. | | `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. | | `yourConsumerReference`
String
Required | Unique reference to anonymously identify your customer.
Advisable to use GUIDs.
Must be below 40 characters. | | `currency`
String
Optional | The currency of the transaction.
Any ISO 4217 alphabetic currency code:
* GBP * USD * EUR | | `amount`
Number
Required | The amount to process.
Format:
* Two decimal places
For currencies using a different structure please contact Judopay for support. | | `webPaymentReference`
String
Optional | The unique reference of the Judopay payment session associated with this transaction. | | `initialRecurringPayment`
Boolean
Optional | Indicates if this initial payment is part of a recurring payment. | | `primaryAccountDetails`
Object
Optional | This is **Mandatory **for merchants who have an MCC code of **6012**
Primary Account Holder Details:
* `Name` **This is the surname**. * `accountNumber` * `dateOfBirth` - Format: YYYY-MM-DD * `postCode` | | `deviceCategory`
String
Optional | Device category data passed to the card gateways.
* Mobile * Desktop | | `acceptHeaders`
String
Optional | Passed to ACS for use in rendering challenge screens. | | `userAgent`
String
Optional | Passed to ACS for use in rendering challenge screens. | | `cardHolderName`
String
Optional | The card name of the consumer. | | `emailAddress`
String
Optional | Consumer’s valid email address.
**It is recommended but not required for 3D Secure 2 authentication**. | | `shippingAddress`
Object
Optional | Card holder's shipping address.
If the shippingAddress 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 | | `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. | | `threeDSecure`
String
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. * `secureCorporate` - Request exemption for payments made using a corporate card. * `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. | | `threeDSecureMpi`
Object
Optional | Optional block to pass in 3DS2 authentication results performed outside of Judopay. | ### Apple Pay™ and Google Pay™ Request Example - **Apple Pay**: For information on how to generate your token, see [Apple Pay Payment Token](https://developer.apple.com/documentation/passkit/pkpaymenttokencontext). - **Google Pay**: The payload is the same when using Google Pay™ DPAN, or FPAN. For information on how to generate your token, see [Google Pay Payment Token](https://developers.google.com/wallet/generic/web#saving_to). :::CodeblockTabs Apple Pay Request Example ```json { "pkPayment": { "token": { "paymentNetwork": "Visa", "paymentData": { "data": "xxx", "signature": "xxx", "header": { "publicKeyHash": "xxx", "ephemeralPublicKey": "xxx", "transactionId": "xxx" }, "version": "EC-v1" }, "paymentInstrumentName": "Visa 1234" } }, "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "amount": 1.01, "currency": "GBP", "yourPaymentMetaData": { "internalLocationRef": "Example", "internalId": 99 } } ``` Google Pay Request Example ```json { "googlePayWallet": { "cardNetwork": "VISA", "cardDetails": "1234", "token": "{\"signature\":\"xxx\",\"protocolVersion\":\"ECv1\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"xxx\\\",\\\"ephemeralPublicKey\\\":\\\"xxx\\\",\\\"tag\\\":\\\"xxx\\\"}\"}" }, "judoId": 100100100, "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "amount": 1.01, "currency": "GBP", "yourPaymentMetaData": { "internalLocationRef": "Example", "internalId": 99 } } ``` 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", }, } ``` ::: *** ## Wallet Payment Scenarios (Negative Flow) :::hint{type="warning"} **Decline scenarios** for wallet payments cannot be tested in the 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 Limited test coverage is possible in the sandbox environment. The suggested negative test scenarios refer to model and processing error codes and information on why the transaction request failed Judopay's validation checks, which are similar to card payment scenarios. | **Suggested Negative Test Scenario** | **Expected Error Code** | **Error Description** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Attempt to perform a wallet payment / preAuth request 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](docId:_zrsihomUEW-XnRQ4PBtJ). | | Attempt to perform a wallet payment / preAuth 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. | :::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). *** ### Next Steps Using the response information from a successful wallet payment test transaction, you can test the following scenarios. Directly call the Transaction API to make a: - [Collection](docId\:yVjgZT2gxWBDxm3m0wEmu) - [Refund](docId\:mEbkvLfMxdP3kOlys0uDa) - [Void](docId\:DMBAKsKJll551SuxQIPuM)