---
title: Payment Request
slug: payment-request
docTags:
createdAt: 2024-08-19T13:11:09.058Z
---
# Creating a Payment / PreAuth Request with the Web SDK
:::hint{type="info"}
When authorising `/payments` or `/preauths` it is recommended to use **paymentSession**.
:::
### Prerequisites
:::hint{type="info"}
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](docId:40dWE6LBub7vdKza1QYDC)
- You do not need to include the amount or currency fields in your request body.
:::hint{type="warning"}
Merchants operating in specific money movement and financial services categories, as defined by the card schemes **must include** additional data in the [payment session](docId\:ylKW5coh5NQnfQ3j_Wjk2).
For more information, see [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg).
:::
- [Step Two: Add the Payment Form to your Website](docId:40dWE6LBub7vdKza1QYDC)
***
## Step One: Making a Transaction
To make a transaction:
1. Define the** paymentConfiguration** object for the payment or preAuth:
:::hint{type="warning"}
Ensure the details used when creating the **paymentSession** match the values set in the following configuration:
:::
:::CodeblockTabs
Payment Configuration Object Example
```javascript
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: "contact@judopay.com",
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:
:::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 |
| `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](docId\:XZE369mFK5UVOSaNzM8UO) 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 `invokePayment`call.
This will invoke a payment using the **paymentSession **and **paymentConfiguration**
:::CodeblockTabs
Invoke Payment Example
```javascript
function handlePaymentButtonClick() {
judo.invokePayment(paymentSession, paymentConfiguration)
.then(handleSuccess)
.catch(handleError)
}
```
:::
:::hint{type="info"}
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 `onclick`attribute to the payment 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](docId\:bcXNM5keOk-nlNrZTafUT).
- 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](docId\:qfxaWPAQl_-2EVfP8y94d).
- The consumer should be redirected to an Error Page.
:::CodeblockTabs
Response Example
```json
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](docId:_zrsihomUEW-XnRQ4PBtJ).