This guide outlines all the steps that are required to add Click-To-Pay to your gateway integration using the Click-To-Pay JavaScript (JS) API.
This section describes a simple integration for Hosted Session to collect payer's credit card details and configure Click-To-Pay.
<html>
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://ap-gateway.mastercard.com/form/version/72/merchant/<Merchant ID>/session.js"></script>
<!-- INCLUDE CLICK-TO-PAY.MIN.JS JAVASCRIPT LIBRARY -->
<script type="text/javascript" src="https://test-gateway.mastercard.com/static/click-to-pay/click-to-pay.min.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>
<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
<div>Please enter your payment details:</div>
<h3>Credit Card</h3>
<div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div>
<div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="2" readonly></div>
<div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="3" readonly></div>
<div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div>
<div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div>
<div><button id="payButton" onclick="pay('card');">Pay Now</button></div>
<!-- CREATE THE HTML FOR THE CLICK-TO-PAY INTERACTION -->
<div>C2P Fields Below------</div>
Email: <input id="payerEmail" onblur="updateEmail();" /><br/>
<div id="cardListContainer" ></div><br/>
<div id="otpContainer"></div><br/>
<div id="cardFacilitator" ></div><br/>
<div id="coid" ></div><br/>
<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
PaymentSession.configure({
session: "<your_session_ID>",
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD
card: {
number: "#card-number",
securityCode: "#security-code",
expiryMonth: "#expiry-month",
expiryYear: "#expiry-year",
nameOnCard: "#cardholder-name"
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
console.log('initialized: ' + response)
if(response.status === 'ok') {
//configure C2P
configure()
}
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
//check if the security code was provided by the user
if (response.sourceOfFunds.provided.card.securityCode) {
console.log("Security code was provided.");
}
//check if the user entered a Mastercard credit card
if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') {
console.log("The user entered a Mastercard credit card.")
}
ClickToPay.isEnrollmentAvailableForScheme(response.sourceOfFunds.provided.card.scheme, function (canEnroll) {
console.log('Card can be enrolled', canEnroll)
if(canEnroll) {
ClickToPay.checkoutWithNewCard();
}
});
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.cardNumber) {
console.log("Card number invalid or missing.");
}
if (response.errors.expiryYear) {
console.log("Expiry year invalid or missing.");
}
if (response.errors.expiryMonth) {
console.log("Expiry month invalid or missing.");
}
if (response.errors.securityCode) {
console.log("Security code invalid.");
}
} else if ("request_timeout" == response.status) {
console.log("Session update failed with request timeout: " + response.errors.message);
} else if ("system_error" == response.status) {
console.log("Session update failed with system error: " + response.errors.message);
}
} else {
console.log("Session update failed: " + response);
}
}
},
interaction: {
displayControl: {
formatCard: "EMBOSSED",
invalidFieldCharacters: "REJECT"
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
</script>
<script type="text/javascript">
var payloadCallback = function (correlationId, scheme) {
console.log('Payload callback complete with correlation id %s and scheme %s', correlationId, scheme);
};
var errorCallback = function (error) {
console.log('Error callback triggered with error ' + error);
console.log(error);
};
var cancelCallback = function () {
console.log('Cancel callback triggered');
};
function configure() {
ClickToPay.configure({
merchant: {
id: "<your_gateway_merchant_ID>",
name: "<your_gateway_name>",
url: "<your_website_URL>"
},
session: {
id: "<your_session_ID>",
wsVersion: <api_version>
},
order: {
amount: <amount>,
currency: "<currency>"
},
interaction: {
//Billing preference with one of the following values: NONE, FULL, POSTAL_COUNTRY
billingPreference: "FULL",
collectShippingAddress: true,
locale: "<locale>",
country: "<country code>"
},
customer: {
email: "<payers_email_address>"//optional
},
elements: {
cardList: "cardListContainer",
otp: "otpContainer", // optional
dcf: "cardFacilitator"
},
callbacks: {
onComplete: function(correlationId, scheme) {
console.log("onComplete fired");
console.log("Correlation ID: " + correlationId);
console.log("Scheme: " + scheme);
document.getElementById("coid").innerHTML = 'Correlation ID: ' + correlationId + ', Scheme: ' + scheme
},
onStateChange: function(changeInfo) {
console.log("onStateChange fired");
console.log(changeInfo);
},
onError: function(errInfo) {
console.log("onError fired");
console.log(errInfo);
}
}
});
}
function updateEmail() {
ClickToPay.lookupCustomer(document.getElementById("payerEmail").value);
}
</script>
</body>
</html>
You can create a session using the Create Session call. This is a server-side API call and is a prerequisite for integrating with the JS API. Use API version 62 or above. The response returns a session ID that you must use in the subsequent steps to reference this session.
You can add or update fields in a session using the Update Session call. The following fields are required in a session:
| Parameter | Existance | Description |
|---|---|---|
session.id |
Required | The identifier of the payment session. |
order.amount |
Required | The total amount of the order. |
order.currency |
Required | The currency of the order. |
Include the Click to Pay JavaScript SDK (click-to-pay.js) provided by the gateway in your payment page by adding a script element within the head element. This places an ClickToPay object into the window namespace.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/static/click-to-pay/click-to-pay.min.js"></script>
The configuration object allows you to configure the payment interaction. When loading your payment page, initiate the Click to Pay interaction by invoking the ClickToPay.configure() method. For additional information on Hosted Session integration, please see the Hosted Session integration page.
The Click to Pay library may take a few seconds to initialize. You should initialize the components as early as possible during the page load so that the payer can quickly checkout using Click to Pay.For additional details such as example and usage, please see the relevant API Reference section.
| Field | Required | Type | Description |
|---|---|---|---|
merchant.id |
Yes | string | It is required so that the gateway can correctly determine your payment options. |
merchant.name |
Yes | string | It provides your trading name, for example, the name known to your payer. |
merchant.url |
Required | URL string | It provides the URL of your website that the payer is using. |
| Field | Required | Type | Description |
|---|---|---|---|
session.id |
Yes | string | It provides the session identifier returned from Step 1 Create Session operation. |
session.wsVersion |
Yes | int | Value must be >= 62. This is the version you used when submitting the Create Session operation in step 1. |
| Field | Required | Type | Description |
|---|---|---|---|
order.amount |
Yes | string | The value you provide in this method is used for display only and is not used for processing the payment |
order.currency |
Yes | string | The value you provide in this method is used for display only and is not used for processing the payment |
| Field | Required | Type | Description |
|---|---|---|---|
interaction.billingPreference |
No | enumeration string | Set billingPreference whether billing address is collected during the Click to Pay interaction. Values
|
interation.collectShippingAddress |
No | boolean | By default, Click to Pay will not collect the payer's shipping address. If you want Click to Pay to collect the payer's shipping address, set collectShippingAddress:true. By default, the payer can select any shipping address country. To restrict the list of country that you ship goods to, you must configure your merchant profile for SRC via Merchant Administration with either a list of allowed countries or a list of excepted countries. Where you have defined any restrictions, the payer will only be able to select an allowed shipping address country. You cannot override the supported shipping address countries for a specific request. |
interation.locale |
No | string | The interaction locale determines the language used during the Click to Pay interaction. By default, the language configured in the payer's browser is used. If the payer's language cannot be determined or is not supported, en_US is used. If you want to override this value for this interaction, add the interaction.locale field to the ClickToPay.configure() method. |
interation.country |
No | string | The interaction country determines country-specific content presented to the payer during the Click to Pay interaction such as Terms and Conditions. The value you have configured against your merchant profile in the gateway is used by default. If you want to override this value for this interaction, add the interaction.country field to the ClickToPay.configure() method and set to valid ISO 3166 alpha-3 Country value, |
interaction.cardSelectionAction |
No | string | Allows you to choose what action is performed when the payer makes the card selection SELECT_ONLY. By default, the selection is SELECT_AND_PROCEED. UI will display the list of cards using radio buttons. Selecting a radio button will not trigger any action. The payer needs to click the "Continue" button to continue to the next step. UI will display the list of cards where each card entry is clickable. Selecting an entry will automatically take the payer to the next step. |
interaction.skipDCFInteraction |
No | Boolean | Allows you to remove the requirement for the payer to manually confirm their email address and phone number. This only applies to Mastercard card enrollment at this time. The customer.email and customer.mobilePhone parameters are required within the configure() method for this function to take effect. If set to true, the payer is not prompted with a Confirm message on the DCF. A brief loading screen will appear. If not provided, the value defaults to false. This functionality is available after release 23.2. |
| Field | Required | Type | Description |
|---|---|---|---|
customer.email |
Yes | String | Include the payer's email in field customer.email so that Click to Pay can lookup payer's profile within SRC system. This email lookup will be initiated only if the device is not recognized. If the device is recognized then this field will be ignored. Include information on your site that the payer’s email is used for the lookup purpose, unless you already informed the payer that their email address is used for looking up their Click to Pay profile. You may include a notice informing that you partner with participating card schemes to deliver Click to Pay for faster checkout and that their email address is securely shared with participating card schemes to check if the payer already has a Click to Pay profile. |
customer.mobilePhone |
No | telephone number | The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678 The number consists of:
|
customer.firstName |
No | String | The payer's first name. |
customer.lastName |
No | String | The payer's last or surname. |
| Event | Required | Description |
|---|---|---|
srcDCFCancel |
If you intend to support Visa cards – Yes If you do not intend to support Visa cards - No |
Visa’s current design for Click to Pay closes it’s Click to Pay session if the payer selects the “X” displayed in the top right corner of the Visa DCF. When this event is sent, it is recommended that you reinitialize Click to Pay to ensure open sessions for all card schemes. |
Click to Pay provides several components used to embed the Click to Pay experience in your payment page. Create div elements at the location in your payment page you want these components displayed and identify these div elements in the ClickToPay.configure() method. The elements are:
| Field | Required | Description |
|---|---|---|
cardList |
Yes | dom element id where you would like to display the Card List component. |
otp |
No | dom element id where you would like to display One Time Password component. if not provided, one time password (OTP) will be displayed as an overlay. |
dcf |
Yes | dom element id where you would like to display the Digital Card Facilitator component. This is used by the scheme to interact with the payer. |
You must define the actions to be invoked during the Click to Pay experience.
The SDK will determine the initial flow after you call configure method().
This callback is triggered when the Click to Pay experience state changes. You can use this to determine which component is visible and what stage the payer is in the flow.
| Example onStateChange Callback object |
|---|
oldState : {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email if not supplied in customer.email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: true},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: false}
}
},
newState: {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: false},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: true}
}
},
diffState: {
elementState: {
dcf: {selector:'dcfContainer', visible: true}
}
} |
| State | Old State field value | New State field value | Comments |
|---|---|---|---|
| Page load (before cardlist is displayed) after isRecognized and before cardList is displayed | {} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
- |
| after card is clicked and before redirecting to DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| after checkout is complete | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
onComplete callback returns correlationId, scheme, digitalCardId. Goto step 6 |
| State | Old State field value | New State field value | Comments |
|---|---|---|---|
| after valid OTP is entered | {
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: true},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
- |
| after card is clicked before redirecting to DCF | {
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| after checkout is complete | {
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrollled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
onComplete callback return correlationId, scheme, digitalCardId Goto step 6 |
| State | Old State field value | New State field value | Comments |
|---|---|---|---|
| Page load with email | {
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
Since the payer's Click to Pay profile isn't recognized, you can display card input. The email will be blank if not provided in configure. |
| call enrollUnencrypted method before DCF is displayed | {
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| after checkout is complete | {
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
onComplete callback return correlationId, scheme, digitalCardId Goto step 6 |
Callback function to be triggered when the payer has completed the interaction with the DCF component.
This function uses two arguments, correlationId and scheme
These details must subsequently be used to retrieve the payment details for this Click to Pay interaction in Step 6 Update Session with SRC Payment Details below.
This callback returns an error object if an error occurred during Click to Pay experience. It contains two fields, errorCode and errorMessage.
for example: { errorCode: 'INVALID_INPUT', errorMessage: 'session id is required' }
| Error Code | Error Message | Your Action |
|---|---|---|
CALLBACKS_ONCOMPLETE_ERROR |
Missing Argument: onComplete callback is required | Include the onComplete callback method in the configure method. |
CALLBACKS_ONERROR_ERROR |
Missing Argument: onError callback is required | Include the onError callback method in the configure method. |
MERCHANT_ID_ERROR |
Missing Argument: Merchant ID is required | Include the merchant.id field in the configure method. |
MERCHANT_NAME_ERROR |
Missing Argument: Merchant Name is required | Include the merchant.name field in the configure method. |
MERCHANT_URL_ERROR |
Missing Argument: Merchant URL is required | Include the merchant.url field in the configure method. |
SESSION_ID_ERROR |
Missing Argument: Session Id is required | Include the session.id field in the configure method. |
MISSING_API_VERSION_ERROR |
Missing Argument: API Version is required | Include wsVersion field in the configure method. |
ORDER_AMOUNT_ERROR |
Missing Argument: Order Amount is required | Include order.amount field in the configure method. |
ORDER_CURRENCY_ERROR |
Missing Argument: Order currency is required | Include order.currency field in the configure method. |
MIN_API_VERSION_ERROR |
API version should be greater than or equal to 62 | Change the wsVersion field value to at least 62, all operations must be made using 62 or higher. |
CARD_LIST_ERROR |
Missing Argument: Elements.cardList is required | Include the elements.cardList field that links to the card list component div |
DCF_ERROR |
Missing Argument: Elements.dcf is required | Include the elements.dcf field that links to the card list component div |
MISSING_EMAIL_ERROR |
Missing Argument: email is required | Include customer.email field in the configure method. |
CUSTOMER_EMAIL_ERROR |
Customer email format error | Ensure only valid payer email addresses are accepted by your site. |
INTERACTION_LOCALE_ERROR |
Interaction locale format error | Provide a valid locale using format eg en_US. |
INTERACTION_COUNTRY_ERROR |
Interaction country format error | Provide a valid ISO 3166 alpha-3 Country value in field interaction.country. |
| Error Code | Error Message | Your Action |
|---|---|---|
CARD_MISSING |
The digital card ID or encrypted card object was required but is missing | Click to Pay is unavailable, revert to guest checkout flow. |
CARD_ADD_FAILED |
Unable to add card when combined flow executed | Click to Pay is unavailable, revert to guest checkout flow. |
CARD_SECURITY_CODE_MISSING |
Card security must be supplied when combined flow executed | Ensure the cardSecurityCode field in method C2P.enroll() is contains a 3 digit value or 4 digit for Amex. |
CARD_INVALID |
Invalid card number when combined flow executed | Ensure the primaryAccountNumber field in method C2P.enroll() is a valid card |
CARD_NOT_RECOGNIZED |
The specified card was not recognized | Ensure the primaryAccountNumber field in method C2P.enroll() is a valid card |
CARD_EXP_INVALID |
Invalid card expiry date | Ensure the panExpirationYear and panExpirationMonth field in method C2P.enroll() is a valid |
MERCHANT_DATA_INVALID |
Merchant data is invalid | Click to Pay is unavailable, revert to guest checkout flow. |
UNABLE_TO_CONNECT |
Unable to connect to / Launch DCF | Click to Pay is unavailable, revert to guest checkout flow. |
AUTH_INVALID |
Invalid federated ID token | Click to Pay is unavailable, revert to guest checkout flow. |
| Error Code | Error Message | Your Action |
|---|---|---|
REQUEST_TIMEOUT |
The request took longer than the permitted time to complete. This could mean the service is experiencing a high volume of calls. You should try again later. It may also be because the SDK is unable to communicate with its iFrame | Click to Pay is unavailable, revert to guest checkout flow. |
SERVER_ERROR |
This indicates that the server encountered an unexpected condition that prevented it from fulfilling the request | Click to Pay is unavailable, revert to guest checkout flow. |
INVALID_PARAMETER |
The value provided for one or more request parameters is considered invalid. This error is also generated when a required field is missing. Note: Whenever possible you should provide client side validation to avoid an unnecessary round trip to the server. Simple validation constraints are documented as part of the API specification | Click to Pay is unavailable, revert to guest checkout flow. |
INVALID_REQUEST |
The server could not understand the request. Usually this means a data field must be in a particular format, but is not. For example, base64 decoding may have failed. The message field may provide additional clarification of what part/field of the request is considered incorrect | Click to Pay is unavailable, revert to guest checkout flow. |
AUTH_ERROR |
The server does understand the request, but cannot authenticate | Click to Pay is unavailable, revert to guest checkout flow. |
NOT_FOUND |
The requested resource/business entity does not exist. The resource might also be hidden for security reasons | Click to Pay is unavailable, revert to guest checkout flow. |
TERMS_AND_CONDITIONS_NOT_ACCEPTED |
Terms and Conditions not accepted | Revert to guest checkout flow |
IS_CONFIGURED_ERROR |
configure() did not complete. Configuration should be initialized first | Ensure your integration called configure method(). Ensure you allow sufficient time for the configure method to complete before making the Click to Pay components visible. |
SRCI_ID_MISSING |
The identifier for the SRC Initiator is missing | Click to Pay is unavailable, revert to guest checkout flow. |
DPA_ID_MISSING |
The identifier for the DPA is missing | Click to Pay is unavailable, revert to guest checkout flow. |
SRCI_TXID_MISSING |
The SRC Initiator transaction identifier is missing | Click to Pay is unavailable, revert to guest checkout flow. |
DPA_TXOPT_MISSING |
The DPA Transaction Options structure is missing | Click to Pay is unavailable, revert to guest checkout flow. |
INVALID_STATE |
The account exists but is not in an “active” status for this program | Revert to guest checkout flow |
CONSUMER_ID_MISSING |
The consumer identity was required but not supplied | Revert to guest checkout flow |
FRAUD |
The user account was locked or disabled | Revert to guest checkout flow |
ID_FORMAT_UNSUPPORTED |
Invalid session ID | Click to Pay is unavailable, revert to guest checkout flow. |
If a payer is recognized by Click to Pay based on their email, the default behavior for the click-to-pay.js is to automatically show the OTP provided by Click to Pay.
In some cases, a merchant may want to initiate the Click to Pay interaction but suppress the OTP provided by Click to Pay until a later time. This is possible by adding the interaction.suppressPayerInteraction field in the ClickToPay.configure() method.
| Field | Type | Description |
|---|---|---|
interaction.suppressPayerInteraction |
Boolean | Allows you to suppress the Click to Pay interaction with the payer (i.e. the display of any screens) as part of the configure() method. If set to true, the configure() method will set up the Click to Pay interaction and check if the payer is recognized using their email or a cookie or is a new user. However, the method will not trigger the Click to Pay interaction with the payer. This allows you to display any additional screens to the payer before they proceed to the Click to Pay interaction. To subsequently trigger the Click to Pay interaction you need to use the initiatePayerInteraction() function. If set to false, the configure() method will set up the Click to Pay interaction, check if the payer is recognized using their email or a cookie or is a new user, as well as trigger the Click to Pay interaction with the payer. If not provided, the value defaults to false. |
If the payer was:
| InitiatePayerInteraction() | Type | Description |
|---|---|---|
interaction.suppressPayerInteraction |
Boolean | Use this function to trigger the Click to Pay interaction with the payer. The configure() method will by default (or if interaction.suppressPayerInteraction=false) immediately trigger the Click to Pay interaction with the payer. However, if you call configure() with interaction.suppressPayerInteraction = true then the configure() function will only set up the Click to Pay interaction and check if the payer is recognized. This allows you to display any additional screens to the payer before allowing them to proceed to the Click to Pay interaction. This method must only be called by the merchant when the merchant has used the optional parameter suppressPayerInteraction in the configure() method.
|
If the payer can change their email address on the same page as the Click to Pay components, then any changes to the payer email address will need to be pushed to the Click to Pay SDK. Every time the payer updates their email address, call the lookupCustomer(email) method to update the Click to Pay SDK. The payer email is used to lookup whether this payer has an existing Click to Pay profile associated with their email address.
If you collect email address from the payer on your site, include information that the payer’s email is used for looking up their Click to Pay profile. You may include a tooltip next to the email input box informing the payer that 'you partner with the participating card schemes to deliver Click to Pay for faster checkout and that email is securely shared with participating card schemes to check if payer already has a Click to Pay profile'.
If the updated email address is:
The payer may enroll a new card into their Click to Pay profile, or if payer does not have a profile, a new one will be created. Your application needs to retrieve the scheme from hosted session using onCardTypeChange callback and then call isEnrollmentAvailableForScheme() with the retrieved scheme.
When the payer clicks the button on your payment page to progress to the next stage:
| Function |
|---|
checkoutWithNewCard()
Once the payer is ready to checkout with the new card, you will call the checkoutWithNewCard method. This function will take the payer to the DCF card enrollment screen. |
isEnrollmentAvailableForScheme()
Once the merchant application has displayed a card input form (because the email of the payer is not enrolled in Click to Pay) and the payer has clicked the 'Pay' button, the merchant application must call this function. This function checks the supplied scheme against paymentTypes.card.walletProviders[n].secureRemoteCommerce.scheme[n].name in the PAYMENT_OPTIONS_INQUIRY response to determine if the merchant is enabled for the scheme. |
isEnrollmentAvailableForCardPrefix()
Once the merchant application has displayed a card input form (because the email of the payer is not enrolled in Click to Pay) and the payer has clicked the 'Pay' button, the merchant application must call this function. The function allows the merchant application to determine if they should subsequently offer the payer to enroll the card in Click to Pay. |
The payer may choose to checkout using an existing card from their Click to Pay profile. Once the payer selects the card from the card list, then you call checkoutWithExistingCard()which will take the payer to the card confirmation screen in DCF.
You must request the gateway to retrieve the payment details for the Click to Pay interaction and store them in the session, after your payer has successfully completed the Click to Pay interaction.
Submit an Update Session From Wallet request with:
If the session has successfully been updated with the payment details from the Click to Pay interaction, you should display a payment confirmation screen to confirm all details are correct before the payer commits to payment. If the session has not been successfully updated, ask your payer to select another checkout option.
| Example |
|---|
URL: "https://ap-gateway.mastercard.com/form/version/72/merchant/<your_merchant_ID>/session/<your_session_ID>
HTTP Method POST
{
"apiOperation":"UPDATE_SESSION_FROM_WALLET",
"order":{
"walletProvider":"SECURE_REMOTE_COMMERCE"
},
"wallet":{
"secureRemoteCommerce":{
"srcCorrelationId":"<correlationId_provided_in_payloadCallback>,
"scheme":"<scheme_provided_in_payloadCallback>"
}
}
}
|
If you want to authenticate the payer, perform 3-D Secure Authentication using the session. See Implementing a 3DS Integration using the 3DS JavaScript API for details.
If the session is successfully updated with the payment details from the Click to Pay interaction (and the 3-D Secure Authentication, if performed in step 7), use the session to submit the payment for processing from your server-side application. For example, you can submit an Authorize request. The payment details stored in the session from the Click to Pay interaction are used to process the payment. You can use the session for a number of API operations; see Use a Session for more information.
For Guest checkout non Click to Pay flows, the session will not contain the card number and you will need to provide the card data in the API directly.
URL: "https://ap-gateway.mastercard.com/form/version/72/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID>
HTTP Method PUT
{
"session":{
"id":"<session_ID>"
}
}
Before going live, you must test your integration to ensure correct functionality.
For general FAQs about Click To Pay, see Click to Pay FAQs.
Copyright © 2023 MasterCard