`Unified Click to Pay` Developer Guide {#uctp-about-guide} ========================================================== This section describes how to use this guide and where to find further information. Audience and Purpose : This document is written for merchants and ISVs who want to enable `Unified Click to Pay` so that they can accept payments on their e-commerce page. Conventions : This statement is used in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. Related Documentation : Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional technical documentation. Customer Support : For support information about any service, visit the Support Center: Pilot Release {#uctp-pilot-release} =================================== This document describes the pilot release of the `Unified Click to Pay` Developer Guide. Recent Revisions to This Document {#uctp-doc-revisions} ======================================================= 26.04.01 {#uctp-doc-revisions_section_s11_tdm_w3c} -------------------------------------------------- Added information about client and server keys. See these topics: * [API Authentication Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-api-keys.md "") * [JWT Validation Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-jwt-keys.md "") * [Client-Side PAN Encryption Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-pan-enc-keys.md "") * [Token Management MLE Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-tms-mle-keys.md "") {#uctp-doc-revisions_ul_qrx_cbp_53c} Added information about the required keys for checkout(). See [checkout()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-checkout.md "") and [checkout() API Specifications](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-api-specifications/uctp-api-specs-checkout.md ""). 26.03.01 -------- Added version to the capture context example. See [Capture Context](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-ss-setup/uctp-capture-context-intro.md ""). Updated the `uctp` object to `vsdk` in all examples. See these topics: * [initialize()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-initialize.md "") * [getCards()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-getcards.md "") * [checkout()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-checkout.md "") * [initiateIdentityValidation()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-init-validate.md "") * [unbindAppInstance()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-unbind-app.md "") Updated the intialize() example and syntax. See [initialize()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-initialize.md "") and [initialize() API Specifications](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-api-specifications/uctp-api-specs-initialize.md ""). 26.02.01 -------- Initial release. Introduction to `Unified Click to Pay` {#uctp-intro} ==================================================== `Unified Click to Pay`, powered by `Unified Checkout`, provides a flexible integration that enables merchants to customize their checkout experience for accepting `Click to Pay` payments from Visa, Mastercard, and American Express. The `Unified Click to Pay` SDK has no UI and the UI must be configured by the integrator. This enables merchants and partners to fully control the UI and branding. `Unified Click to Pay` offers advanced security and compliance and is PCI 4.0 compliant. `Unified Click to Pay` consists of a server-side API and a client-side JavaScript SDK. The server-side component authenticates your identity as the merchant and instructs the system to act within your payment environment. The response contains a JWT that can be used for the initialization of the client-side SDK and sets up the backend configuration required to run the SDK. The client-side JavaScript SDK can be used to integrate with `Click to Pay` payments from Visa, Mastercard, and American Express cards. > IMPORTANT > Each request that you send to ` Cybersource ` requires header information. For information about constructing the headers for your request, see the [Getting Started with REST Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md ""). Prerequisites ------------- Before you call the capture context and load the SDK, you must complete these tasks: 1. [Enable `Click to Pay`](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-intro/uc-enable-digital-pay-ctp.md ""). 2. [Upload Your Encryption Key](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-intro/uctp-upload-encryption-key.md ""). 3. [Set Up Customer Authentication for `Unified Click to Pay`](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-intro/uctp-authentication-steps.md ""). Enabling `Click to Pay` {#uc-enable-digital-pay-ctp} ==================================================== To begin your integration, you must first enable `Click to Pay`. `Click to Pay` is a digital payment solution that allows customers to pay with their preferred card network and issuer without entering their card details on every website. Customers can use Visa, Mastercard, and American Express cards to streamline their purchase experience. `Click to Pay` provides a fast, secure, and consistent checkout experience across devices and browsers. Follow these steps to enable in `Click to Pay` on `Unified Checkout`: 1. Log in to the `Business Center`: Test URL: ` `` ` Production URL: ` `` ` If you are unable to access this page, contact your sales representative. {#uc-enable-digital-pay-ctp_step-1} {#uc-enable-digital-pay-ctp_step-1} 2. In the `Business Center`, go to the left navigation panel and choose Payment Configuration \> Unified Checkout. The `Unified Checkout` customer experience page appears: #### Figure: `Unified Checkout` Customer Experience ![Image that shows the Unified Checkout Customer Experience page.](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-checkout/images/uc-custom-exp-800x875.png/jcr:content/renditions/original) {#uc-enable-digital-pay-ctp_step-2} {#uc-enable-digital-pay-ctp_step-2} 3. In the Payment Options section, click **Manage**. The Payment Options page appears. 4. Click **Manage** next to `Click to Pay`. The `Click to Pay` configuration page appears. 5. Enter your business name and website URL. 6. Click Submit. 7. Contact your implementation contact or technical account manager to request that you be enabled for tokenization within `Click to Pay`. Your implementation contact or technical account manager will confirm that you were configured successfully and that you can now accept digital payments with `Click to Pay`. > IMPORTANT > ` Click to Pay ` uses network tokenization for transactions. These network tokens are stored in the vault of the token requestor ID (TRID) for the card scheme. Upload Your Encryption Key {#uctp-upload-encryption-key} ======================================================== After you enable `Click to Pay`, you must upload your public encryption keys so that you can retrieve payment information from the `Unified Click to Pay` checkout() SDK method. This method retrieves all of the payment data that is captured during the transaction. The payment data is encrypted to ensure that the payment information is secure. You must generate an encryption key pair to retrieve the encrypted payment information and upload the public encryption key to the `our platform`. > IMPORTANT > You must upload your encryption key before you can generate the capture context from the ` sessions ` API. > Follow these steps to upload your encryption key to the `our platform`: 1. Log in to the `Business Center`: Test URL: ` `` ` Production URL: ` `` ` If you are unable to access this page, contact your sales representative. 2. In the `Business Center`, from the navigation panel choose Payment Configuration \> Key Management. ![](/content/dam/documentation/cybs/en-us/topics/platform/rest/getting-started/images/left-navigation-311x633.png/jcr:content/renditions/original) 3. Click + Generate key. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/payment-services/sec-keys/images/generate-key-1200x309.png/jcr:content/renditions/original) 4. Under Alternate Key Types, choose Token Management MLE and click Generate key. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/payment-services/sec-keys/images/tms-mle-key-list-1200x1554.png/jcr:content/renditions/original) 5. Enter your public key in Base64 format and click Create key. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/payment-services/sec-keys/images/tms-mle-create-key.png/jcr:content/renditions/original) Set Up Customer Authentication for `Unified Click to Pay` {#uctp-authentication-steps} ====================================================================================== After you enable Click to Pay and upload your encryption key, you must set up customer authentication for `Unified Click to Pay`. Follow these steps to use the `Business Center` to enable customer authentication through `Unified Click to Pay`. Authentication methods differ in each region and are dependent on the issuer, the cardholder device, and the Click to Pay configuration. These authentication methods are available: * `3-D Secure` * FIDO * Card verification value (CVV) * One-time password (OTP) > IMPORTANT > After you complete these steps, Visa determines which authentication method to use. When Visa determines that they will authenticate, they authenticate each Click to Pay transaction through the appropriate method. This may be a frictionless authentication or the customer may need to provide more information when required by the issuer. This is available only through Visa. 1. Log in to the `Business Center`: Test URL: ` `` ` Production URL: ` `` ` If you are unable to access this page, contact your sales representative. {#uctp-authentication-steps_step-1} {#uctp-authentication-steps_step-1} 2. In the `Business Center`, from the navigation panel choose Payment Configuration \> Unified Checkout. You must have Click to Pay enabled as a digital payment method to use this method of authentication. Click Manage to view the digital payment methods that you have enabled. ![Manage Unified Checkout Digital Payments Solutions](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-checkout/images/pmt-config-unified-payments-digitalpmtsolutions.png/jcr:content/renditions/original) If Click to Pay is not enabled, click On next to Click to Pay. ![Manage Available Digital Payments Solutions](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-click-to-pay/images/uctp-ebc-600x600.png/jcr:content/renditions/original) {#uctp-authentication-steps_step-2} {#uctp-authentication-steps_step-2} 3. Enter the account details and click Update. 4. Click Set up under Value Added Solutions. The Value Added Solutions page appears. ![Value Added Solutions Page](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-checkout/images/pmt-config-unified-payments-vas.png/jcr:content/renditions/original) 5. Click Set up to set up `3-D Secure`. The 3DS page appears. 6. Enter the required information in the Merchant Details section. You must enter the information that is provided to you by your acquirer or processor. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-checkout/images/pmt-config-unified-payments-3ds.png/jcr:content/renditions/original) #### Step Result This completes the authentication setup for the entered acquirer merchant ID and BIN. If you do not know what these values are, you must contact your acquirer. Completing this information enables `Cybersource` to send Visa the information that is required for authentication. IMPORTANT Charges for ` 3-D Secure ` may apply. You must speak with your acquirer for more information about the charges associated with ` 3-D Secure `. `Unified Click to Pay` Customer Workflows {#uctp-customer-workflows} ==================================================================== This section describes the flows within `Unified Click to Pay`. `Unified Click to Pay` provides customers with a simple payment experience across multiple payment networks. You can customize the user experience. The customer flow for calling the capture context and loading the SDK differs based on the type of customer in `Click to Pay`: * The customer is a recognized `Click to Pay` customer. * The customer is not recognized by `Unified Click to Pay` but is a `Click to Pay` customer. * The customer is a new user enrolling in `Click to Pay`. Recognized `Click to Pay` Customer {#uctp-flow-recognized} ========================================================== This section provides an overview of the `Click to Pay` recognized experience. This interaction occurs when a customer's device is recognized by the `Unified Click to Pay`. A customer's device is recognized under these conditions: * When the customer has used `Click to Pay` on their device through any `Click to Pay` channel. * If the customer chose to have their device remembered during a previous transaction. #### Figure: Recognized `Click to Pay` Customer ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-click-to-pay/images/uctp-recognized-flow-600x500.svg/jcr:content/renditions/original) 1. Set up your server side by generating the capture context. For information about how to set up your server side, see [Server-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-ss-setup.md ""). 2. Set up your client side by initiating the `Unified Click to Pay` JavaScript SDK. For a recognized customer, you will load these functions from the SDK: * initialize(capture context JWT) * getCards(consumer identity - email) * checkout(card details) For information about setting up the client side, see [Client-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-cs-setup.md ""). Unrecognized `Click to Pay` Customer {#uctp-flow-unrecognized} ============================================================== This section provides an overview of the `Unified Click to Pay` unrecognized experience. This interaction occurs when a customer's device is not recognized by the `Unified Click to Pay` SDK. This condition occurs when the customer has a `Click to Pay` account but has not used it on their device previously. #### Figure: Unrecognized `Click to Pay` Customer ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-click-to-pay/images/uctp-unrecognized-flow-600x555.svg/jcr:content/renditions/original) 1. Set up your server side by generating the capture context. For information about how to set up your server side, see [Server-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-ss-setup.md ""). 2. Set up your client side by initiating the `Unified Click to Pay` JavaScript SDK. For an unrecognized customer, you will load these functions from the SDK: * initialize(capture context JWT) * getCards(consumer identity - email) * getCards(validation data - otp) * checkout(card details) For information about setting up the client side, see [Client-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-cs-setup.md ""). Guest Customer {#uctp-flow-guest} ================================= This section provides an overview of the `Unified Click to Pay` guest flow. This interaction occurs when the customer has not created a `Click to Pay` account, or their issuer has not provisioned their card into `Click to Pay`. #### Figure: Guest Customer ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/unified-click-to-pay/images/uctp-guest-flow-600x500.svg/jcr:content/renditions/original) 1. Set up your server side by generating the capture context. For information about how to set up your server side, see [Server-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-ss-setup.md ""). 2. Set up your client side by initiating the `Unified Click to Pay` JavaScript SDK. For a guest customer, you will load these functions from the SDK: * initialize(capture context JWT) * getCards(consumer identity - email) * checkout(card details) For information about setting up the client side, see [Client-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-cs-setup.md ""). `Unified Click to Pay` Integration {#uctp-integration-details} ============================================================== This section describes how to integrate and launch `Unified Click to Pay` on your website and process a transaction for you. For information about the detailed specifications of the APIs described in this section see [API Specifications](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-api-specifications.md ""). To integrate `Unified Click to Pay` into your platform, you must follow these integration steps: 1. You send a server-to-server API request for a capture context. This request is fully authenticated and returns a JSON Web Token (JWT) that is necessary to invoke the frontend JavaScript library. For information on setting up the server side, see [Server-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-ss-setup.md ""). 2. You invoke the `Unified Click to Pay` JavaScript library using the JWT response from the capture context request. For information on setting up the client side, see [Client-Side Set Up](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-integration-details/uctp-cs-setup.md ""). > IMPORTANT > Each request that you send to ` Cybersource ` requires header information. For information about constructing the headers for your request, see the [Getting Started with REST Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md ""). Server-Side Set Up {#uctp-ss-setup} =================================== This section contains the information you need to set up your server. Initializing `Unified Click to Pay` within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials, and establishes how `Unified Click to Pay` manages your capture context configuration. This includes supported locales, currencies, and country availability. The sessions API request contains parameters that define how `Unified Click to Pay` performs. For information about sessions API requests, see [Generate Unified Click to Pay Capture Context](https://developer.cybersource.com/api-reference-assets/index.md#unified-checkout_unified-click-to-pay-capture-context_generate-unified-click-to-pay-capture-context "") in the `Cybersource` API Reference. The server-side component provides this information: * A transaction-specific public key is used by the customer's browser to protect the transaction. * An authenticated context description package that manages the payment experience on the client side. It includes available payment options such as card networks, and payment methods. {#uctp-ss-setup_ul_atq_bwq_npb} The functions are compiled in a JSON Web Token (JWT) object referred to as the *capture context* . The header of each JWT header contains a key ID field (`kid`) that references the specific RSA public key that `Cybersource` used to sign that token. The integrator must retrieve this public key from `Cybersource` and use it to verify the JWT's signature. If the signature is invalid, the JWT must be rejected. For information about JWTs, JWT validation keys, and API authentication keys, see these topics: * [JSON Web Tokens](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uc-appendix-jwts.md "") * [JWT Validation Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-jwt-keys.md "") * [API Authentication Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-api-keys.md "") {#uctp-ss-setup_ul_nrx_r2t_w3c} Capture Context {#uctp-capture-context-intro} ============================================= The capture context request is a signed JSON Web Token (JWT) that includes all of the merchant-specific parameters. This request tells the frontend JavaScript library how to behave within your payment experience. The request provides authentication, one-time keys, in addition to allowed card networks and payment types. The capture context, at a minimum, requires these elements: * allowedCardNetworks * amountDetails * billingType * country * currency * data.orderInformation.amountDetails.totalAmount * data.orderInformation.amountDetails.currency * locale * totalAmount * version Capture Context Example {#uctp-capture-context-intro_example} ------------------------------------------------------------- ``` { // -------- REQUIRED VALUES ---------- "data": { "orderInformation": { "amountDetails": { "totalAmount": "123.94", "currency": "USD" } } }, "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX" ], "billingType": "FULL", "country": "US", "locale": "en_US", "version":"0.6" } ``` Client-Side Set Up {#uctp-cs-setup} =================================== This section contains the information you need to set up the client side. You use the `Unified Click to Pay` JavaScript library to add the payment interface to your e-commerce site. Follow these steps to set up the client: 1. Load the JavaScript library. 2. Initialize the SDK with the JWT by passing the JWT as a parameter in the initialization method. For information JSON Web Tokens, see [JSON Web Tokens](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uc-appendix-jwts.md ""). {#uctp-cs-setup_ul_m5t_gwq_npb} After you initialize the SDK, you can use the unified SDK as a single integration across multiple `Click to Pay` schemes. Loading the JavaScript Library {#uctp-load-js-library} ====================================================== Use the clientLibrary asset path and clientLibraryIntegrity value that is returned by the capture context response to invoke `Unified Click to Pay`. You must retrieve these values from the clientLibrary and clientLibraryIntegrity fields that are returned in the JWT from `https://apitest.cybersource.com``/uctp/v1/sessions`: ``` "data": { "clientLibrary": "[EXTRACT clientLibrary VALUE from here]", "clientLibraryIntegrity": "[EXTRACT clientLibraryIntegrity VALUE from here]" } ``` You can use these values to create your script tags: ``` <script src="[INSERT clientLibrary VALUE HERE]" integrity=”[INSERT clientLibraryIntegrity VALUE HERE]” crossorigin=”anonymous”></script> <script> var vsdk = window.VSDK </script> ``` You must perform this process for each transaction, as these values are unique for each transaction. You must avoid hard-coding values for the clientLibrary and clientLibraryIntegrity fields to prevent client-side errors. > IMPORTANT > Use the clientLibrary and clientLibraryIntegrity parameter values in the capture context response to obtain the ` Unified Click to Pay ` JavaScript library URL and the integrity value. This ensures that you are always using the most up-to-date library and protects against fraud. Do not hard-code the ` Unified Click to Pay ` JavaScript library URL or integrity value. > When you load the library, the capture context from your initial server-side request is used to invoke the accept function. Get Started with `Unified Click to Pay` {#uctp-getting-started} =============================================================== This section describes the specifications for these `Unified Click to Pay` API methods and their parameters: * [initialize()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-initialize.md "") * [getCards()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-getcards.md "") * [checkout()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-checkout.md "") * [initiateIdentityValidation()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-init-validate.md "") * [unbindAppInstance()](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-getting-started/uctp-get-started-unbind-app.md "") You must use client and server keys to validate your integration. For information about the keys that are used in your `Unified Click to Pay` integration, see [Client and Server Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys.md ""). initialize() {#uctp-get-started-initialize} =========================================== This method initializes the application with the common state. The initialize method must be called before any other methods. JavaScript Example ------------------ ``` window.onload = async function() { // Create a shorthand reference to the Unified Click to Pay SDK const vsdk = window.VSDK; // fetch the JWT from Capture Context // Initialize the Unified Click to Pay SDK with your JWT received from capture context try { await vsdk.initialize({ header: header, payload: payload, raw: capture - context //optionally, pass the dpaTransactionOptions here }); //Invoke getCards and other apis here onwards } catch (error) { console.error('Error initializing SDK:', error); ``` In this example, captureContext refers to the capture context JWT. Syntax ------ Your initialize() request must have this syntax: ``` initialize({ required object captureContext; optional DpaTransactionOptions dpaTransactionOptions; }); ``` getCards() {#uctp-get-started-getcards} ======================================= getCards encapsulates all your identity calls. Make the getCards with the email. For unrecognized user, you'd receive `PENDING_CONSUMER_IDV`. This would trigger an OTP generation. Make the getCards call again with the OTP. JavaScript Example ------------------ ``` // Get cards sample request let consumerIdentity = { identityProvider: "SRC", identityValue: "pocusr2cert1@mailinator.com", identityType: "EMAIL_ADDRESS" }; let cards = await vsdk.getCards({ consumerIdentity }); let { actionCode } = cards; switch (actionCode) { case 'SUCCESS': //handle getCards response in UI console.log('Handle getCards response in the UI ', cards); break; // If cards status is "PENDING_CONSUMER_IDV", call getCards again with validationData case 'PENDING_CONSUMER_IDV': const validationDataInput = { consumerIdentity, validationData: "654321"}; // Replace with your actual validation data cards = await vsdk.getCards(validationDataInput); break; case 'ERROR': console.log('Handle error cases:'); break; default: console.log('No cards found >> ', cards.actionCode); break; } ``` Syntax ------ Your getCards() request must have this syntax: ``` getCards({ required ConsumerIdentity consumerIdentity; conditional String validationData; }) ``` checkout() {#uctp-get-started-checkout} ======================================= This method performs checkout using the specified digital card or PAN. If successful, the response contains summary checkout information and, conditionally, an encrypted payload signed by the SRC System containing PCI and/or PII data. This method is called after the consumer has chosen a card for checkout from the card list or when the consumer enrolls a new card. To add a card, the partner or merchant must provide the encrypted card object, instead of ID of the digital card identifier, as an input parameter. The card will be enrolled into the SRC system and used for checkout. The checkout() method uses three types of keys: * **JWT validation keys** : The checkout response from vsdk.checkout() is a signed JWT with the payment credentials. The response must be verified server-side by retrieving the RSA public key from `https://api.cybersource.com``/flex/v2/public-keys` using the `kid` from the header of each JWT. `Cybersource` recommends that you do not skip this step, as this verification exposes the integration to payload tampering. For information about JWT validation keys, see [JWT Validation Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-jwt-keys.md ""). * **Client-side PAN encryption keys** : When you add a card to `Unified Click to Pay`, the customer manually enters their card details in the UI. The raw PAN must be JWE-encrypted in the browser before it is passed to checkout(encryptedCard). The encryption key is a per-network RSA JWK from the `/sessions` API response from paymentConfigurations.\[SRCVISA\|SRCMASTERCARD\|SRCAMEX\].panEncryptionKey. The encyrypted key is selected using the PAN's BIN range. For information about client-side PAN encryption keys, see [Client-Side PAN Encryption Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-pan-enc-keys.md ""). * **Token Management MLE keys** : The checkout() response can include PCI/PII data that is in the encryptedPayload field. This data is encrypted by `Cybersource` using the merchant's RSA public key uploaded to the `Cybersource` `Business Center`. The merchant decrypts it server-side using their corresponding private key. For information about Token Management MLE keys, see [Token Management MLE Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-tms-mle-keys.md ""). {#uctp-get-started-checkout_ul_off_3gy_x3c} JavaScript Example ------------------ ``` //sample checkoutParameters const checkoutParameters = { srcDigitalCardId: 'nE5xhI3jQcSis6Vf7IAH-A000000000000US', dpaTransactionOptions: { dpaBillingPreference: 'POSTAL_COUNTRY', dpaAcceptedBillingCountries: ['US', 'CA'], consumerNationalIdentifierRequested: false, merchantCategoryCode: '4829', merchantCountryCode: 'US', merchantOrderId: '8e15ce5c-58a3-4748-acab-71c67432dfa7', paymentOptions: [ { dpaDynamicDataTtlMinutes: 2, dynamicDataType: 'CARD_APPLICATION_CRYPTOGRAM_LONG_FORM' } ] }, payloadTypeIndicatorCheckout: 'FULL' }; // Call checkout const checkoutResponse = await vsdk.checkout(checkoutParameters); // Log the checkout response console.log(checkoutResponse); ``` Syntax ------ Your checkout() request must have this syntax: ``` checkout({ conditional String srcDigitalCardId; conditional JWE<Card> encryptedCard; optional Consumer consumer; optional DpaTransactionOptions dpaTransactionOptions; optional PayloadTypeIndicator payloadTypeIndicatorCheckout; conditional Window windowRef; conditional ComplianceSettings complianceSettings; optional AssuranceData assuranceData; }) ``` initiateIdentityValidation() {#uctp-get-started-init-validate} ============================================================== This can be used to trigger resend the OTP. JavaScript Example ------------------ ``` await vsdk.initiateIdentityValidation({ consumerIdentity }); ``` Syntax ------ Your initiateIdentityValidation() request must have this syntax: ``` initiateIdentityValidation({ optional String requestedValidationChannelId }) ``` unbindAppInstance() {#uctp-get-started-unbind-app} ================================================== This method unbinds a device identity (an application instance) from an SRC profile. JavaScript Example ------------------ ``` await vsdk.unbindAppInstance(); ``` Syntax ------ Your unbindAppInstance() request must have this syntax: ``` unbindAppInstance() ``` API Specifications {#uctp-api-specifications} ============================================= This section describes the specifications for all `Unified Click to Pay` API methods and their parameters. initialize() {#uctp-api-specs-initialize} ========================================= dpaTransactionOptions is an optional field in a initialize() request. You can include the dpaTransactionOptions field in the `initialize()` request if your system supports it. You must consider this information if you include the dpaTransactionOptions field in your request: * You must include the transaction amount and currency in the backend of the request payload that is sent to `/sessions` API. The values that are included in the request to the `/sessions` API are used and any value included in dpaTransactionOptions are ignored. * You must configure authentication fields in the `Business Center`. The values of these fields are retrieved from the merchant or partner profiles and not from the dpaTransactionOptions field. Your initialize() request must have this syntax: ``` initialize({ required object captureContext; optional DpaTransactionOptions dpaTransactionOptions; }); ``` Request Parameters {#uctp-java-initialize} ========================================== Your initialize() request can include these parameters: Request Parameters {#uctp-java-initialize_OLE_LINK50} ----------------------------------------------------- | Name | Required? | Description | |--------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------| | dpaTransactionOptions **Type** : DpaTransactionOptions | Optional | These options can override default transaction options configured during DPA Registration. | | header **Type**: Decoded JWT header as a String | Required | Decoded header from the `/sessions` API response. | | payload **Type**: Decoded JWT payload as a String | Required | Decoded payload from the `/sessions` API response. | | raw **Type**: String | Required | JWT from the `/sessions` API response. | DpaTransactionOptions --------------------- | Data Element | Required? | Description | |------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------| | dpaAcceptedBillingCountries **Type**: List\<String\> | Optional | Billing restrictions. Payments from these countries are accepted. ISO 3166‑1 alpha‑2 country codes. `["US","CA","AU"]` | | dpaBillingPreference **Type** : AddressPreference | Optional | Type of billing address required. Possible values: * `FULL` * `NONE` * `POSTAL_COUNTRY` | | dpaLocale **Type**: String | Optional | Merchant preferred locale in ISO 639‑1 and ISO 3166‑1 format. `["en_US", "fr_CA"]` | | merchantCategoryCode **Type**: String **Length**: 4 | Optional | Merchant category code. | | merchantCountryCode **Type**: String | Optional | Merchant country in ISO 3166‑1 alpha‑2 format. | | merchantName **Type**: String | Optional | Merchant name. | | merchantOrderId **Type**: String, UUID | Optional | DPA-generated order or invoice number. | | paymentOptions **Type** : List\<PaymentOptions\> | Optional | Dynamic Data requirements. | | recurringData **Type** : RecurringData | Optional | Recurring transaction data. | PaymentOptions -------------- | Data Element | Required? | Description | |-----------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | dpaDynamicDataTtlMinutes **Type**: String (Numeric) | Optional | TTL of the dynamic data in minutes. | | dynamicDataType **Type** : DynamicDataType | Optional | Type of dynamic data required. * `CARD_APPLICATION_CRYPTOGRAM_LONG_FORM` * `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM` * `CARDHOLDER_AUTHENTICATION_CRYPTOGRAM` * `DYNAMIC_CARD_SECURITY_CODE` * `NONE` | AuthenticationPreferences ------------------------- | Data Element | Required? | Description | |--------------------------------------------------------------------|-----------|-----------------------------------------| | authenticationMethods **Type**: List\<AuthenticationMethod\> | Optional | List of authentication methods. | | payloadRequested **Type** : PayloadRequested | Optional | Indicates preferred payload type. | | supressChallenge **Type**: Boolean | Optional | SRCI preference to suppress challenges. | **AuthenticationMethod** ------------------------ | Data Element | Required? | Description | |----------------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | authenticationMethodType **Type** : AuthenticationMethodType | Required | Indicates whether C2P should perform managed authentication. Possible values: * `3DS` * `APP_AUTHENTICATION` * `CSC_VALIDATION` * `EMAIL_OTP` * `SMS_OTP` | | authenticationSubject **Type** : AuthenticationSubject | Required | Authentication subject. Possible values: * `CARD` * `CARDHOLDER` * `CONSUMER` | | uriData **Type** : UriData | Optional | URI used to launch authentication. Relevant data is returned asynchronously. | | authenticationCredentialReference **Type**: String **Maximum Length**: 255 | Optional | Reference returned by identity provider. | | methodAttributes **Type**: JSONObject | Optional | Method‑specific attributes. | The content of the methodAttributes object depends on the authenticationMethodType field value and the method that is requested. The methodAttributes object is included within the checkout response for the authentication flow or as part of the AuthenticationMethod object in the checkout authentication request flow. If authenticationMethodType is any of the these values. * `CSC_VALIDATION` * `SMS_OTP` * `EMAIL_OTP` * `APP_AUTHENTICATON` * `3DS` | authenticationMethodType | Data Element | Description | |------------------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CSC_VALIDATION` | cardSecurityCode **Type**: String **Maximum Length**: 4 | Card security code. | | `SMS_OTP` | otpValue **Type**: String **Maximum Length**: 16 | OTP value. | | `EMAIL_OTP` or `APP_AUTHENTICATON` | stepUpIdentifier **Type**: String | Step-up identification. | | `3DS` | challengeIndicator **Type**: String | Challenge indicator value related to `3-D Secure` authentication. For SRC orchestrated `3-D Secure` is authentication method, SRCIs can specify the preference of challenge indicator here. Please refer to EMV `3-D Secure` specification for more details. > IMPORTANT > If no preference provided, SRC will set up the default value of ` 01 ` for ` 3-D Secure ` and 04 when followed by FIDO registration. > If value is set to ` 05 ` by the SRCI then do not override the indicator to ` 03 ` though it is a FIDO compliant device. Possible values: * `01`: No preference * `02`: No challenge requested * `03`: Challenge requested (3DS Requestor Preference) * `04`: Challenge requested (Mandate) * `05`: No challenge requested (transactional risk analysis is already performed) * `06`: No challenge requested (Data share only) * `07`: No challenge requested (strong consumer authentication is already performed) * `08`: No challenge requested (utilize trust list exemption if no challenge required) * `09` :Challenge requested (trust list prompt requested if challenge required) | UriData ------- | Data Element | Required? | Description | |-----------------------------------------------|-----------|--------------------------------------------------------| | uri **Type**: String **Maximum Length**: 2048 | Required | Specifies the URI for the given authentication method. | | uriType **Type** : UriType | Required | URI type. Possible values: * `APP_URI` * `WEB_URI` | RecurringData ------------- | Data Element | Required? | Description | |-------------------------------------------------------------------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | recurringAmount **Type**: String (Numeric) **Maximum Length**: 48 | Required when recurringInd.AmountInd = `01` | Recurring amount in minor units of currency with all punctuation removed. For example, when the purchase amount is USD 123.45, these values are acceptable: * `12345` * `012345` * `0012345` | | recurringCurrency **Type**: String | Required when recurringAmount is included. | Currency in which recurringAmount is expressed. Currency must be in ISO 4217 format. | | recurringDate **Type**: String (Numeric) **Length**: 8 | Required when recurringInd.frequencyInd = `01` | Effective date in YYYYMMDD format. | | recurringExpiry **Type**: String (Numeric) **Length**: 8 | Required when there is an end date. | Date after which no further authorizations occur, in YYYYMMDD format. | | recurringExponent **Type**: String (Numeric) **Length**: 1 | Required when recurringAmount is included. | Minor units of currency according to ISO 4217 (e.g., USD=2, JPY=0). | | recurringFrequency **Type**: String **Maximum Length**: 4 | Required when recurringInd.frequencyInd = `01` | Minimum number of days between authorizations (1--9999). | | recurringInd **Type**: JSONObject | Required | Indicates recurring/instalment amount and frequency type. Possible values for amountInd: * `01`: Fixed * `02`: Variable Possible values for frequencyInd: * `01`: Fixed frequency * `02`: Variable/unknown frequency Example: ``` { "recurringInd": { "amountInd": "01", "frequencyInd": "02" } } ``` | Handle Errors {#uctp-initialize-errors} ======================================= An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could nxot be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [ // Optional structure, used with input data validation error { // Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `UNKNOWN_ERROR` | Unknown error. | [Error Codes] getCards() {#uctp-api-specs-getcards} ===================================== Your getCards() request must have this syntax: ``` getCards({ required ConsumerIdentity consumerIdentity; conditional String validationData; }) ``` Request Parameters {#uctp-java-getcards} ======================================== Your getCards() request can include these parameters: Request Parameters ------------------ | **Field** | **Required?** | **Description** | |----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | consumerIdentity **Type** : ConsumerIdentity | Required | Primary verifiable consumer identity within an SRC profile (e.g. an email address). > IMPORTANT If an SRC system recognizes the user then this identity can be ignored. | | validationData **Type**: String | Required when a prior call within the same transaction returns a field value of `PENDING_CONSUMER_IDV` for the actionCode field. | The validation data (e.g. the OTP value) entered by the user. > IMPORTANT > When a merchant calls getCards() for the first time and the user is not recognized, Visa initiates identity validation and returns a value of ` PENDING_CONSUMER_IDV ` for the actionCode field. This field is required the second time the merchant calls getCards() after the OTP is provided. | ConsumerIdentity ---------------- | **Data Element** | **Required?** | **Description** | |--------------------------------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------| | identityProvider **Type** : IdentityProvider | Optional | Entity or organization that collected and verified the identity. The default value is `SRC`. | | identityType **Type** : ConsumerIdentityType | Required | Type of consumer identity transmitted or collected. Possible values: * `EMAIL_ADDRESS` * `MOBILE_PHONE_NUMBER` | | identityValue **Type**: String **Maximum Length**: 255 | Required | Consumer identity value used to locate profile information. This is not an SRC consumer reference identifier but a consumer‑provided value. | SrcProfile ---------- | Data Element | Required? | Description | |-------------------------------------------------|-----------|-----------------------------------------------------------------| | maskedCards **Type** : List\<MaskedCard\> | Required | Masked card data associated with the SRC profile. May be empty. | | maskedConsumer **Type** : MaskedConsumer | Optional | Masked consumer data associated with the profile. | MaskedCard ---------- | Data Element | Required? | Description | |-----------------------------------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------| | srcDigitalCardId **Type**: String Universally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for checkout. | | panBin **Type**: String (Numeric) **Maximum Length**: (PAN Length -10) | Required | First significant digits of the PAN in unmasked form. | | panLastFour **Type**: String (Numeric) **Length**: 4 | Required | Last four digits of the PAN in unmasked form. | | panExpirationMonth **Type**: String (Numeric) **Length**: 2 | Required when specified for the PAN. | Expiration month (MM). | | panExpirationYear **Type**: String (Numeric) **Length**: 4 | Required when specified for the PAN. | Expiration year in YYYY format. | | tokenBinRange **Type**: String (Numeric) **Maximum Length**: (Payment token length -10) | Required when a payment token is used. | BIN range used for issuing payment tokens (unmasked). | | tokenLastFour **Type**: String (Numeric) **Length**: 4 | Required when a payment token is used. | Last four digits of the payment token (unmasked). | | digitalCardData **Type** : DigitalCardData | Required | Digital card information used in UI and acceptance environments. | | maskedCardholderFullName **Type**: String **Maximum Length**: 100 | Optional | Masked full cardholder name. | | maskedCardholderFirstName **Type**: String **Maximum Length**: 50 | Optional | Masked first name. | | maskedCardholderLastName **Type**: String **Maximum Length**: 50 | Optional | Masked last name. | | paymentCardDescriptor **Type**: String **Maximum Length**: 32 | Optional | Card brand descriptor. | | paymentCardType **Type**: String **Maximum Length**: 32 | Optional | Card type. | | digitalCardFeatures **Type** : List\<DigitalCardFeature\> | Optional | Attributes related to digital card features for consumer display. | | countryCode **Type**: String | Optional | Issuer country code in ISO 3166‑1 alpha‑2 format. | | maskedBillingAddress **Type** : MaskedAddress | Optional | Masked billing address. | | dcf **Type** : Dcf | Optional | Digital Card Facilitator. Present when MaskedCard is used in Checkout or Get Payload. | | paymentAccountReference **Type**: String **Maximum Length**: 29 | Optional | Reference tying PAN to its associated tokens. | | dateOfCardCreated **Type**: String (Numeric) UTC Unix epoch | Required | Date the card was enrolled. | | dateOfCardLastUsed **Type**: String (Numeric) UTC Unix epoch | Optional | Date when card was last used. | DigitalCardData --------------- | Data Element | Required? | Description | |---------------------------------------------------------------|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | status **Type** : DigitalCardStatus | Required | State of the digital card. Possible values: * `ACTIVE` * `CANCELLED` * `EXPIRED` * `PENDING` * `SUSPENDED` | | presentationName **Type**: String **Maximum Length**: 64 | Optional | Consumer-defined text to help recognize the card. | | descriptorName **Type**: String **Maximum Length**: 64 | Required | System‑defined card description. | | artUri **Type**: String **Maximum Length**: 1024 | Required | URI hosting the card image. | | artHeight **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Card art height in pixels. | | artWidth **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Card art width in . | | pendingEvents **Type** : List\<CardPendingEvent\> | Required when the status is `PENDING`. | Pending events. Possible values: * `PENDING_AVS` * `PENDING_CSC` * `PENDING_CONSUMER_IDV` * `PENDING_ CARDHOLDER_AUTHENTICATION` | | authenticationMethods List\<AuthenticationMethod\> | Optional | List of supported authentication methods. | AuthenticationMethod -------------------- | Data Element | Required? | Description | |----------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | authenticationMethodType **Type** : AuthenticationMethodType | Required | SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not. Possible values: * `3DS` * `APP_AUTHENTICATION` * `CSC_VALIDATION` * `EMAIL_OTP` * `SMS_OTP` | | authenticationSubject **Type** : AuthenticationSubject | Required | Authentication subject. Possible values: * `CARD` * `CARDHOLDER` * `CONSUMER` | | uriData **Type** : UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then AssuranceData, AuthenticationStatus, AuthenticationResult and any relevant session ids should be provided back asynchronously when authentication completes. It can be achieved by cross‑origin post message between the windows (caller and authenticator). | | authenticationCredentialReference **Type**: String **Maximum Length**: 255 | Optional | May be provided by the identity provider to qualify the nature of the authentication method. | | methodAttributes **Type**: JSONObject | Optional | Attributes associated with the authentication method type. | The content of the methodAttributes object depends on the authenticationMethodType field value and the method that is requested. The methodAttributes object is included within the checkout response for the authentication flow or as part of the AuthenticationMethod object in the checkout authentication request flow. If authenticationMethodType is any of the these values. * `CSC_VALIDATION` * `SMS_OTP` * `EMAIL_OTP` * `APP_AUTHENTICATON` * `3DS` | authenticationMethodType | Data Element | Description | |------------------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CSC_VALIDATION` | cardSecurityCode **Type**: String **Maximum Length**: 4 | Card security code. | | `SMS_OTP` | otpValue **Type**: String **Maximum Length**: 16 | OTP value. | | `EMAIL_OTP` or `APP_AUTHENTICATON` | stepUpIdentifier **Type**: String | Step-up identification. | | `3DS` | challengeIndicator **Type**: String | Challenge indicator value related to `3-D Secure` authentication. For SRC orchestrated `3-D Secure` is authentication method, SRCIs can specify the preference of challenge indicator here. Please refer to EMV `3-D Secure` specification for more details. > IMPORTANT > If no preference provided, SRC will set up the default value of ` 01 ` for ` 3-D Secure ` and 04 when followed by FIDO registration. > If value is set to ` 05 ` by the SRCI then do not override the indicator to ` 03 ` though it is a FIDO compliant device. Possible values: * `01`: No preference * `02`: No challenge requested * `03`: Challenge requested (3DS Requestor Preference) * `04`: Challenge requested (Mandate) * `05`: No challenge requested (transactional risk analysis is already performed) * `06`: No challenge requested (Data share only) * `07`: No challenge requested (strong consumer authentication is already performed) * `08`: No challenge requested (utilize trust list exemption if no challenge required) * `09` :Challenge requested (trust list prompt requested if challenge required) | UriData ------- | Data Element | Required? | Description | |-----------------------------------------------|-----------|--------------------------------------------------------| | uri **Type**: String **Maximum Length**: 2048 | Required | Specifies the URI for the given authentication method. | | uriType **Type** : UriType | Required | URI type. Possible values: * `APP_URI` * `WEB_URI` | DigitalCardFeature ------------------ | Data Element | Required? | Description | |------------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------| | content **Type**: String **Maximum Length**: 1024 | Required | Content of the digital card feature. | | contentType **Type** : DigitalCardFeatureContentType | Required | Content type of the digital card feature. Possible values: * `CONTENT_URL` * `IMAGE_URL` * `LINK_URL` * `TEXT_STRING` | | style **Type**: String **Maximum Length**: 1024 | Optional | URL of a CSS file defining style. | | width **Type**: String (Numeric) | Optional | Width of card feature. | | height **Type**: String (Numeric) | Optional | Height of card feature. | MaskedAddress ------------- The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/ | Data Element | Required? | Description | |-----------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------| | addressId **Type**: String Universally Unique Identifier (UUID) | Required | Identifier used to point to the address. | | name **Type**: String **Maximum Length**: 100 | Optional | Name of the individual receiving the delivered goods or service. Only applicable for the shipping address. | | line1 **Type**: String **Maximum Length**: 75 | Optional | Address line 1. | | line2 **Type**: String **Maximum Length**: 75 | Optional | Address line 2. | | line3 **Type**: String **Maximum Length**: 75 | Optional | Address line 3. | | city **Type**: String **Maximum Length**: 50 | Optional | Address city. | | state **Type**: String **Maximum Length**: 30 | Optional | Address state in ISO 3166‑2 format. | | countryCode **Type**: String | Optional | Address country code in ISO 3166‑1 alpha‑2 country code format. | | zip **Type**: String **Maximum Length**: 16 | Optional | Address zip/postal code. | | createTime **Type**: String (Numeric), UTC Unix epoch | Optional | Date and time the address was created. | | lastUsedTime **Type**: String (Numeric), UTC Unix epoch | Optional | Date and time the address was last used. | Dcf --- | Data Element | Required? | Description | |---------------------------------------------------|-----------|---------------------------------| | applicationType **Type**: ApplicationType | Optional | Type of environment of the DCF. | | uri **Type**: String **Maximum Length**: 1024 | Optional | DCF URI. | | logoUri **Type**: String **Maximum Length**: 1024 | Optional | Logo image URI provided by DCF. | | name **Type**: String **Maximum Length**: 60 | Optional | Legal name of the DCF. | MaskedConsumer -------------- | Data Element | Required? | Description | |---------------------------------------------------------------------|-------------|-----------------------------------------------------------| | srcConsumerId **Type**: String Universally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. | | maskedConsumerIdentity **Type** : MaskedConsumerIdentity | Conditional | Masked value of the primary verifiable consumer identity. | | maskedEmailAddress **Type**: String **Maximum Length**: 255 | Optional | Masked consumer email address. | MaskedConsumerIdentity ---------------------- | Data Element | Required? | Description | |--------------------------------------------------------------|-----------|------------------------------------------------------------------| | identityProvider **Type** : IdentityProvider | Optional | Entity or organization that collected and verified the identity. | | identityType **Type** : ConsumerIdentityType | Optional | Type of consumer identity transmitted or collected. | | maskedIdentityValue **Type**: String **Maximum Length**: 255 | Required | Masked identity value. | Response Attributes {#uctp-getcards-response} ============================================= | Field | Required? | Description | |-------------------------------------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | actionCode **Type**: ActionCode enum | Required | A code indicating the behavior to be handled by the SRC Initiator. Values applicable: * SUCCESS * PENDING_CONSUMER_IDV * ADD_CARD * ERROR | | profiles **Type** : List\<SrcProfile\> | Required | List of SRC profile(s) associated with each recognized consumer identity. If actionCode is SUCCESS and no SRC profiles are recognized, Or If actionCode is PENDING_CONSUMER_IDV or ADD_CARD, then an empty list is returned. | | maskedValidationChannel **Type**: String | Conditional | Masked value of the channel (e.g. email) that the SRC System used to deliver the validation data (e.g. OTP). Conditionality: Required when actionCode is PENDING_CONSUMER_IDV. | | supportedValidationChannels **Type**: List\<IdentityValidationChannel\> | Conditional | List of additional channels that are supported and can be used to perform identity validation. If returned by the SRC System, these choices may be presented to the consumer. Conditionality: Optionally returned when actionCode is PENDING_CONSUMER_IDV and returned by the SRC System. | SrcProfile ---------- |---------------------------------------------------------------|-----------|-------------------------------------------------------------------------| | Data Element | Required? | Description | | maskedCards **Type**: List\<MaskedCard\> See MaskedCard | Required | Masked card data associated with the SRC profile. May be an empty list. | | maskedConsumer **Type**: MaskedConsumer See MaskedConsumer | Optional | Masked consumer data associated with the SRC profile. | MaskedCard ---------- |-----------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | srcDigitalCardId **Type**: String Universally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for checkout. | | panBin **Type**: String (Numeric) **Maximum Length**: (PAN Length -10) | Required | First significant digits of the PAN included in an unmasked form. | | panLastFour **Type**: String (Numeric) **Length**: 4 | Required | Last four digits of the PAN in an unmasked form. | | panExpirationMonth **Type**: String (Numeric) **Length**: 2 | C | Expiration month expressed as a two-digit month (MM) used for presentation purposes. Conditionality: Required when specified for the card (PAN). | | panExpirationYear **Type**: String (Numeric) **Length**: 4 | C | Expiration year expressed as four-digit calendar year (YYYY), used for presentation purposes. Conditionality: Required when specified for the card (PAN). | | tokenBinRange **Type**: String (Numeric) **Maximum Length**: (Payment Token Length -10) | C | Specific BIN range or subset of the BIN Range that has been designated only for the purpose of issuing payment tokens in an unmasked form. Conditionality: Required when a payment token is used. | | tokenLastFour **Type**: String (Numeric) **Length**: 4 | C | Last four digits of the payment token in an unmasked form. Conditionality: Required when a payment token is used. | | digitalCardData **Type** : DigitalCardData See DigitalCardData | Required | Contains digital card information that is used in the acceptance environment and user interface. It refers to the actual PAN or payment token without disclosing either. | | maskedCardholderFullName **Type**: String **Maximum Length**: 100 | Optional | Masked cardholder name. | | maskedCardholderFirstName **Type**: String **Maximum Length**: 50 | Optional | Masked cardholder first name. | | maskedCardholderLastName **Type**: String **Maximum Length**: 50 | Optional | Masked cardholder last name. | | paymentCardDescriptor **Type**: String **Maximum Length**: 32 | Optional | Conveys the card brand defined within an SRC System. | | paymentCardType **Type**: String **Maximum Length**: 32 | Optional | Conveys the card type. | | digitalCardFeatures **Type** : List\<DigitalCardFeature\> See DigitalCardFeature | Optional | Attributes related to the digital card features that should be displayed to the consumer. | | countryCode **Type**: String ISO 3166-1 alpha 2 country code | Optional | Country code of issuance associated with the card issuer's BIN license. | | maskedBillingAddress **Type** : MaskedAddress See MaskedAddress | Optional | Masked billing address associated with the card. | | dcf **Type**: Dcf See Dcf | Optional | Digital Card Facilitator (DCF) associated with the card. It is present only when the MaskedCard is used in the Checkout or Get Payload operation. | | paymentAccountReference **Type**: String **Maximum Length**: 29 | Optional | A non-financial reference assigned to each unique PAN and used to link a payment account represented by that PAN to affiliated payment tokens. | | dateOfCardCreated **Type**: String (Numeric) UTC time in Unix epoch format | Required | Date when card was enrolled into the SRC System. | | dateOfCardLastUsed **Type**: String (Numeric) UTC time in Unix epoch format | Optional | Date when card was last used for an SRC transaction. | DigitalCardData --------------- |-----------------------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | status **Type**: DigitalCardStatus See DigitalCardStatus enum | Required | State of the digital card. | | presentationName **Type**: String **Maximum Length**: 64 | Optional | Presentation text created by the consumer to enable recognition of the PAN. This value is defined by the consumer (e.g. nickname). | | descriptorName **Type**: String **Maximum Length**: 64 | Required | Presentation text defined by the SRC System that describes the PAN presented as a digital card. | | artUri **Type**: String **Maximum Length**: 1024 | Required | URI that hosts the card art image to be used for presentation purposes. Can be provided by SRC Issuer (SRCPI). | | artHeight **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Height of the card art in pixels. | | artWidth **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Width of the card art in pixels. | | pendingEvents **Type**: List\<CardPendingEvent\> See CardPendingEvent enum | C | Set of events that are pending completion. Conditionality: Required when the value of status is set to PENDING. | | authenticationMethods List\<AuthenticationMethod\> See AuthenticationMethod | Optional | List of available authentication methods. May be provided when SRC System identifies a need to perform verification. | DigitalCardStatus ----------------- |-------------------|--------------------------------------------| | Enumeration Name | Possible Values | | DigitalCardStatus | ACTIVE SUSPENDED EXPIRED PENDING CANCELLED | CardPendingEvent ---------------- |------------------|---------------------------------------------------------------------------------| | Enumeration Name | Possible Values | | CardPendingEvent | PENDING_AVS PENDING_CSC PENDING_CONSUMER_IDV PENDING_ CARDHOLDER_AUTHENTICATION | AuthenticationMethod -------------------- |-----------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | authenticationMethodType **Type**: AuthenticationMethodType See AuthenticationMethodType enum | Required | SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not. | | authenticationSubject **Type**: AuthenticationSubject See AuthenticationSubject enum | Required | Authentication subject. | | uriData **Type**: UriData See UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then AssuranceData, AuthenticationStatus, AuthenticationResult and any relevant session ids should be provided back asynchronously when authentication completes. It can be achieved by cross origin post message between the windows i.e. the caller and the authenticator. | | authenticationCredentialReference **Type**: String **Maximum Length**: 255 | Optional | May be provided by the identity provider once an authentication is initiated to qualify the nature of the authentication method (e.g. for SMS_OTP, this may include the masked mobile number "\*\*\*-\*\*\*-1234", which can be displayed to the consumer to aid method selection). | | methodAttributes **Type**: JSONObject | Optional | Attributes associated with the authentication method type. (See AuthenticationMethod Attributes JSON Values) | AuthenticationMethod MethodAttributes JSON Values The contents of methodAttributes depends on the value of authenticationMethodType and on the API operation / SDK method being called. The methodAttributes is included as follows: Within the Checkout response for authenticate flow. As part of AuthenticationMethod within the Checkout request for authenticate flow. If authenticationMethodType is any of the following. CSC_VALIDATION |--------------------------------------------------------|---------------------| | Data Element | Description | | cardSecurityCode **Type** : String, **Length**: 3 or 4 | Card Security Code. | If authenticationMethodType is any of the following. SMS_OTP EMAIL_OTP |----------------------------------------------------|-------------------------| | Data Element | Description | | otpValue **Type** : String, **Maximum Length**: 16 | OTP value. | | stepUpIdentifier **Type**: String | Step-up identification. | If authenticationMethodType is any of the following. APP_AUTHENTICATON |-----------------------------------|-------------------------| | Data Element | Description | | stepUpIdentifier **Type**: String | Step-up identification. | If authenticationMethodType is any of the following. 3DS |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Description | | challengeIndicator **Type**: String | Challenge indicator value related to 3DS authentication. For SRC orchestrated 3DS is authentication method, SRCIs can specify the preference of challenge indicator here. Please refer to EMV 3DS specification for more details. Note: If no preference provided, SRC will set up the default value of 01 for 3DS and 04 when followed by FIDO registration. If value is set to 05 by the SRCI then do not override the indicator to 03 though it is a FIDO compliant device. Possible Values are: 01 - No preference 02 - No challenge requested 03 - Challenge requested (3DS Requestor Preference) 04 - Challenge requested (Mandate) 05 - No challenge requested (transactional risk analysis is already performed) 06 - No challenge requested (Data share only) 07 - No challenge requested (strong consumer authentication is already performed) 08 - No challenge requested (utilize trust list exemption if no challenge required) 09 - Challenge requested (trust list prompt requested if challenge required) | AuthenticationMethodType ------------------------ |--------------------------|---------------------------------------------------------| | Enumeration Name | Possible Values | | AuthenticationMethodType | CSC_VALIDATION EMAIL_OTP SMS_OTP APP_AUTHENTICATION 3DS | AuthenticationSubject --------------------- |-----------------------|--------------------------| | Enumeration Name | Possible Values | | AuthenticationSubject | CARD CARDHOLDER CONSUMER | UriData ------- |-----------------------------------------------|-----------|--------------------------------------------------------| | Data Element | Required? | Description | | uri **Type**: String **Maximum Length**: 2048 | Required | Specifies the URI for the given authentication method. | | uriType **Type**: UriType See UriType enum | Required | URI type. | UriType ------- |------------------|-----------------| | Enumeration Name | Possible Values | | UriType | APP_URI WEB_URI | DigitalCardFeature ------------------ |--------------------------------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------------| | Data Element | Required? | Description | | content **Type**: String **Maximum Length**: 1024 | Required | Content of the digital card feature. The value is specific for the 'contentType'. | | contentType **Type**: DigitalCardFeatureContentType See DigitalCardFeatureContentType enum | Required | Type of the content of the digital card feature. | | style **Type**: String **Maximum Length**: 1024 | Optional | URL of a CSS style sheet that describes how to present the card feature. | | width **Type**: String (Numeric) | Optional | Width to be applied to display of card feature. | | height **Type**: String (Numeric) | | | DigitalCardFeatureContentType ----------------------------- |-------------------------------|--------------------------------------------| | Enumeration Name | Possible Values | | DigitalCardFeatureContentType | TEXT_STRING IMAGE_URL CONTENT_URL LINK_URL | MaskedAddress ------------- The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/ |------------------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | addressId **Type**: String Universally Unique Identifier (UUID) | Required | Identifier used to point to the address. | | name **Type**: String **Maximum Length**: 100 | Optional | Name of the individual receiving the delivered goods or service. Only applicable for the shipping address. | | line1 **Type**: String **Maximum Length**: 75 | Optional | Address line 1. | | line2 **Type**: String **Maximum Length**: 75 | Optional | Address line 2. | | line3 **Type**: String **Maximum Length**: 75 | Optional | Address line 3. | | city **Type**: String **Maximum Length**: 50 | O | Address city. | | state **Type**: String **Maximum Length**: 30 | Optional | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, followed by an alphanumeric string of 3 characters representing the state or sub-division. | | countryCode **Type**: String ISO 3166-1 alpha 2 country code | Optional | Address country code. | | zip **Type**: String **Maximum Length**: 16 | Optional | Address zip/postal code. | | createTime **Type**: String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was created. | | lastUsedTime **Type**: String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was last used. | Dcf --- |--------------------------------------------------------------------|-----------|-------------------------------------------------------------| | Data Element | Required? | Description | | applicationType **Type**: ApplicationType See ApplicationType enum | Optional | Type of the environment of the DCF. | | uri **Type**: String **Maximum Length**: 1024 | Optional | DCF URI as provided by DCF. | | logoUri **Type**: String **Maximum Length**: 1024 | Optional | Logo image URI provided by the DCF to support presentation. | | name **Type**: String **Maximum Length**: 60 | Optional | Legal Name of DCF onboarded to the SRC System. | MaskedConsumer -------------- |------------------------------------------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | srcConsumerId **Type**: String Universally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. Note: Optionally may be returned in Get Payload operation. | | maskedConsumerIdentity **Type**: MaskedConsumerIdentity See MaskedConsumerIdentity | C | Masked value of the primary verifiable consumer identity within an SRC profile (e.g. an email address or a mobile phone number). Conditionality: Returned in Get Payload operation. | | maskedEmailAddress **Type**: String **Maximum Length**: 255 | Optional | Masked consumer email address. | MaskedConsumerIdentity ---------------------- |---------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | identityProvider **Type**: IdentityProvider See IdentityProvider enum | Optional | Entity or organization that collected and verifies the identity. The default value is SRC. | | identityType **Type**: ConsumerIdentityType See ConsumerIdentityType enum | Optional | Type of consumer identity transmitted or collected. | | maskedIdentityValue **Type**: String **Maximum Length**: 255 | Required | Masked consumer identifier value. For example, masked email address or masked mobile phone number. | Handle Errors {#uctp-getcards-errors} ===================================== An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could not be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ACCT_FRAUD` | The user account was locked or disabled. | | `ACCT_INACCESSIBLE` | The user account exists but is not currently accessible. | | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `AUTH_INVALID` | Invalid federated id token. | | `CONSUMER_ID_FORMAT_INVALID` | Invalid consumer identity. | | `CONSUMER_ID_FORMAT_UNSUPPORTED` | Unsupported consumer identity type. | | `CONSUMER_ID_MISSING` | The consumerIdentity parameter is missing. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `OTP_SEND_FAILED` | The OTP could not be sent to the recipient. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `RETRIES_EXCEEDED` | The limit for the number of retries exceeded. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `UNKNOWN_ERROR` | Unknown error. | | `VALIDATION_DATA_EXPIRED` | The validationData is expired. | | `VALIDATION_DATA_INVALID` | The supplied validationData is invalid. | | `VALIDATION_DATA_MISSING` | The validationData parameter is missing. | [Error Codes] checkout() {#uctp-api-specs-checkout} ===================================== dpaTransactionOptions is an optional field in a checkout() request. You can include the dpaTransactionOptions field in the `checkout()` request if your system supports it. You must consider this information if you include the dpaTransactionOptions field in your request: * You must include the transaction amount and currency in the backend of the request payload that is sent to `/sessions` API. The values that are included in the request to the `/sessions` API are used and any value included in dpaTransactionOptions are ignored. * You must configure authentication fields in the `Business Center`. The values of these fields are retrieved from the merchant or partner profiles and not from the dpaTransactionOptions field. The checkout() method uses three types of keys: * **JWT validation keys** : The checkout response from vsdk.checkout() is a signed JWT with the payment credentials. The response must be verified server-side by retrieving the RSA public key from `https://api.cybersource.com``/flex/v2/public-keys` using the `kid` from the header of each JWT. `Cybersource` recommends that you do not skip this step, as this verification exposes the integration to payload tampering. For information about JWT validation keys, see [JWT Validation Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-jwt-keys.md ""). * **Client-side PAN encryption keys** : When you add a card to `Unified Click to Pay`, the customer manually enters their card details in the UI. The raw PAN must be JWE-encrypted in the browser before it is passed to checkout(encryptedCard). The encryption key is a per-network RSA JWK from the `/sessions` API response from paymentConfigurations.\[SRCVISA\|SRCMASTERCARD\|SRCAMEX\].panEncryptionKey. The encyrypted key is selected using the PAN's BIN range. For information about client-side PAN encryption keys, see [Client-Side PAN Encryption Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-pan-enc-keys.md ""). * **Token Management MLE keys** : The checkout() response can include PCI/PII data that is in the encryptedPayload field. This data is encrypted by `Cybersource` using the merchant's RSA public key uploaded to the `Cybersource` `Business Center`. The merchant decrypts it server-side using their corresponding private key. For information about Token Management MLE keys, see [Token Management MLE Keys](/docs/cybs/en-us/unified-click-to-pay/developer/all/rest/unified-click-to-pay/uctp-appendix-intro/uctp-keys/uctp-keys-tms-mle-keys.md ""). {#uctp-api-specs-checkout_ul_off_3gy_x3c} Your checkout() request must have this syntax: ``` checkout({ conditional String srcDigitalCardId; conditional JWE<Card> encryptedCard; optional Consumer consumer; optional DpaTransactionOptions dpaTransactionOptions; optional PayloadTypeIndicator payloadTypeIndicatorCheckout; conditional Window windowRef; conditional ComplianceSettings complianceSettings; optional AssuranceData assuranceData; }) ``` Request Parameters {#uctp-java-checkout} ======================================== Your checkout() request can include these parameters: Request Parameters ------------------ | Field | Required? | Description | |-------------------------------------------------------------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | srcDigitalCardId **Type**: String | Required for checkout when a card is selected from a candidate list. | A reference identifier of the card to be used for checkout. > IMPORTANT > If srcDigitalCardId and encryptedCard both are provided then srcDigitalCardId takes precedence. | | encryptedCard **Type**: JWE | Required for a combined flow where this card is being enrolled during checkout. | The card being enrolled with the SRC System. > IMPORTANT > If srcDigitalCardId and encryptedCard both are provided then srcDigitalCardId takes precedence. | | consumer **Type** : Consumer | Optional | Consumer identity or profile information collected by an SRCi. | | complianceSettings **Type** : ComplianceSettings | Conditional | The consumer's compliance settings. | | assuranceData **Type** : AssuranceData | Optional | Assurance data supplied to support risk management. | | dpaTransactionOptions **Type** : DpaTransactionOptions | Optional | Options to override DPA‑registered transaction settings. | | transactionAmount **Type** : TransactionAmount | Optional | | | paymentOptions **Type** : List\<PaymentOptions\> | Optional | | | payloadTypeIndicatorCheckout **Type** : PayloadTypeIndicator enum | Optional | Indicates the scope of encrypted payload in the response. Possible values: * `FULL` * `SUMMARY` | | windowRef **Type** : Window | Conditional | Reference to a browsing context (iframe, popup, etc.). | [Request Parameters and Descriptions] Card ---- | Data Element | Required? | Description | |----------------------------------------------------------------------------------------------|-------------|----------------------------------| | primaryAccountNumber **Type**: String (Numeric) **Minimum Length**: 9 **Maximum Length**: 19 | Required | The account number of the card. | | panExpirationMonth **Type**: String (Numeric) **Length**: 2 | Conditional | Expiration month in MM format. | | panExpirationYear **Type**: String (Numeric) **Length**: 4 | Conditional | Expiration year in YYYY format. | | cardSecurityCode **Type**: String (Numeric) **Maximum Length**: 4 | Conditional | Card security code. | | cardholderFullName **Type**: String **Maximum Length**: 100 | Conditional | Cardholder name. | | cardholderFirstName **Type**: String **Maximum Length**: 50 | Optional | Cardholder first name. | | cardholderLastName **Type**: String **Maximum Length**: 50 | Optional | Cardholder last name. | | billingAddress **Type**: Address | Optional | Billing address. | | paymentAccountReference **Type**: String **Maximum Length**: 29 | Optional | Reference linking PAN to tokens. | BillingAddress -------------- | Data Element | Required? | Description | |----------------------------------|-------------|-------------------------------------------| | billingAddress **Type**: Address | Conditional | Billing address associated with the card. | Address ------- The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/ | Data Element | Required? | Description | |-----------------------------------------------------------------|------------------------------------------|-------------------------------------------------------------------| | addressId **Type**: String Universally Unique Identifier (UUID) | Optional | Reference identifier of the address in the SRC System. | | name **Type**: String **Maximum Length**: 100 | Optional | Name of the consumer. | | line1 **Type**: String **Maximum Length**: 75 | Required if this is a shipping address. | Address line 1 | | line2 **Type**: String **Maximum Length**: 75 | Optional | Address line 2. | | line3 **Type**: String **Maximum Length**: 75 | Optional | Address line 3. | | city **Type**: String **Maximum Length**: 50 | Required if this is a shipping address. | Address city. | | state **Type**: String **Maximum Length**: 30 | Required if this is a shipping address. | Address state. | | zip **Type**: String **Maximum Length**: 16 | Required if applicable for that country. | Address zip/postal code. | | countryCode **Type**: String | Required | Address country code in ISO 3166‑1 alpha‑2 country code format. | | createTime **Type**: String (Numeric) | Optional | Date and time the address was created in UTC Unix epoch format. | | lastUsedTime **Type**: String (Numeric) | Optional | Date and time the address was last used in UTC Unix epoch format. | Consumer -------- | Data Element | Required? | Description | |------------------------------------------------------------|-------------|-------------------------------------------------------------------------| | consumerIdentity **Type** : ConsumerIdentity | Required | Primary verifiable consumer identity. | | firstName **Type**: String **Maximum Length**: 50 | Optional | Consumer-provided first name. | | lastName **Type**: String **Maximum Length**: 50 | Optional | Consumer-provided last name. | | fullName **Type**: String **Maximum Length**: 100 | Conditional | Consumer-provided full name. | | emailAddress **Type**: String **Maximum Length**: 255 | Optional | Consumer email address. | | mobileNumber **Type** : PhoneNumber | Conditional | Consumer mobile number. | | nationalIdentifier **Type**: String **Maximum Length**: 20 | Optional | National identifier. | | countryCode **Type**: String | Optional | Country code associated with the consumer in ISO 3166‑1 alpha‑2 format. | | locale **Type**: String | Optional | Consumer locale. | ConsumerIdentity ---------------- | Data Element | Required? | Description | |--------------------------------------------------------|-----------|---------------------------------------------------------------------------------------| | identityProvider **Type** : IdentityProvider | Optional | Entity or organization that verified the identity. Possible value: * `SRC` | | identityType **Type** : ConsumerIdentityType | Required | Type of consumer identity. Possible values: * `EMAIL_ADDRESS` * `MOBILE_PHONE_NUMBER` | | identityValue **Type**: String **Maximum Length**: 255 | Required | Consumer identity value. | PhoneNumber ----------- | Data Element | Required? | Description | |---------------------------------------------------------------------------|-----------|-------------------------------------------------------------------------| | countryCode **Type**: String **Minimum Length**: 1 **Maximum Length**: 4 | Required | Phone number country code per ITU in international calling code format. | | phoneNumber **Type**: String **Minimum Length**: 4 **Maximum Length**: 14 | Required | Phone number without country code. | ComplianceSettings ------------------ | Data Element | Required? | Description | |-----------------------------------------------------------------|-----------|-----------------------------------| | complianceResources **Type** : List\<ComplianceResource\> | Required | One or more compliance resources. | ComplianceResource ------------------ | Data Element | Required? | Description | |-------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------| | complianceType **Type** : ComplianceType | Required | Compliance type. Possible values: * `PRIVACY_POLICY` * `REMEMBER_ME` * `TERMS_AND_CONDITIONS` | | uri **Type**: String **Maximum Length**: 1024 | Required | URI or URL. | | version **Type**: String **Maximum Length**: 10 | Optional | Version. | | datePublished **Type**: String | Optional | Date published in UTC Unix epoch. | AssuranceData ------------- | Data Element | Required? | Description | |------------------------------------------------------------|-----------|--------------------------------------| | verificationData **Type** : List\<VerificationData\> | Required | Verification data structures. | | eci **Type**: String **Maximum Length**: 2 | Optional | E-commerce authentication indicator. | Response Attributes {#uctp-java-checkout-response} ================================================== ****Response Attributes**** |------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Field | Required? | Description | | actionCode **Type**: ActionCode enum | Required | A code indicating the behavior to be handled by the SRC Initiator. Values applicable: SUCCESS ERROR | | checkoutResponse **Type**: JWS \<CheckoutPayloadResponse\> | C | Signed checkout response. Conditionality: Required when the actionCode is set to SUCCESS. encryptedPayload will be not present within the checkoutResponse when: payloadTypeIndicatorCheckout is set to SUMMARY. | | bindingStatus **Type**: BindingStatus enum | Optional | Status of the binding/unbinding request. The value BIND indicates that the consumer has chosen to be "remembered" on the consumer device. | ActionCode ---------- |------------------|---------------------------------------------------------------------------------------| | Enumeration Name | Possible Values | | ActionCode | SUCCESS PENDING_CONSUMER_IDV PENDING_AUTHENTICATION CHANGE_CARD ADD_CARD CANCEL ERROR | CheckoutPayloadResponse ----------------------- |-----------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | srciTransactionId **Type**: String **Maximum Length**: 255 | Required | A unique identifier generated by Visa SRCi. | | maskedConsumer **Type**: MaskedConsumer See MaskedConsumer | C | Masked consumer data associated with the SRC profile. Conditionality: Required for the Checkout and Get Payload operations if the associated SRC profile contains consumer data. | | maskedCard **Type**: MaskedCard See MaskedCard | Required | Masked card data. | | shippingAddressZip **Type**: String **Maximum Length**: 16 | C | Zip or postal code of selected shipping address. Conditionality: Required, depending on the dpaShippingPreference option in the dpaTransactionOptions structure. | | shippingAddressCountryCode **Type**: String ISO 3166-1 alpha-2 country code | C | Country code of selected shipping address. Conditionality: Required, depending on the dpaShippingPreference option in the dpaTransactionOptions structure. | | customOutputData **Type**: JSONObject | Optional | SRC System-specific data. | | assuranceData **Type**: AssuranceData See AssuranceData | Optional | Assurance data related to the checkout flow. | | encryptedPayload **Type**: JWE\<Payload\> See Payload | C | SRC Payload. Encrypted for the specific recipient. Conditionality: encryptedPayload will be not present when: payloadTypeIndicatorCheckout is set to SUMMARY or actionCode in checkout operation response is set to PENDING_AUTHENTICATION. | MaskedConsumer -------------- |------------------------------------------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | srcConsumerId **Type**: String Universally Unique Identifier (UUID) | Optional | Reference identifier generated by the SRC System. Note: Optionally may be returned in Get Payload operation. | | maskedConsumerIdentity **Type**: MaskedConsumerIdentity See MaskedConsumerIdentity | C | Masked value of the primary verifiable consumer identity within an SRC profile (e.g. an email address or a mobile phone number). Conditionality: Returned in Get Payload operation. | | maskedEmailAddress **Type**: String **Maximum Length**: 255 | Optional | Masked consumer email address. | MaskedConsumerIdentity ---------------------- |---------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | identityProvider **Type**: IdentityProvider See IdentityProvider enum | Optional | Entity or organization that collected and verifies the identity. The default value is SRC. | | identityType **Type**: ConsumerIdentityType See ConsumerIdentityType enum | Optional | Type of consumer identity transmitted or collected. | | maskedIdentityValue **Type**: String **Maximum Length**: 255 | Required | Masked consumer identifier value. For example, masked email address or masked mobile phone number. | ConsumerIdentityType -------------------- |----------------------|-----------------------------------| | Enumeration Name | Possible Values | | ConsumerIdentityType | EMAIL_ADDRESS MOBILE_PHONE_NUMBER | MaskedCard ---------- |-----------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | srcDigitalCardId **Type**: String Universally Unique Identifier (UUID) | Required | A reference identifier of the card to be used for checkout. | | panBin **Type**: String (Numeric) **Maximum Length**: (PAN Length -10) | Required | First significant digits of the PAN included in an unmasked form. | | panLastFour **Type**: String (Numeric) **Length**: 4 | Required | Last four digits of the PAN in an unmasked form. | | panExpirationMonth **Type**: String (Numeric) **Length**: 2 | C | Expiration month expressed as a two-digit month (MM) used for presentation purposes. Conditionality: Required when specified for the card (PAN). | | panExpirationYear **Type**: String (Numeric) **Length**: 4 | C | Expiration year expressed as four-digit calendar year (YYYY), used for presentation purposes. Conditionality: Required when specified for the card (PAN). | | tokenBinRange **Type**: String (Numeric) **Maximum Length**: (Payment Token Length -10) | C | Specific BIN range or subset of the BIN Range that has been designated only for the purpose of issuing payment tokens in an unmasked form. Conditionality: Required when a payment token is used. | | tokenLastFour **Type**: String (Numeric) **Length**: 4 | C | Last four digits of the payment token in an unmasked form. Conditionality: Required when a payment token is used. | | digitalCardData **Type**: DigitalCardData See DigitalCardData | Required | Contains digital card information that is used in the acceptance environment and user interface. It refers to the actual PAN or payment token without disclosing either. | | maskedCardholderFullName **Type**: String **Maximum Length**: 100 | Optional | Masked cardholder name. | | maskedCardholderFirstName **Type**: String **Maximum Length**: 50 | Optional | Masked cardholder first name. | | maskedCardholderLastName **Type**: String **Maximum Length**: 50 | Optional | Masked cardholder last name. | | paymentCardDescriptor **Type**: String **Maximum Length**: 32 | Optional | Conveys the card brand defined within an SRC System. | | paymentCardType **Type**: String **Maximum Length**: 32 | Optional | Conveys the card type. | | digitalCardFeatures **Type**: List\<DigitalCardFeature\> See DigitalCardFeature | Optional | Attributes related to the digital card features that should be displayed to the consumer. | | countryCode **Type**: String ISO 3166-1 alpha 2 country code | Optional | Country code of issuance associated with the card issuer's BIN license. | | maskedBillingAddress **Type**: MaskedAddress See MaskedAddress | Optional | Masked billing address associated with the card. | | dcf **Type**: Dcf See Dcf | Optional | Digital Card Facilitator (DCF) associated with the card. It is present only when the MaskedCard is used in the Checkout or Get Payload operation. | | paymentAccountReference **Type**: String **Maximum Length**: 29 | Optional | A non-financial reference assigned to each unique PAN and used to link a payment account represented by that PAN to affiliated payment tokens. | | dateOfCardCreated **Type**: String (Numeric) UTC time in Unix epoch format | Required | Date when card was enrolled into the SRC System. | | dateOfCardLastUsed **Type**: String (Numeric) UTC time in Unix epoch format | | | DigitalCardData --------------- |-----------------------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | status **Type**: DigitalCardStatus See DigitalCardStatus enum | Required | State of the digital card. | | presentationName **Type**: String **Maximum Length**: 64 | Optional | Presentation text created by the consumer to enable recognition of the PAN. This value is defined by the consumer (e.g. nickname). | | descriptorName **Type**: String **Maximum Length**: 64 | Required | Presentation text defined by the SRC System that describes the PAN presented as a digital card. | | artUri **Type**: String **Maximum Length**: 1024 | Required | URI that hosts the card art image to be used for presentation purposes. Can be provided by SRC Issuer (SRCPI). | | artHeight **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Height of the card art in pixels. | | artWidth **Type**: String (Numeric) **Maximum Length**: 4096 | Optional | Width of the card art in pixels. | | pendingEvents **Type**: List\<CardPendingEvent\> See CardPendingEvent enum | C | Set of events that are pending completion. Conditionality: Required when the value of status is set to PENDING. | | authenticationMethods List\<AuthenticationMethod\> See AuthenticationMethod | Optional | List of available authentication methods. May be provided when SRC System identifies a need to perform verification. | DigitalCardStatus ----------------- |-------------------|--------------------------------------------| | Enumeration Name | Possible Values | | DigitalCardStatus | ACTIVE SUSPENDED EXPIRED PENDING CANCELLED | CardPendingEvent ---------------- |------------------|---------------------------------------------------------------------------------| | Enumeration Name | Possible Values | | CardPendingEvent | PENDING_AVS PENDING_CSC PENDING_CONSUMER_IDV PENDING_ CARDHOLDER_AUTHENTICATION | AuthenticationMethod -------------------- |-----------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | authenticationMethodType **Type**: AuthenticationMethodType See AuthenticationMethodType enum | Required | SRCi to indicate for a particular transaction if Click to Pay needs to perform managed authentication or not. | | authenticationSubject **Type**: AuthenticationSubject See AuthenticationSubject enum | Required | Authentication subject. | | uriData **Type**: UriData See UriData | Optional | URI associated with the authentication method. When authentication is invoked by launching the URI then AssuranceData, AuthenticationStatus, AuthenticationResult and any relevant session ids should be provided back asynchronously when authentication completes. It can be achieved by cross origin post message between the windows i.e. the caller and the authenticator. | | authenticationCredentialReference **Type**: String **Maximum Length**: 255 | Optional | May be provided by the identity provider once an authentication is initiated to qualify the nature of the authentication method (e.g. for SMS_OTP, this may include the masked mobile number "\*\*\*-\*\*\*-1234", which can be displayed to the consumer to aid method selection). | | methodAttributes **Type**: JSONObject | Optional | Attributes associated with the authentication method type. (See AuthenticationMethod Attributes JSON Values) | AuthenticationMethod MethodAttributes JSON Values The contents of methodAttributes depends on the value of authenticationMethodType and on the API operation / SDK method being called. The methodAttributes is included as follows: Within the Checkout response for authenticate flow. As part of AuthenticationMethod within the Checkout request for authenticate flow. If authenticationMethodType is any of the following. CSC_VALIDATION |--------------------------------------------------------|---------------------| | Data Element | Description | | cardSecurityCode **Type** : String, **Length**: 3 or 4 | Card Security Code. | If authenticationMethodType is any of the following. SMS_OTP EMAIL_OTP |----------------------------------------------------|-------------------------| | Data Element | Description | | otpValue **Type** : String, **Maximum Length**: 16 | OTP value. | | stepUpIdentifier **Type**: String | Step-up identification. | If authenticationMethodType is any of the following. APP_AUTHENTICATON |-----------------------------------|-------------------------| | Data Element | Description | | stepUpIdentifier **Type**: String | Step-up identification. | If authenticationMethodType is any of the following. 3DS |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Description | | challengeIndicator **Type**: String | Challenge indicator value related to 3DS authentication. For SRC orchestrated 3DS is authentication method, SRCIs can specify the preference of challenge indicator here. Please refer to EMV 3DS specification for more details. Note: If no preference provided, SRC will set up the default value of 01 for 3DS and 04 when followed by FIDO registration. If value is set to 05 by the SRCI then do not override the indicator to 03 though it is a FIDO compliant device. Possible Values are: 01 - No preference 02 - No challenge requested 03 - Challenge requested (3DS Requestor Preference) 04 - Challenge requested (Mandate) 05 - No challenge requested (transactional risk analysis is already performed) 06 - No challenge requested (Data share only) 07 - No challenge requested (strong consumer authentication is already performed) 08 - No challenge requested (utilize trust list exemption if no challenge required) 09 - Challenge requested (trust list prompt requested if challenge required) | AuthenticationMethodType ------------------------ |--------------------------|---------------------------------------------------------| | Enumeration Name | Possible Values | | AuthenticationMethodType | CSC_VALIDATION EMAIL_OTP SMS_OTP APP_AUTHENTICATION 3DS | AuthenticationSubject --------------------- |-----------------------|--------------------------| | Enumeration Name | Possible Values | | AuthenticationSubject | CARD CARDHOLDER CONSUMER | UriData ------- |-----------------------------------------------|-----------|--------------------------------------------------------| | Data Element | Required? | Description | | uri **Type**: String **Maximum Length**: 2048 | Required | Specifies the URI for the given authentication method. | | uriType **Type**: UriType See UriType enum | Required | URI type. | UriType ------- |------------------|-----------------| | Enumeration Name | Possible Values | | UriType | APP_URI WEB_URI | DigitalCardFeature ------------------ |--------------------------------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------------| | Data Element | Required? | Description | | content **Type**: String **Maximum Length**: 1024 | Required | Content of the digital card feature. The value is specific for the 'contentType'. | | contentType **Type**: DigitalCardFeatureContentType See DigitalCardFeatureContentType enum | Required | Type of the content of the digital card feature. | | style **Type**: String **Maximum Length**: 1024 | Optional | URL of a CSS style sheet that describes how to present the card feature. | | width **Type**: String (Numeric) | Optional | Width to be applied to display of card feature. | | height **Type**: String (Numeric) | Optional | Height to be applied to display of card feature. | DigitalCardFeatureContentType ----------------------------- |-------------------------------|--------------------------------------------| | Enumeration Name | Possible Values | | DigitalCardFeatureContentType | TEXT_STRING IMAGE_URL CONTENT_URL LINK_URL | MaskedAddress ------------- The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/ |------------------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | addressId **Type**: String Universally Unique Identifier (UUID) | Required | Identifier used to point to the address. | | name **Type**: String **Maximum Length**: 100 | Optional | Name of the individual receiving the delivered goods or service. Only applicable for the shipping address. | | line1 **Type**: String **Maximum Length**: 75 | Optional | Address line 1. | | line2 **Type**: String **Maximum Length**: 75 | Optional | Address line 2. | | line3 **Type**: String **Maximum Length**: 75 | Optional | Address line 3. | | city **Type**: String **Maximum Length**: 50 | O | Address city. | | state **Type**: String **Maximum Length**: 30 | Optional | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, followed by an alphanumeric string of 3 characters representing the state or sub-division. | | countryCode **Type**: String ISO 3166-1 alpha 2 country code | Optional | Address country code. | | zip **Type**: String **Maximum Length**: 16 | Optional | Address zip/postal code. | | createTime **Type**: String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was created. | | lastUsedTime **Type**: String (Numeric), UTC time in Unix epoch format | Optional | Date and time the address was last used. | Dcf --- |--------------------------------------------------------------------|-----------|-------------------------------------------------------------| | Data Element | Required? | Description | | applicationType **Type**: ApplicationType See ApplicationType enum | Optional | Type of the environment of the DCF. | | uri **Type**: String **Maximum Length**: 1024 | Optional | DCF URI as provided by DCF. | | logoUri **Type**: String **Maximum Length**: 1024 | Optional | Logo image URI provided by the DCF to support presentation. | | name **Type**: String **Maximum Length**: 60 | Optional | Legal Name of DCF onboarded to the SRC System. | ApplicationType --------------- |------------------|-----------------------------------------| | Enumeration Name | Possible Values | | ApplicationType | IOT_DEVICE MOBILE_APP WEB_BROWSER OTHER | AssuranceData ------------- |--------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | verificationData **Type**: List\<VerificationData\> See VerificationData | Required | Set of verification data structures relating to different types of assurance. | | eci **Type**: String **Maximum Length**: 2 | Optional | If present, a value indicating the result of the authentication performed or attempted during a transaction. Use this value in the e-commerce authorization message to VisaNet. It is one of the following values: 05 -- Successful authentication 06 -- Authentication attempted 07 -- Authentication not performed | VerificationData ---------------- |--------------------------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | verificationType **Type**: VerificationType See VerificationType enum | Required | Type of the verification data. | | verificationEntity **Type**: String (Numeric) **Length**: 2 | Required | Entity performing the verification. See VerificationData Values | | verificationEvents **Type**: List\<String (Numeric)\> Array of two digit codes | Optional | Event where the verification occurred. See VerificationData Values | | verificationMethod **Type**: String (Numeric) **Length**: 2 | Required | Method of the verification. See VerificationData Values | | verificationResults **Type**: String (Numeric) **Length**: 2 | Required | Result of the verification. See VerificationData Values | | verificationTimestamp **Type**: String (Numeric) UTC time in Unix epoch format | Required | Date and time when the verification was conducted. | | methodResults **Type**: JSONObject | Optional | Attributes associated with the authentication method (See AuthenticationMethod MethodResults JSON Values). | VerificationData Values |-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Verification Type | Verification Entity | Verification Event | Verification Method | Verification Results | | CARDHOLDER | Entity performing or initiating Cardholder authentication. Valid values are: 01 SRC Initiator 02 SRC System (Not supported) 03 SRCPI 04 DCF (Not supported) 05 DPA (Not supported) 06-- 20 EMVCo future use (Not supported) 21 -- 99 SRC System specific (Not supported) | Event where the verification occurred. Possible Values are: 01 Payment transaction 02 Add card/Card enrollment 03 SRC Profile Access 04 Account Verification 05 -- 20 EMVCo future use (Not supported) 21 -- 99 SRC System specific (Not supported) | Card Issuer verification of the Cardholder. Possible Values are: 01 Use of an EMV 3-D Secure ACS (Not supported) 02 App based authentication 03 Federated login systems (Not supported) 04 A shared secret between the Card Issuer and the Cardholder such as One Time Passcode (OTP), activation code 05 No authentication (Not supported) 06 Proprietary method of authentication (Not supported) 07 FIDO2 (Not supported) 08 SPC (Not supported) 09 -- 20 EMVCo future use (Not supported) 21 -- 99 SRC System specific (See below) 21 -- Visa Token Service step--up: Device binding 22 -- Visa Token Service step--up: Cardholder verification | Indicates whether the Cardholder was verified or not, and what the results are when verified. Possible Values are: 01 Verified 02 Not Verified 03 Not performed 04 Not required 05 -- 20 EMVCo future use (Not supported) 21 -- 99 SRC System specific (See below) 21 -- Not allowed | AuthenticationMethod MethodResults JSON Values The methodResults is part of VerficationData which is part of AssuranceData, which is returned in the Checkout/Authenticate response. Within methodResults, threeDsData may contain data such as tranStatus and tranStatusReason when 3DS is completed. |-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Description | | transStatus **Type**: String | Whether a transaction qualifies as an authenticated transaction (for 3DS authentication). Format: It is one of the following string values: "Y" "R" "C" "N" "U" "A" "D" "I" | | dsTransId **Type**: String, UUID | ID assigned by the DS to identify the transaction (for 3DS authentication). | | acsTransId **Type**: String, UUID | ID assigned by the ACS to identify the transaction (for 3DS authentication). | Payload ------- |--------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | card **Type**: Card See Card | C | Card data associated with the PAN used for the purchase. Conditionality: Required when the: value of the relevant data element of type PayloadTypeIndicator was set to FULL; and SRC System determines that a PAN-based payload must be returned. A card is required if a token is not present. Card and token are mutually exclusive. | | token **Type**: PaymentToken See PaymentToken | C | Payment Token data associated with the PAN used for the purchase. Conditionality: Required when the: Value of the relevant data element of type PayloadTypeIndicator was set to FULL; and SRC System determines that a payment token-based payload must be returned. A token is required if a card is not present. Card and token are mutually exclusive. | | shippingAddress **Type**: Address See Address | C | Shipping address as required for the delivery of the goods/services being purchased. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Identified shipping address is available in the SRC Profile; and Shipping address was requested (based on dpaShippingPreference) | | consumerEmailAddress **Type**: String **Maximum Length**: 255 | C | Consumer-provided email address. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Email address is available in the SRC profile; and Email address was requested (consumerEmailAddressRequested set to true) | | consumerFirstName **Type** : String, **Maximum Length**: 50 | C | Consumer-provided first name. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Consumer first name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to true) | | consumerLastName **Type**: String **Maximum Length**: 50 | C | Consumer-provided last name. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Consumer last name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to true) | | consumerFullName **Type**: String **Maximum Length**: 100 | C | Consumer-provided name. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Consumer name is available in the SRC profile; and Consumer name was requested (consumerNameRequested set to true) | | consumerMobileNumber **Type**: PhoneNumber See Phonenumber | C | Consumer-provided mobile number. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Consumer mobile number is available in the SRC profile; and Consumer mobile number is requested (consumerPhoneNumberRequested set to true) | | consumerNationalIdentifier **Type**: String **Maximum Length**: 20 | Optional | Consumer national identifier as available in SRC profile. | | dynamicData **Type**: List\<DynamicData\> See DynamicData | Required | Dynamic data, generated using the dynamicDataType preference indicated in paymentOptions. | | billingAddress **Type**: Address See Address | C | Billing address associated with the card used for the purchase. Conditionality: Required when: The value of the relevant data element of type PayloadTypeIndicator was set to FULL; and Billing address is available in the SRC profile; and Billing address was requested (based on dpaBillingPreference or statically derived using the default configured during DPA Registration) | PaymentToken ------------ |-----------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | paymentToken **Type**: String ISO/IEC 7812 format | Required | The tokenized payment instrument. | | tokenExpirationMonth **Type**: String (Numeric) **Length**: 2 | Required | Expiration month expressed as a two-digit month (MM). | | tokenExpirationYear **Type**: String (Numeric) **Length**: 4 | C | Expiration year expressed as a four-digit calendar year (YYYY). | | cardholderFullName **Type**: String **Maximum Length**: 100 | Optional | Cardholder name. | | cardholderFirstName **Type**: String **Maximum Length**: 50 | Optional | Cardholder first name. | | cardholderLastName **Type**: String **Maximum Length**: 50 | Optional | Cardholder last name. | | paymentAccountReference **Type**: String **Maximum Length**: 29 | Optional | A non-financial reference assigned to each unique PAN and used to link a payment account represented by that PAN to affiliated payment tokens. | Address ------- The allowed characters for the address line 1, 2, and 3 are: .',:_#/()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõOEoeÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/ |-----------------------------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Element | Required? | Description | | addressId **Type**: String Universally Unique Identifier (UUID) | Optional | Reference identifier of the address in the SRC System. | | name **Type**: String **Maximum Length**: 100 | Optional | Name of the consumer. | | line1 **Type**: String **Maximum Length**: 75 | C | Address line 1 Conditionality: Required if this is a shipping address in a valid format for the country. | | line2 **Type**: String **Maximum Length**: 75 | Optional | Address line 2. | | line3 **Type**: String **Maximum Length**: 75 | Optional | Address line 3. | | city **Type**: String **Maximum Length**: 50 | C | Address city. Conditionality: Required if this is a shipping address in a valid format for the country. | | state **Type**: String **Maximum Length**: 30 | C | Address state. Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, followed by an alphanumeric string of 3 characters representing the state or sub-division Conditionality: Required if this is a shipping address in a valid format for the country. | | zip **Type**: String **Maximum Length**: 16 | C | Address zip/postal code. Conditionality: Required if this is a shipping address in a valid format for the country and has a postal code or zip code. | | countryCode **Type**: String ISO 3166-1 alpha-2 country code | Required | Address country code. | | createTime **Type**: String (Numeric) UTC time in Unix epoch format | Optional | Date and time the address was created. | | lastUsedTime **Type**: String (Numeric) UTC time in Unix epoch format | Optional | Date and time the address was last used. | PhoneNumber ----------- |----------------------------------------------------------------------------------------------------------|-----------|------------------------------------------------------------------------------------| | Data Element | Required? | Description | | countryCode **Type**: String Min **Length**: 1 **Maximum Length**: 4 (International calling code format) | Required | Phone number country code as defined by the International Telecommunication Union. | | phoneNumber **Type**: String Min **Length**: 4 **Maximum Length**: 14 | Required | Phone number without country code. | DynamicDataType --------------- |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| | Enumeration Name | Possible Values | | DynamicDataType | CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM CARD_APPLICATION_CRYPTOGRAM_LONG_FORM DYNAMIC_CARD_SECURITY_CODE CARDHOLDER_AUTHENTICATION_CRYPTOGRAM NONE | BindingStatus ------------- |------------------|-----------------| | Enumeration Name | Possible Values | | BindingStatus | BIND UNBIND | Handle Errors {#uctp-checkout-errors} ===================================== An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could not be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ACCT_INACCESSIBLE` | The user account exists but is not currently accessible. | | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `AUTH_INVALID` | Invalid federated id token. | | `AUTHENTICATION_METHOD_NOT_SUPPORTED` | The supplied authentication method is not supported. | | `BILLING_ADDRESS_REQUIRED` | The billing address must be provided. | | `CARD_ADD_FAILED` | Unable to add the card. | | `CARD_EXP_INVALID` | Invalid card expiry date. | | `CARD_INVALID` | Invalid primaryAccountNumber parameter. | | `CARD_MISSING` | The srcDigitalCardId or encryptedCard parameter is required but is missing. | | `CARD_NOT_RECOGNIZED` | The provided srcDigitalCardId is not recognized. | | `CARD_NOT_RECOGNIZED` | The provided srcDigitalCardId is not recognized. | | `CARD_SECURITY_CODE_MISSING` | Card Security Code (CSC) must be supplied in the encryptedCard parameter. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `OTP_SEND_FAILED` | The OTP could not be sent to the recipient. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `RETRIES_EXCEEDED` | The limit for the number of retries exceeded. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `TERMS_AND_CONDITIONS_ NOT_ACCEPTED` | Terms and conditions not accepted. | | `UNABLE_TO_CONNECT` | Unable to connect to or launch card experience. | | `UNKNOWN_ERROR` | Unknown error. | | `VALIDATION_DATA_EXPIRED` | The validationData is expired. | | `VALIDATION_DATA_INVALID` | The supplied validationData is invalid. | | `VALIDATION_DATA_MISSING` | The validationData parameter is missing. | [Error Codes] initiateIdentityValidation() {#uctp-api-specs-validate} ======================================================= Your initiateIdentityValidation() request must have this syntax: ``` initiateIdentityValidation({ optional String requestedValidationChannelId }) ``` Request Parameters {#uctp-java-init-validate} ============================================= Your initiateIdentityValidation() request can include these parameters: Request Parameters ------------------ | Field | Required? | Description | |-----------------------------------------------|-----------|-----------------------------------------------------------------------------------| | requestedValidationChannelId **Type**: String | Optional | Identifier of the channel over which the identity validation should be initiated. | Response Attributes {#uctp-java-init-validate-response} ======================================================= | Field | Required? | Description | |------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | maskedValidationChannel **Type**: String | Required | Masked value of the channel (e.g. email) that the SRC System used to deliver the validation data (e.g. OTP) **Example:**"sen\*\*\*\*\*@mailinator.com" | Handle Errors {#uctp-validate-errors} ===================================== An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could not be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `UNKNOWN_ERROR` | Unknown error. | [Error Codes] unbindAppInstance() {#uctp-api-specs-unbind-app} ================================================ Your unbindAppInstance() request must have this syntax: ``` unbindAppInstance() ``` Handle Errors {#uctp-unbind-app-errors} ======================================= An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could not be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [// Optional structure, used with input data validation error {// Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `UNKNOWN_ERROR` | Unknown error. | [Error Codes] Appendix {#uctp-appendix-intro} =============================== This section contains supplementary information for `Unified Click to Pay`. Client and Server Keys {#uctp-keys} =================================== You must use four types of cryptographic keys to complete your `Unified Click to Pay` integration: * API keys server side * JWT keys * PAN encryption keys * MLE keys The use of different types of encryption keys ensures that sensitive cardholder data is protected at every stage, and that each participant can only access the data that they are authorized to see. API Authentication Keys {#uctp_keys_api_keys} ============================================= API authentication keys are credentials that are required to authenticate every server-to-server request to `Cybersource` APIs. They are used to construct the HTTP signature header that `Cybersource` validates before processing requests. You must use valid API authentication keys to retrieve a capture context JWT and start the SDK integration workflow. API authentication keys are made up of three credentials: * `MERCHANT_ID`: Uniquely identifies the merchant account on `Cybersource`. You must include the `MERCHANT_ID` as the `v-c-merchant-id` HTTP header on every API request. Merchants must get the `MERCHANT_ID` from the `Cybersource` `Business Center` when their account is created. * `API_KEY_ID`: Identifies which hash-based message authentication code (HMAC) key is used for HTTP signature authentication. You must include the `API_KEY_ID` as the `keyid` parameter in the `Signature` header. Merchants may have multiple API keys. `Cybersource` uses the `API_KEY_ID` to determine which key to use for signature verification. * `API_SECRET_KEY`: The Base64-encoded HMAC shared secret that is paired with the `API_KEY_ID`. Used with the `HmacSHA256` algorithm to compute the HTTP Signature over specific request headers. This secret must never be logged, committed to source control, or sent to the client. These credentials are configured under Payment Configuration \> Key Management in the `Cybersource` `Business Center`: * Test URL: ` `` ` * Production URL: ` `` ` If you are unable to access this page, contact your sales representative. > IMPORTANT You must store these credentials on the server side in environment variables or a secrets manager. Do not hard-code the credentials in source files, embed them in client bundles, or expose them in API responses. If the credentials get exposed, an attacker could make authenticated API calls on the merchant's behalf. JavaScript Example: HTTP Signature Authentication ------------------------------------------------- ``` const crypto = require('crypto'); function generateSignatureHeaders(method, resourcePath, body) { const date = new Date().toUTCString(); const digest = body ? 'SHA-256=' + crypto.createHash('sha256').update(body).digest('base64') : null; const headers = ['host', 'date', '(request-target)']; const signingParts = [ `host: ${API_HOST}`, `date: ${date}`, `(request-target): ${method.toLowerCase()} ${resourcePath}` ]; if (body) { headers.push('digest', 'v-c-merchant-id'); signingParts.push(`digest: ${digest}`, `v-c-merchant-id: ${MERCHANT_ID}`); } else { headers.push('v-c-merchant-id'); signingParts.push(`v-c-merchant-id: ${MERCHANT_ID}`); } const signature = crypto .createHmac('sha256', Buffer.from(API_SECRET_KEY, 'base64')) .update(signingParts.join('\n')) .digest('base64'); return { host: API_HOST, date: date, 'v-c-merchant-id': MERCHANT_ID, signature: `keyid="${API_KEY_ID}", algorithm="HmacSHA256", headers="${headers.join(' ')}", signature="${signature}"`, 'Content-Type': 'application/json', ...(digest ? { digest } : {}) }; } // Make the capture context request const headers = generateSignatureHeaders('POST', '/uctp/v1/sessions', requestBody); ``` JWT Validation Keys {#uctp-keys-jwt-keys} ========================================= `Unified Click to Pay` uses JWTs to transfer data. These `Unified Click to Pay` integration elements are JWTs: * The capture context that is returned by the `/uctp/v1/sessions` request. You must verify this JWT immediately on your server to ensure that the SDK script URL, PAN encryption keys, and session configuration have not been tampered with. For information about `/uctp/v1/sessions` requests, see [Generate Unified Click to Pay Capture Context](https://developer.cybersource.com/api-reference-assets/index.md#unified-checkout_unified-click-to-pay-capture-context_generate-unified-click-to-pay-capture-context "") in the `Cybersource` API Reference. * The response that is returned by checkout(). You must verify this JWT on your server after you receive it from the client. Each JWT must be validated before you trust its contents. > IMPORTANT > The header of each JWT header contains a key ID field (` kid `) that references the specific RSA public key that ` Cybersource ` used to sign that token. The integrator must retrieve this public key from ` Cybersource ` and use it to verify the JWT's signature. If the signature is invalid, the JWT must be rejected. > JWT validation keys are composed of these elements located in the JWT header: * `kid`: Key ID that references the RSA public key that signed the JWT. Each JWT may have a different `kid`. * `alg`: The signing algorithm. This is often `RS256` (RSA with SHA-256). You can retrieve the RSA public key as a JSON Web Key from these endpoints: * **Test** : GET `https://apitest.cybersource.com``/flex/v2/public-keys/{kid}` * **Production** : GET `https://api.cybersource.com``/flex/v2/public-keys/{kid}` > IMPORTANT > You can store RSA public keys, however, ` Cybersource ` recommends that you use the keys from the URL. This ensures that you use the most current key. JavaScript Example: JWT Signature Authentication ------------------------------------------------ ``` async function verifyJwt(token) { const [headerB64, payloadB64, signatureB64] = token.split('.'); const header = JSON.parse(base64UrlDecode(headerB64)); // Fetch the public key using the kid from the JWT header const response = await fetch(`https://${API_HOST}/flex/v2/public-keys/${header.kid}`, { headers: generateSignatureHeaders('GET', `/flex/v2/public-keys/${header.kid}`, null) }); const jwk = await response.json(); const publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' }); // Verify the signature const signedData = `${headerB64}.${payloadB64}`; const signatureBuffer = base64UrlDecode(signatureB64); const valid = crypto.verify('RSA-SHA256', Buffer.from(signedData), publicKey, signatureBuffer); if (!valid) throw new Error('JWT signature verification failed'); return { header, payload: JSON.parse(base64UrlDecode(payloadB64)), signature: signatureB64, raw: token }; } ``` Client-Side PAN Encryption Keys {#uctp-keys-pan-enc-keys} ========================================================= During the guest checkout flow, the customer enters their card details such as the PAN, expiration date, CVV, and billing address directly into the merchant UI. This sensitive data must be encrypted before it is sent to `Click to Pay` for card enrollment and checkout. You can use PAN encryption keys to encrypt the sensitive data. Every card network provides an RSA public key for encrypting card data. These RSA public keys are included in the decoded JWT response from the `/uctp/v1/sessions` request. Your client-side code must extract the correct key based on the card number that is entered by the customer and then use that key to generate a JSON Web Encryption (JWE) compact serialization string. The encrypted card data is passed to the checkout() method as encryptedCard in the SDK. The SDK then forwards the encrypted card data to `Click to Pay`, where it is decrypted using the corresponding key. This means that the unencrypted PAN does not pass through the payment network or pass through your server. > IMPORTANT > You can store RSA public keys, however, ` Cybersource ` recommends that you use the keys from the URL. This ensures that you use the most current key. Key in Capture Context JWT {#uctp-keys-pan-enc-keys_section_rn3_pv4_53c} ------------------------------------------------------------------------ | Card Network | JWT Path | Key Format | |------------------|----------------------------------------------------------------------------|------------| | Visa | `payload.ctx[0].data.paymentConfigurations.SRCVISA.panEncryptionKey` | RSA JWK | | Mastercard | `payload.ctx[0].data.paymentConfigurations.SRCMASTERCARD.panEncryptionKey` | RSA JWK | | American Express | `payload.ctx[0].data.paymentConfigurations.SRCAMEX.panEncryptionKey` | RSA JWK | [PAN Encryption Key Locations] > IMPORTANT > Keys are located in the paymentConfigurationa field object within the data object. You must ensure the correct path to the key within the field object. If you do not do this and the path is incorrect, the key will be empty. > The card network is determined based on the bank identification number (BIN) of the PAN: * Visa: PAN starts with `4`. * Mastercard: PAN starrds with `51` through `55`, or `2221` through `2720`. * American Express: PAN starts with `34` or `37`. {#uctp-keys-pan-enc-keys_ul_nzn_m54_53c} Encryption Algorithm {#uctp-keys-pan-enc-keys_section_vfg_4v4_53c} ------------------------------------------------------------------ The card data is encrypted using a two-layer scheme per the JWE standard (RFC 7516): * **RSA-OAEP-256**: A random 256-bit AES content encryption key (CEK) is generated and encrypted (wrapped) using the network's RSA public key. * **A256GCM**: The card data JSON is encrypted using the CEK with AES-256-GCM, which provides both confidentiality and integrity. {#uctp-keys-pan-enc-keys_ul_ujk_3v4_53c} The result is a JWE Compact Serialization string with five Base64URL-encoded parts separated by dots: `header.encryptedKey.iv.ciphertext.authTag`. The `kid` from the PAN encryption key JWK is included in the JWE header. This enables the SRC receiving system to know which private key to use for decryption. JavaScript Example: Extract PAN Encryption Keys from Capture Context {#uctp-keys-pan-enc-keys_section_q2k_gw4_53c} ------------------------------------------------------------------------------------------------------------------ After you verify the capture context JWT on your server, extract the PAN encryption keys from the payload and pass them to the client alongside the decoded JWT. The keys are located within the paymentConfigurations field object for each card network. ``` // Server-side: extract PAN encryption keys from the verified JWT payload function extractPanEncryptionKeys(jwtPayload) { const networks = ['SRCVISA', 'SRCMASTERCARD', 'SRCAMEX']; const panEncryptionKeys = {}; for (const entry of (jwtPayload.ctx || [])) { for (const network of networks) { const key = entry?.data?.paymentConfigurations?.[network]?.panEncryptionKey; if (key) { panEncryptionKeys[network] = key; } } } return panEncryptionKeys; } // After verifying the capture context JWT: const decoded = await verifyJwt(captureContextJwt); const panEncryptionKeys = extractPanEncryptionKeys(decoded.payload); // Return both the decoded JWT and the keys to the client res.json({ captureContext: captureContextJwt, decoded, panEncryptionKeys }); ``` {#uctp-keys-pan-enc-keys_codeblock_vjx_fw4_53c} JavaScript Example: JWE Encrypt Card Data {#uctp-keys-pan-enc-keys_section_gjy_4w4_53c} --------------------------------------------------------------------------------------- These functions run in the browser using the Web Crypto API. The jweEncrypt function takes a pre-stringified JSON payload and the RSA JWK public key, and returns a JWE Compact Serialization string. ``` // Base64url-encode a Uint8Array (no padding) function base64UrlEncode(data) { let binary = ''; for (const byte of data) { binary += String.fromCharCode(byte); } return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); } // Base64url-encode a string (UTF-8) function base64UrlEncodeString(str) { return base64UrlEncode(new TextEncoder().encode(str)); } // JWE-encrypt a plaintext string using an RSA-OAEP-256 public key (JWK) async function jweEncrypt(plaintext, jwk) { // Import the RSA public key for key wrapping const publicKey = await crypto.subtle.importKey( 'jwk', jwk, { name: 'RSA-OAEP', hash: 'SHA-256' }, false, ['wrapKey'] ); // Generate a random 256-bit Content Encryption Key (CEK) const cek = await crypto.subtle.generateKey( { name: 'AES-GCM', length: 256 }, true, ['encrypt'] ); // Wrap (encrypt) the CEK with the RSA public key const wrappedKey = new Uint8Array( await crypto.subtle.wrapKey('raw', cek, publicKey, { name: 'RSA-OAEP' }) ); // Generate a random 96-bit IV for AES-GCM const iv = crypto.getRandomValues(new Uint8Array(12)); // Build the JWE protected header (include kid if present on the JWK) const header = { alg: 'RSA-OAEP-256', enc: 'A256GCM' }; if (jwk.kid) { header.kid = jwk.kid; } const encodedHeader = base64UrlEncodeString(JSON.stringify(header)); // The Additional Authenticated Data (AAD) is the ASCII bytes of the encoded header const aad = new TextEncoder().encode(encodedHeader); // Encrypt the plaintext with AES-256-GCM using the CEK const plaintextBytes = new TextEncoder().encode(plaintext); const encrypted = await crypto.subtle.encrypt( { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, cek, plaintextBytes ); // AES-GCM appends the 16-byte auth tag to the ciphertext const encryptedArray = new Uint8Array(encrypted); const ciphertext = encryptedArray.slice(0, encryptedArray.length - 16); const authTag = encryptedArray.slice(encryptedArray.length - 16); // Build JWE Compact Serialization: header.encryptedKey.iv.ciphertext.tag return [ encodedHeader, base64UrlEncode(wrappedKey), base64UrlEncode(iv), base64UrlEncode(ciphertext), base64UrlEncode(authTag), ].join('.'); } // Usage: encrypt card data with the appropriate network key const cardPayload = { card: { primaryAccountNumber: 'XXXXXXXXXXX, /* ... */ } }; const encryptedCard = await jweEncrypt(JSON.stringify(cardPayload), panEncryptionKeys['SRCVISA']); ``` {#uctp-keys-pan-enc-keys_codeblock_cky_4w4_53c} Token Management MLE Keys {#uctp-keys-tms-mle-keys} =================================================== When a checkout is completed with the payloadTypeIndicatorCheckout field set to `FULL`, the checkout response includes the encryptedPayload field which contains sensitive PCI/PII data. This sensitive data includes the actual card number (or token), expiration date, billing address, consumer details, and dynamic cryptogram data. This payload is encrypted by c`Cybersource` using Message-Level Encryption (MLE) so that only the authorized payment service provider (PSP) can read it. MLE keys are required when the payloadTypeIndicatorCheckout field is set to `FULL` in the checkout request. When the field is set to `SUMMARY`, the encryptedPayload field is not present and the MLE key is not required. MLE keys are also required when the decrypted payload is needed to obtain the actual payment credentials (PAN or token, cryptogram) for downstream payment processing, such as authorization through `Cybersource` or another processor. The public key is generated by the PSP or by the merchant, and uploaded to the `Cybersource` `Business Center` in the Key Management section. `Cybersource` uses this public key to encrypt the checkout payload. The private key is securely retained by the PSP or merchant and is never shared. It is preferably used on server-side to decrypt the encryptedPayload JWE. This design ensures that even `Cybersource` cannot read the decrypted payload after encryption and only the entity holding the private key can access the cardholder data. This is critical for ensuring PCI DSS compliance. Use Encryption Keys {#uctp-keys-tms-mle-keys_section_rn3_pv4_53c} ----------------------------------------------------------------- This table shows how encryption keys are used: | Key Aspect | Details | |----------------------------|--------------------------------------------------------------------------------------------------------------| | Generating Party | PSP or merchant | | Public Key Upload Location | `Business Center` \> Key Management (Token Management MLE section) | | Format | Base64-encoded RSA public key | | Private Key Storage | PSP or merchant, in a secure key vault or HSM | | Purpose | Decrypt `encryptedPayload` JWE in checkout responses | | Encryption Format | JWE Compact Serialization (RSA-OAEP-256 / A256GCM) | | Payload Contents | Card or token data, billing address, consumer email/name/phone, shipping address, dynamic data (cryptograms) | [Encryption Key Responsibilities and Usage] Key Setup {#uctp-keys-tms-mle-keys_section_vfg_4v4_53c} ------------------------------------------------------- Follow these steps to set up your key: 1. Generate an RSA key pair (minimum 2048-bit, recommended 4096-bit). 2. Extract the public key in Base64 format. 3. Upload the public key in `Business Center` \> Key Management. 4. Store the private key securely on your server (key vault, HSM, or encrypted secrets store). {#uctp-keys-tms-mle-keys_ol_stq_s1p_53c} When you need to rotate the key, you must generate a new key pair, upload the new public key to `Business Center`, and update your server with the new private key. `Cybersource` uses the new public key for subsequent checkout responses. You must keep the old private key available temporarily to decrypt any in-flight responses that were encrypted with the previous key. JavaScript Example: Decrypt Checkout Payload {#uctp-keys-tms-mle-keys_section_q2k_gw4_53c} ------------------------------------------------------------------------------------------ ``` const crypto = require('crypto'); async function decryptPayload(jweCompact, privateKeyPem) { const [headerB64, encKeyB64, ivB64, ciphertextB64, tagB64] = jweCompact.split('.'); // Import the merchant's private key const privateKey = crypto.createPrivateKey(privateKeyPem); // Unwrap the content encryption key (CEK) const wrappedKey = base64UrlDecode(encKeyB64); const cek = crypto.privateDecrypt( { key: privateKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, wrappedKey ); // Decrypt the payload with AES-256-GCM const iv = base64UrlDecode(ivB64); const ciphertext = base64UrlDecode(ciphertextB64); const authTag = base64UrlDecode(tagB64); const aad = Buffer.from(headerB64, 'ascii'); const decipher = crypto.createDecipheriv('aes-256-gcm', cek, iv); decipher.setAAD(aad); decipher.setAuthTag(authTag); const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]); return JSON.parse(decrypted.toString()); } // Usage: decrypt the encryptedPayload from a checkout response const payload = await decryptPayload(checkoutResponse.encryptedPayload, merchantPrivateKey); // payload contains: { card, billingAddress, consumerEmailAddress, dynamicData, ... } ``` {#uctp-keys-tms-mle-keys_codeblock_vjx_fw4_53c} Key Summary {#uctp-keys-tms-mle-keys_section_gjy_4w4_53c} --------------------------------------------------------- | Key | Side | Source | When Used | Purpose | |----------------------------|--------|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| | API Authentication Keys | Server | `Business Center` credentials. | Every server-to-server API call | Authenticate requests to `Cybersource` (`/uctp/v1/sessions` and `/flex/v2/public-keys/{kid}`) . | | JWT Validation Key (`kid`) | Server | Retrieved from `/flex/v2/public-keys/{kid}` per JWT | Every JWT received (capture context, checkout response, inner credentials JWT) | Verify JWT signature integrity and reject tampered tokens. | | PAN Encryption Keys | Client | Extracted from capture context JWT at `ctx[0].data.paymentConfigurations.[NETWORK].panEncryptionKey` | Guest checkout flow only when consumer enters card manually. | JWE-encrypt card data so raw PAN does not travel unencrypted. | | Token Management MLE Key | Server | RSA key pair generated by PSP and the public key is uploaded to the `Business Center`. | Checkout responses with payloadTypeIndicatorCheckout set to `FULL`. | Decrypt encryptedPayload to access PCI/PII payment credentials. | [Keys Used in Checkout and Tokenization Flows] JSON Web Tokens {#uc-appendix-jwts} =================================== JSON Web Tokens (JWTs) are digitally signed JSON objects based on the open standard [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519 ""). These tokens provide a compact, self-contained method for securely transmitting information between parties. These tokens are signed with an RSA-encoded public/private key pair. The signature is calculated using the header and body, which enables the receiver to validate that the content has not been tampered with. A JWT takes the form of a string, and consists of three parts separated by dots: ``` <Header>.<Payload>.<Signature> ``` The header and payload is **Base64-encoded JSON** and contains these claims: * **Header** : The algorithm and token type. For example: ``` { "kid": "zu", "alg": "RS256" } ``` * **Payload** : The claims of what the token represents. For example: ``` { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 } ``` * **Signature**: The signature is computed from the header and payload using a secret or private key. {#uc-appendix-jwts_ul_ozy_ysn_4pb} > IMPORTANT > When working with JWTs, ` Cybersource ` recommends that you use a well- maintained JWT library to ensure proper decoding and parsing of the JWT. > IMPORTANT When parsing the JWT's JSON payload, you must ensure that you implement a robust solution for transversing JSON. Additional elements can be added to the JSON in future releases. Follow JSON parsing best practices to ensure that you can handle the addition of new data elements in the future.