Secure Remote Commerce
Secure Remote Commerce (SRC) is an intelligent, password-free online checkout option that provides a quick and easy checkout experience for payers. SRC provides a single checkout button (also referred to as 'Click to Pay') and a standardized checkout flow for all participating card schemes, including Mastercard, Visa, American Express, Discover and others. SRC is built off EMVCo's SRC specification and replaces Masterpass, Visa Checkout and Amex Express Checkout.
A payer can create an SRC profile using their email address. During checkout, the payer must then provide this email address and perform an additional verification step with a one time code. They can also choose the "Remember me" option to subsequently skip the verification when using the same browser.
The payer can store multiple credit, debit or prepaid cards, the associated billing addresses, and multiple shipping addresses in their SRC profile. Card details are securely stored, and additional security is provided by offering network tokenization.
SRC allows your payer to select the payment details to be used for the payment; however, the payment itself is processed using the acquirer configured for your merchant profile in the gateway.
SRC is supported on the gateway's payment page (Hosted Checkout), or through a JavaScript SDK if you are using your own payment page.
Key benefits
SRC offers the following benefits:
- Fast, easy-to-use checkout option for your payers with reduced risk of checkout abandonment
- Higher authorization approval rates if you use network tokens
- Decreased payer fraud
- Secure exchange of payment data including card details, billing and shipping address details
Prerequisites
If you want to offer SRC as a checkout option to your payers:
- Contact your payment service provider to ensure that SRC is available to you.
- From the Admin menu in Merchant Administration, click SRC Configuration and follow the instructions to onboard to SRC and activate SRC for your merchant profile. You must have the required privilege to update your SRC configuration.
SRC as a checkout option in Hosted Checkout
If you are using the gateway's payment page (Hosted Checkout), SRC will automatically be offered as a checkout option to your payers if you have activated SRC for your merchant profile, and are using API version 57 or higher when submitting the Create Checkout Session request to initiate the Hosted Checkout interaction.
While your payer's SRC profile itself can contain cards for any supported card schemes, for a given transaction your payer can only use SRC for those cards where:
- the card scheme has been activated for SRC on your merchant profile, and
- your merchant profile is configured to process cards with this scheme and the transaction currency.
Shipping Address: Payers will not be able to select a shipping address during the SRC interaction, as shipping address collection is not currently supported via Hosted Checkout.
Billing Address: A billing address will always be collected during the SRC interaction.
3-D Secure Authentication: If you are configured for 3-D Secure (3DS) Authentication, Hosted Checkout will automatically perform the 3DS authentication after the SRC interaction.
To use Hosted Checkout, follow the steps as defined under Implementing a Hosted Checkout Integration.
When calling Checkout.configure(), include the following details:
| Interaction Country | For an SRC interaction, the interaction country determines country-specific content presented to the payer during the SRC interaction such as Terms and Conditions. The value you have configured against your merchant profile in the gateway is used by default. Add the interaction.country field to the Checkout.configure() method, if you want to override this value for this interaction. |
| Interaction Locale | For an SRC interaction, the interaction locale determines the display language. 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, add the interaction.locale field to the Checkout.configure() method. Currently, the supported languages are English (UK) (en_UK), Spanish (Spain) (es_ES), French (Canada) (fr_CA), Portuguese (Brazil) (pt_BR), and Chinese (Hong Kong) (zh_HK). |
| Merchant Name | Provide your trading name, i.e., the name known to your payer. The name may be displayed during the SRC interaction. |
| Merchant URL | Provide the URL of your website that the payer is using. For example, https://example.com. The URL may be displayed during the SRC interaction. |
| Payer Email | The payer's email address will always be collected during the SRC interaction. If you already know the payer's email address, add customer.email:<your payer's email address> to the Checkout.configure() to allow the payer to bypass entering their email address during the SRC interaction. |
<html>
<head>
<script src="https://na.gateway.spring.citi.com/static/srci/1.2.0/srci.min.js"
data-error="errorCallback"
data-cancel="cancelCallback"></script>
<script type="text/javascript">
function errorCallback(error) {
console.log(JSON.stringify(error));
}
function cancelCallback() {
console.log('Payment cancelled');
}
Checkout.configure({
merchant: "<gateway_merchant_ID>",
session: {
id: "<session_ID>",
},
customer: {
email: "<payer_email_address>"
},
order: {
amount: "60",
currency: "USD",
description: "High level description of the goods contained in the order",
id: "<your_unique_order_ID>",
},
interaction: {
country: "USA",
locale: "en_US",
operation: "AUTHORIZE",
merchant: {
name: "<merchant_name>",
url: "<website_URL>",
address: {
line1: "200 Sample St",
line2: "1234 Example Town"
}
}
}
});
</script>
</head>
<body>
...
<input
type="button"
value="Pay with Lightbox"
onclick="Checkout.showLightbox();"
/>
<input
type="button"
value="Pay with Payment Page"
onclick="Checkout.showPaymentPage();"
/>
...
</body>
</html>
SRC as a checkout option on your payment page
If you are using your own payment page and want to offer SRC as a checkout option to your payers, use the SRCI JavaScript SDK (srci.js) provided by the gateway.
This is a client-side JavaScript integration that allows you to initiate the SRC interaction directly from the payer's browser, and it ensures that the payment details selected by the payer during the SRC interaction are directly submitted from the payer's browser to the gateway.
To use the SRCI JavaScript SDK, follow the steps below.
Step 1: Create a Session
Create a session by submitting a Create Session request from your server-side application. The response returns a session ID that you must use in the subsequent steps to reference this session.
Step 2: Update the Session with the Order Amount and Currency
Update the session with the amount and currency for the order by submitting a Update Session request from your server-side application. This step is required to subsequently inquire about SRC being available for payments with this currency.
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/merchant/<your_merchant_ID>/session/<your_session_ID> |
| HTTP Method | PUT |
{
"order":{
"amount":100.00,
"currency":"USD"
}
}
Step 3: Include the SRCI JavaScript SDK in your Payment Page
Include the SRCI JavaScript SDK (srci.js) provided by the gateway in your payment page by adding a script element within the head element. This places an SRCi object into the window namespace.
<script type="text/javascript" src="https://na.gateway.spring.citi.com/static/srci/1.2.0/srci.min.js"></script>
Step 4: Configure the SRC Interaction
When loading your payment page, initiate the SRC interaction by invoking the SRCi.configure() method.
<html>
<head>
<script type="text/javascript" src="https://na.gateway.spring.citi.com/static/srci/1.2.0/srci.min.js"></script>
<script type="text/javascript">
var callback = function (response) {
if(response.result === "SUCCESS") {
console.log("Response from SDK: %s", response.restApiResponse);
} else if(response.result === "ERROR") {
console.log("An error occurred");
}
}
SRCi.configure(
"<your_gateway_merchant_ID>",
"<your_merchant_name>",
"<your_merchant_URL>",
"<your_session_ID>",
{ wsVersion: 57 },
callback
);
</script>
</head>
<body>
...
</body>
</html>
Merchant Details
The merchantId is required so that the gateway can correctly determine your payment options.
The merchantName and merchantUrl fields are submitted to the SRC Server. These details may be displayed to the payer during the SRC interaction.
Provide your trading name, i.e., the name known to your payer and the URL of your website that the payer is using.
Version
Set this value to 57. This is the version you used when submitting the Create Session request.
Callback
Use the callback parameter to define the actions to be invoked after SRCi.configure() has completed. For example, you may want to log if the method was successful:
var srciConfigCallback = function (resp) {
var response = resp.restApiResponse;
if (response.result === "ERROR") {
console.error("SRC could not successfully be configured");
} else if (response.result === "SUCCESS") {
console.log("SRC was successfully configured");
}
}
The SRCi.configure() call might return the following error responses:
response.cause |
resp.explanation |
Required Action |
|---|---|---|
| Error | Missing argument: Merchant ID, Merchant Name, Merchant URL, Hosted Session ID, and a callback function are all required arguments for the configure() method. |
Fix your integration. You must provide all mandatory request fields |
| Error | Missing argument: Merchant URL is a required argument for the configure() method |
Fix your integration. You must provide the Merchant URL field. |
| Error | Callback must be a function. | Fix your integration. |
| Error | API version must be <MIN_VERSION> or greater. |
Fix your integration. Set wsVersion to 57. |
Where an error is returned, do not proceed to the next step. Offer the payer another payment method.
Advanced Configuration
The SDK retrieves details about your merchant profile configuration for SRC (including, for example, the list of all schemes for which SRC is available) using the Payment Options Inquiry operation. However, if you have already submitted a Payment Options Inquiry request earlier during the payer's session, you can pass these details in by adding the configuration element to the request.
In this case, the SDK does not perform the Payment Options Inquiry request again. The wsVersion parameter indicates the API version you have used to submit the Payment Options Inquiry request.
<html>
<head>
<script type="text/javascript" src="https://na.gateway.spring.citi.com/static/srci/1.2.0/srci.min.js"></script>
// Response from the Payment Options Inquiry call. This value to SRCi.configure() is optional. If it is not passed in, a call will be made from the SDK to the API to retrieve it.
var paymentOptionsInquiryResponse = {
merchant: "<gateway_merchant_ID>",
paymentTypes: {
card: {
cardTypes: [{
cardType: "MASTERCARD",
schemeTokenTypes: "CRYPTOGRAM_3DSECURE"
}, {
cardType: "VISA",
schemeTokenTypes: "CRYPTOGRAM_3DSECURE"
}, {
cardType: "AMEX",
schemeTokenTypes: "DYNAMIC_CSC_AND_EXPIRY"
}],
walletProviders: [{
secureRemoteCommerce: {
defaultPayerCountry: "USA",
shippingAddressCountries : "USA,CAN"
scheme: [{
dpaId: "<DPA_ID>", // As configured for this scheme on your merchant profile.
name: "MASTERCARD"
}, {
dpaId: "<DPA_ID>", // As configured for this scheme on your merchant profile.
name: "VISA"
}, {
name: "AMERICAN_EXPRESS"
}]
},
walletProvider: "SECURE_REMOTE_COMMERCE"
}]
}
},
result: "SUCCESS"
}
SRCi.configure({
"<gateway_merchant_ID>",
"<merchant_name>",
"<merchant_URL>",
"<session_ID>",
configuration: {
wsVersion: 57,
paymentOptions: paymentOptionsInquiryResponse
},
callback: function (response) {
if(response.result === "SUCCESS") {
console.log("Response from SDK: %s", response.restApiResponse);
} else if(response.result === "ERROR") {
console.log("An error occurred");
}
}
});
</script>
</head>
<body>
...
</body>
</html>
Example SRCi.configure() Response
The following example shows a successful SRCi.configure() call.
{
result: "SUCCESS"
restApiResponse: <Payments Options Inquiry response>
}
The response contains the Payments Options Inquiry response in the restApiResponse field, which is informational only. However, you may want to use this information later during the payer's session rather than using the PAYMENT_OPTIONS_INQUIRY request to retrieve it.
The following example shows an unsuccessful SRCi.configure() call.
{
result: "ERROR"
cause: <cause>
explanation: <explanation>
}
In this case, request the payer to select another checkout option.
Step 5: Display SRC as a Checkout Option
If SRCi.configure() was successful, display SRC as a checkout option on your payment page. For the branding requirements, see SRC User Interface Guidelines.
Use the SRC configuration details returned in the Payment Options Inquiry response to determine what scheme logos to display within the button. For each supported scheme, the Payment Options Inquiry response contains the name of the scheme in the paymentTypes.card.walletProviders[n].secureRemoteCommerce.scheme[n].name field.
Step 6: Launch the SRC UI
When the payer selects SRC as a checkout option, launch the SRC UI by invoking the SRCi.launchUI() method.
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: %s", error);
};
var cancelCallback = function () {
console.log("Cancel callback triggered");
};
SRCi.launchUI({
orderAmount: "100.00",
orderCurrency: "USD"
},
payloadCallback,
errorCallback,
cancelCallback
);
In addition to the mandatory fields, you can also provide a number of optional fields:
SRCi.launchUI(
{
"orderAmount":"60"
"orderCurrency":"USD",
"customerEmail":"<payer_email_address>",
"collectShippingAddress":true,
"interactionCountry":"CAN"
"interactionLocale":"fr"
}
);
Payer Email Address Collection
The payer's email address will always be collected during the SRC interaction. If you already know the payer's email address, add the customerEmail field to the SRCi.launchUI() method to allow the payer to bypass entering their email address during the SRC interaction.
Billing Address Collection
A billing address will always be collected during the SRC interaction.
Shipping Address Collection
By default, SRC will not collect the payer's shipping address. If you want SRC to collect the payer's shipping address, add collectShippingAddress:true to the SRCi.launchUI() method.
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.
Interaction Country
The interaction country determines country-specific content presented to the payer during the SRC interaction such as Terms and Conditions. The value you have configured against your merchant profile in the gateway is used by default. Add the interactionCountry field to the SRCi.launchUI() method, if you want to override this value for this interaction.
Interaction Locale
The interaction locale determines the language used during the SRC 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. Add the interactionLocale field to the SRCi.launchUI() method, if you want to override this value. Currently, the supported languages are English (UK) (en_UK), Spanish (Spain) (es_ES), French (Canada) (fr_CA), Portuguese (Brazil) (pt_BR), and Chinese (Hong Kong) (zh_HK).
Callback
You must define the actions to be invoked after SRCi.launchUI() has completed as follows:
payloadCallback |
Callback function to be triggered when the payer has completed the interaction in the SRC UI. This function uses two arguments, correlationId and scheme
These details must subsequently be used to retrieve the payment details for this SRC interaction (see step 7). |
|||||||||||||||||||||
errorCallback |
The callback function to be triggered if an error is encountered when loading the SRC UI. This function uses an argument that will be populated with an error object containing the error details.
|
|||||||||||||||||||||
cancelCallback |
The callback function to be triggered when the payer cancels the SRC interaction, or the SRC UI is closed. It does not use any arguments. |
Step 7: Update Session with SRC Payment Details
After your payer has successfully completed the SRC interaction, you must request the gateway to retrieve the payment details for the SRC interaction and store them in the session.
Submit an Update Session From Wallet request with:
- the session ID in the request URL, and
- the
correlationIdand scheme as returned in thepayloadCallback
| URL | https://na.gateway.spring.citi.com/api/rest/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 the session has successfully been updated with the payment details from the SRC interaction, you can proceed. If the session has not been successfully updated, ask your payer to select another checkout option.
Step 8: Perform 3-D Secure Authentication (Optional)
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.
Step 9: Perform Payment Operation
If the session has successfully been updated with the payment details from the SRC interaction (and the 3-D Secure Authentication, if performed in step 8), 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 SRC 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.
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
| HTTP Method | PUT |
{
"session":{
"id":"<session_ID>"
} "..."
}
The following HTML example code shows how to integrate SRCi.js into your payment page. Note the following:
SRCi.configure()must be called immediately after thesrci.min.jsscript is loaded into the page. Attempting to callSRCi.configure()within your button click handler will cause some browsers to block the opening of the SRC payment window.- The 'Pay' button event handler must first check that the JavaScript SDK is completely configured. Attempting to call
SRCi.launchUI()prior to a successful configuration will throw errors and negatively impact the payer experience. - The 'Pay' button should be disabled just before calling SRCi.launchUI() and re-enabled in each of the callbacks. Attempting to call
SRCi.launchUI()multiple times may result in unexpected behavior.
<html>
<head>
<script type="text/javascript" src="https://na.gateway.spring.citi.com/static/srci/1.2.0/srci.min.js"></script>
<script type="text/javascript">
var configured = false;
//SRCi global object is initialized by srci script
SRCi.configure(
"<gateway_merchant_ID>",
"<merchant_name>",
"<merchant_URL>",
"<session_ID>",
{ wsVersion: 57 },
function (response) {
if(response.result === "SUCCESS") {
configured = true;
console.log("Response from SDK: %s", response.restApiResponse);
} else if(response.result === "ERROR") {
console.log("An error occurred");
}
}
);
var payloadCallback = function (correlationId, scheme) {
console.log("Payload callback complete with correlation id %s and scheme %s", correlationId, scheme);
enablePayButton();
};
var errorCallback = function (error) {
console.log("Error callback triggered with error %s", error);
enablePayButton();
};
var cancelCallback = function () {
console.log("Cancel callback triggered");
enablePayButton();
};
function enablePayButton() {
document.getElementById("payButton").disabled = false;
}
function disablePayButton() {
document.getElementById("payButton").disabled = true;
}
function pay() {
if (configured) {
// ensure only one payment window is launched
disablePayButton();
SRCi.launchUI({
orderAmount: "100.00",
orderCurrency: "USD"
},
payloadCallback,
errorCallback,
cancelCallback
);
} else {
console.error("SRCi is not configured");
}
}
</script>
</head>
<body>
<button id="payButton" type="button" onclick="pay();">Pay</button>
</body>
</html>
SRC payment details
This section describes the payment details returned for SRC interactions.
Type of Payment Details Returned for SRC Interactions
SRC supports returning different types of payment details for processing. The payment details returned by the SRC system depend on the type requested by the gateway, your configuration in the SRC system, and the card scheme. SRC typically returns a network token, token expiry, and full cryptogram (where supported by the card scheme).
However, where the gateway is unable to send a network token with full cryptogram to your acquirer, SRC must instead provide a network token, token expiry and dynamic Card Security Code (CSC). The gateway will automatically ensure that the correct type of payment detail is requested.
If a card does not support network tokenization (for example, where the the issuer is not participating), SRC returns the card details (card number and card expiry) instead of network token details (network token, token expiry and cryptogram or dynamic CSC).
If you are a U.S. merchant and have indicated that you want to make use of your rights under the Durbin amendment, SRC provides the card details (card number and card expiry) for debit cards.
SRC Payment Details in API Transaction Response
The payment details selected by the payer during the SRC interaction are stored in the session and returned in the transaction response for API requests performed using the session. When SRC provides the network token details, both the network token details and the (masked) card details are provided.
Depending on the type of payment details returned by the SRC system, you receive the following details in the API response.
| Network token with full cryptogram (American Express does not support this type of network token) (The cryptogram is not returned in transaction responses) |
|
| Network token with dynamic CSC (The CSC is not returned in transaction responses) |
|
| Card number and expiry |
|
Payer Details
The payer's name and phone number are provided in the transaction response in the customer parameter group.
The payer's email address is provided in the transaction response in the customer.email field, if you have set consumerEmailAddressRequested to true.
Billing Address Details
The billing address details associated with the card are provided in the transaction response in the billing.address parameter group.
Shipping address details
If you have set collectShippingAddress to true, the shipping address details are provided in the transaction response in the shipping.address parameter group.
Merchant-Initiated Transactions
You must not offer SRC as a checkout option to your payers if you want to subsequently use those payment details to initiate payments in a series, such as recurring or installment payments. This will be supported in a future release.
Testing your integration
When you have completed your integration with the gateway for SRC, you can test it by using your test merchant profile (your merchant ID prefixed with TEST). When using the test merchant profile the gateway provides a simulator for the SRC interaction. The SRC simulator uses a set of pre-defined payment details that cannot be modified. Based on the pre-defined payment details, you can trigger and test different scenarios, as described below.
The second column in the tables below indicates the last 4 digits of FPAN selected by the payer during the SRC interaction. To trigger a scenario, select the corresponding FPAN on the simulator during the payer's SRC interaction.
| Scheme | Last 4 digits of FPAN | SRC Correlation Id | Resulting API UPDATE_SESSION_FROM_WALLET Response | Resulting API AUTHORIZE or PAY Response |
|---|---|---|---|---|
| Mastercard | xxx0007 | 783a935d-c6a9-4289-b19d-c3336f998b57 |
|
|
| Visa | xxx0003 | 12345671-visaTAVV-expiry0822-colShiptrue |
|
|
| Scheme | Last 4 digits of FPAN | SRC Correlation Id | Resulting API UPDATE_SESSION_FROM_WALLET Response | Resulting API AUTHORIZE or PAY Response |
|---|---|---|---|---|
| Mastercard | xxx0008 | 261af700-e576-43bf-af92-bd0f6810e8fb |
|
|
| Visa | xxx0002 | 12345671-visaDTVV-expiry0822-colShiptrue |
|
|
| American Express | xxx0017 | cf3de1e0-55a2-44cf-9563-5ef9e648c492 |
|
|
| Scheme | Last 4 digits of FPAN | SRC Correlation Id | Resulting API UPDATE_SESSION_FROM_WALLET Response | Resulting API AUTHORIZE or PAY Response |
|---|---|---|---|---|
| Mastercard | xxx0305 | 8e455e8b-4e52-46cf-a3da-83aa3cf9a76e |
|
|
| Visa | xxx0001 | 12345671-visa1-expiry0822 |
|
|
| American Express | xxx4564 | bb978084-42b7-4985-af9d-2e41ee0a370c |
|
|
Testing SRC with 3-D Secure authentication
If your merchant profile is enabled for EMV 3-D Secure Authentication (3DS2) you can use the SRC test details shown in the table below to trigger either a frictionless flow or a challenge flow.
| Scheme | Last 4 digits of FPAN | SRC Correlation Id | Resulting API Response |
|---|---|---|---|
| Mastercard | xxx0009 | 1049624e-cc67-45f6-bd5f-c625eb4c6cc1 |
|
| Visa | xxx4222 | 12345671-SRC3DSChallenge-expiry0822-colShiptrue |
|
| American Express | xxx0017 | 16e051bc-bd25-46db-a7d3-d2944fbb05cf |
|
| Scheme | Last 4 digits of FPAN | SRC Correlation Id | Resulting API Response |
|---|---|---|---|
| Mastercard | xxx0010 | 16e051bc-bd25-46db-a7d3-d2944fbb05cf |
|
| Visa | xxx4180 | 12345671-SRC3DSFrictionless-expiry0822-colShiptrue |
|
| American Express | xxx4564 | 17e051bc-bd25-46db-a7d3-d2944fbb05cf |
|