Payment Request

Creating a Payment / PreAuth Request with the Web SDK

When authorising /payments or /preauths it is recommended to use paymentSession.

Prerequisites

Make sure you are using Web SDK Version 0.0.34 (or higher).

From the Web SDK integration guide, you have completed the following:

Step One: Create a paymentSession

You do not need to include the amount or currency fields in your request body.

Merchants operating in specific money movement and financial services categories, as defined by the card schemes must include additional data in the payment sessionpayment session. For more information, see Account Funding Transactions.

Step Two: Add the Payment Form to your Website

Step One: Making a Transaction

To make a transaction:

Define the paymentConfiguration object for the payment or preAuth:

Ensure the details used when creating the paymentSession match the values set in the following configuration:

const paymentConfiguration = {
    judoId: "yourJudoId",
    amount: 1.01,
    currency: "GBP",
    phoneCountryCode: "44",
    challengeRequestIndicator: "challengeAsMandate",
    initialRecurringPayment: false,
    yourConsumerReference: "yourConsumerReference",
    yourPaymentReference: "yourPaymentReference",
    billingAddress: {
        address1: "My house",
        address2: "My street",
        town: "My town",
        state: "My state", //Mandatory for US and Canada
        postCode: "TR14 8PA",
        country: "826"
    },
    mobileNumber: "07999999999",
    emailAddress: "[email protected]",
    primaryAccountDetails: {
        name: "Doe",
        accountNumber: "9999999",
        dateOfBirth: "1989-09-19",
        postCode: "AB1 2CD"
    }
}

Web SDK Payment Parameter Descriptions

See below for more details on the parameters that create the paymentConfiguration object:

*Mastercard Recommends: These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied. See, Mastercard Recommended 3D Secure 2 Fieldsdd.

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
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.
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
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.
cardHolderName String Recommended *	The card name of the consumer. If the cardHolderName field is displayed to the user in the payment form (isCardHolderNameVisible: true is set in the iFrame config), the value entered in the payment form will overwrite this value.
challengeRequestIndicator String Optional	Indicates the type of challenge request you wish to apply. Set this to one of the following strings: noPreference noChallenge No challenge required. challengePreferred A challenge is preferred for this transaction. challengeAsMandate Must challenge this transaction. This should not be included in the same configuration object as scaExemption.
scaExemption String Optional	To apply for an exemption from SCA, for a customer initiated transaction. Set this to one of the following strings: 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. This should not be included in the same configuration object as challengeRequestIndicator.
initialRecurringPayment Boolean Optional	Indicates if this initial payment is part of a recurring payment.
billingAddress Object Optional	Card holder's billing address. Properties: address1 (Recommended)* address2 (optional) town state (only required if country is USA/Canada) Format: string ISO Alpha-2 Code (e.g. California = "CA") country Format: string See here for the list of valid ISO 3166-1 format country codes. postCode 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.
primaryAccountDetails Object Optional	This is Mandatory for merchants who have an MCC code of 6012, 6051 and 7299. Properties: name This is the surname. accountNumber postCode dateOfBirth Format: YYYY-MM-DD

2. In a function, add the invokePaymentcall. This will invoke a payment using the paymentSession and paymentConfiguration

function handlePaymentButtonClick() {
    judo.invokePayment(paymentSession, paymentConfiguration)
    .then(handleSuccess)
    .catch(handleError)
}

To invoke a preAuth, change the above code to .invokePreauth

3. To call the function (in step 2 above) to invoke the payment or preAuth, add the onclickattribute to the payment button <div>: <button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>

Step Two: Handle the Response

All the Judopay Web SDK transaction methods return a promise. Once the authorisation is complete, the promise will be either fulfilled or rejected.

Fulfilled

You will receive a JSON object response (a Judopay receipt object).
- For more information and schema on the JSON object, see API Transaction Response.
Depending on the result the consumer should be redirected to the appropriate outcome page.
- For example, if the result = SUCCESS redirect the consumer to the Success Page.
This page should display the necessary transaction information (found in the Judopay receipt object).

Rejected

You will receive an error object
- For more information on error responses returned, see Web SDK Error Responses.
The consumer should be redirected to an Error Page.

const onFulfillment = (receiptObject) => {
  const { result } = receiptObject
  //redirect to appropriate page depending on the result (success/failure/declined page)
}

const onRejection = (error) => {
  //redirect to error page and handle error
}

For more information on the response codes, see Codes.