# Integrate with Guest Checkout Tokenization source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-guestcheckout-tutorial/index.md Use this tutorial and follow the required steps to integrate with Guest Checkout Tokenization. ## 1. Onboard to Mastercard Checkout Solutions {#1-onboard-to-mastercard-checkout-solutions} 1. Order the [Mastercard Checkout Solutions - Sandbox](https://www.mastercardconnect.com/-/store-plus/item-details/A/srconbrmtf) on [Mastercard Connect](https://www.mastercardconnect.com/). 2. [Enroll in the programs](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) you require for your sandbox projects. 3. [Create a sandbox project](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md). You can create up to 30 sandbox projects to allow testing in different lower environments. 4. Download the auto-generated [API Signing Key (OAuth key)](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) and [Consumer Key](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md). 5. Download the auto-generated [Payload Encryption Key](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md). Note: For detailed steps on onboarding for each product in Mastercard Checkout Solutions, please refer to the [Onboard to Sandbox](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) tutorial. ## 2. Integrate the APIs {#2-integrate-the-apis} * To get started with the API integration, download the OpenAPI Specifications available in [API Reference](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md) section. Generate an API client using an [OpenAPI Generator](https://openapi-generator.tech/), which provides generators and library templates for supporting multiple languages and frameworks. * To help you sign requests and perform payload encryption/decryption, Mastercard provides [client authentication libraries](https://github.com/Mastercard?q=oauth1-signer) and [encryption libraries](https://github.com/Mastercard?&q=client-encryption). * Follow the steps in [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial to enable authentication and perform encryption/decryption. * Mastercard supports two protocols for authenticating client applications to integrate with Mastercard APIs. Learn more on [API Basics](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-basics/index.md) page. Note: **In case of OAuth Authentication:** * Site identifier `X-Src-Cx-Flow-Id` is added as a part of all inbound API response headers for resolving site affinity issues on subsequent calls. * When making back-to-back API calls, the client must include the `X-Src-Cx-Flow-Id` of the initial API response in the header of the subsequent API request. This ensures that the consecutive API calls will be sent to the same Mastercard server that returned the initial response. ## 3. Call the APIs {#3-call-the-apis} Warning: For cards issued in **India** , Integrators must use the API URL endpoints applicable for **India region**. Please note that use of incorrect URLs will lead to failure of API calls. * If you are a merchant directly integrating with Mastercard Checkout Solutions, call [POST transaction/credentials](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API for tokenizing guest checkout transaction. Ensure you provide `DigitalAccountReferenceType` as `ENCRYPTED_CARD` and `DigitalAccountReferenceValue` with the encrypted card value to retrieve payload. * If you need to onboard merchants, you must register your merchants as DPAs using [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API. Ensure you provide the `programType` as `GUEST_CHECKOUT_TOKENIZATION`. ### General API Execution Flow {#general-api-execution-flow} 1. Encrypt card data object using Mastercard provided public key to encrypt the card object before calling [POST transaction/credentials](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API. Merchant encrypts the card object using the `src-fpan-encryption` public key. Mastercard will then decrypt the card using the private part of the `src-fpan-encryption` key. Refer to [Card Encryption](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/perform-encryption-tutorial/index.md) tutorial for details on how to obtain the public keys and encrypt the card object. ```json { "primaryAccountNumber":"5299920971401623", "panExpirationMonth":"08", "panExpirationYear":"2031", "cardSecurityCode":"000" } ```
2. To encrypt card data, import the following Java packages: * com.nimbusds.jose.EncryptionMethod * com.nimbusds.jose.JOSEException * com.nimbusds.jose.JWEAlgorithm * com.nimbusds.jose.JWECryptoParts * com.nimbusds.jose.JWEEncrypter * com.nimbusds.jose.JWEHeader * com.nimbusds.jose.JWEObject * com.nimbusds.jose.crypto.RSAEncrypter * com.nimbusds.jose.jwk.RSAKey * java.nio.charset.Charset * java.text.ParseException
3. After you import the Java packages, create a public class and include the main method. Use the `nimbus-jose-jwt` library for creating the JWE token. ```java public class JWEEncryptor { public static final String KID = "20230207223521-sandbox-fpan-encryption-src-mastercard-int"; public static final String PAYLOAD = "{\"primaryAccountNumber\":\"5455031247681061\"," + "\"cardSecurityCode\":\"123\"," + "\"panExpirationMonth\":\"11\",\"panExpirationYear\":\"2024\"}"; public static final String PUBLIC_KEY = "{\n" + " \"kty\": \"RSA\",\n" + " \"x5t#S256\": \"NgYAgjb6lJhuCqoB-3aIPc7km_QvU5nM65xdmxp2bFk\",\n" + " \"e\": \"AQAB\",\n" + " \"use\": \"enc\",\n" + " \"kid\": \"20230207223521-sandbox-fpan-encryption-src-mastercard-int\",\n" + " \"x5c\": [\n" + " \"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\"\n" + " ],\n" + " \"key_ops\": [\n" + " \"encrypt\",\n" + " \"wrapKey\"\n" + " ],\n" + " \"alg\": \"RSA-OAEP-256\",\n" + " \"n\": \"t06I8sjlS-rrs7uCagH8evoeumaRovKziZSI9S2N9IDQ9tW2PapfRa9Lc1KveEBDVs27PkhkU5OyHgP0iEjTuKVpvh59T4la-mBSIls7UecUQLLa0WkmbtL7jNdltA5fq7AhcAr5qca988qrLd7Iyr9E0C3TxbT9to1iQcpz8ocZODRXoidFAnOVL5YGFmlsreDbJ4Vhsi0pAdccQcil-ydSgurKB-rqKppb9epomu4QUh3382Cv8NobYmF3os8nGGgGP-cyXo0nsKcPAgfrlQzos7qHxUOrFe2x_lZ1G1AE-XrkrxjBys9q53GMRSNCQ8c-_mcF9pbq4HYBs-vD5Q\"\n" + "}"; public static void main(String[] args) throws ParseException, JOSEException { //generate key by parsing your public key RSAKey key = RSAKey.parse(PUBLIC_KEY); //define JWE header JWEHeader header = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM).keyID(KID).build(); // Create an RSA encrypted with the specified public RSA key JWEEncrypter joseRsaEncryptor = new RSAEncrypter(key); // Initialized the JWECryptoParts object JWECryptoParts jweCryptoParts = joseRsaEncryptor.encrypt(header, PAYLOAD.getBytes(Charset.defaultCharset())); // Doing the actual encryption JWEObject jweObject = new JWEObject(header.toBase64URL(), jweCryptoParts.getEncryptedKey(), jweCryptoParts.getInitializationVector(), jweCryptoParts.getCipherText(), jweCryptoParts.getAuthenticationTag()); // Serialize to JWT compact form String jwtString = jweObject.serialize(); printIt(jwtString); } private static void printIt(String jwtString) { System.out.println(""); System.out.println("========================= Encrypted JWE token =================================="); System.out.println(""); System.out.println("\n JWE token : " + jwtString); System.out.println(""); } } ```
JWE Encryption Instructions * Set the consumerKey. * Copy the contents of the key file into privateKey under the 'Current value' field. * Set the publicKeyFingerprint copied from your project dashboard from the fingerprint section. * Copy the contents of the encryption certificate to encryptionCert. * Set encryptionType to jwe. * Set pathToRawData, pathToEncryptedData and encryptedValueFieldName according to the project documentation. 4. Call the [POST transaction/credentials](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API using `DigitalAccountReferenceType` as `ENCRYPTED_CARD` and add the `ENCRYPTED_CARD` value in `DigitalAccountReferenceValue` to retrieve the transaction credentials for guest checkout transaction. ```json { "srcClientId":"7dd7697a-a2b7-4ac0-bdaa-35b883ca0a37", "srcDpaId":"b756a2b0-ef62-4c62-a6de-f72e75ce5f17", "srcCorrelationId":"29b31955-6829-4e01-a261-ff6263bf9a2a", "serviceId":"${Program Id}}", "srciTransactionId":"086178df-1f8c-4367-83a3-521ffcb7fc1c", "payloadTypeIndicatorCheckout":"FULL", "recipientIdCheckout":"2fb2cd53-a454-4818-9e65-e572240db922", "shippingAddressId":null, "dpaTransactionOptions":{ "transactionAmount":{ "transactionAmount":676, "transactionCurrencyCode":"USD" }, "dpaBillingPreference":null, "dpaAcceptedBillingCountries":null, "dpaShippingPreference":null, "dpaAcceptedShippingCountries":null, "consumerEmailAddressRequested":true, "consumerNameRequested":true, "consumerPhoneNumberRequested":true, "merchantCategoryCode":"4444", "merchantCountryCode":"US", "merchantOrderId":null, "srcTokenRequestData":null, "paymentOptions":null, "dpaLocale":"en_US" }, "assuranceData":null, "complianceSettings":null, "dpaData":{ "dpaPresentationName":null, "dpaAddress":null, "dpaName":"Vitrine Test Merchant", "dpaEmailAddress":null, "dpaPhoneNumber":null, "dpaLogoUri":null, "dpaSupportEmailAddress":null, "dpaSupportPhoneNumber":null, "dpaSupportUri":null, "dpaUri":null, "applicationType":null }, "acceptanceChannelRelatedData":null, "keyFingerprintId":null, "digitalAccountCredentials":{ "digitalAccountReference":{ "digitalAccountReferenceValue":"eyJraWQiOiIxNDkwNjQtc3RnLXNyYy1mcGFuLWVuY3J5cHRpb24iLCJlbmMiOiJBMTI4R0N... ", "digitalAccountReferenceType":"ENCRYPTED_CARD" } } } ``` 5. Merchant receives the `checkoutResponseJWS` and decodes it to extract the `encryptedPayload`. Merchant can then decrypt the `encryptedPayload` using the private payload encryption key (from the public/private Payload Encryption key pair) to extract the token and cryptogram. See [POST transaction/credentials](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API for more details. ```json { "checkoutResponseJWS": "eyJpc3MiOiJodHRwczpcL1wvbWFzdGVyY2FyZC5jb20iLCJpYXQiOjE1NzA3Mzk3MzIsImFsZyI6IlJTMjU2IiwianRpIjoiMGNjODlkYTctMGZlNi00NDU1LWJjYWItZjU4Nzk0ZDY2NWY1Iiwia2lkIjoiMTQ5MDIzLXN0Zy1zcmMtcGF5bG9hZC12ZXJpZmljYXRpb24ifQ.eyJzcmNDb3JyZWxhdGlvbklkIjoiMzRmNGEwNGIuZmJhOTI2M2MtNzVmMS00YjgyLWIzOWItYjI5N2UzY2VlMDI3Iiwic3JjaVRyYW5zYWN0aW9uSWQiOiI1MjZlMWQzMS0xZmViLTQwMjYtYWJjZi1jYTZjZTg1ZWU5Y2IiLCJlbmNyeXB0ZWRQYXlsb2FkIjoiZXlKcmFXUWlPaUpIYjI5bmJHVlRVa00wUTB0bGVTSXNJbVZ1WXlJNklrRXhNamhIUTAwaUxDSmhiR2NpT2lKU1UwRXRUMEZGVUMweU5UWWlmUS5makdIN3BhRWZ3WHJWTDRhdm43TzJOZm9KUUFkbnBKak9nMXYxSGp3UmVVdFhERFF2MlkzZW9kMF9ZbUQ2VDlERVFreW9fTTRURlB4eXQ2SThCZXdNa3dBYVprNUpuYi1jUTVRZkdFVks5Uk94bHVzQWNWOHBGOFFrRktOM1N2dHZFM011MGMxbTNYUV9nUW96bnBYcU91QUxNRnZxNjVhYjBudzdnaGdIaGxqaXJuREZQdVRRVTFyZEJqd2ZVd2tadGtrQXVRLThHdkVFUTdhY3lNMllZX1NPZUpYZzIzX0JYa1BQY25IendERlQ2VWNGUUlNOEltaFJNMzI1NFVrcW4yREJDUWxzZlFXSGVMUVJPQV82SkotcU15OHFhVGUyRkdKemhTTXJaZEd1d1BpRkFaYmlXWFZia0M3Vi0tdzNIckxCcHN5NGhYU1dNSndsenRvUncuU1F5VDFfRXRUMnlDLU55cC5GeDBZUlByOVBncnVTWTdiMDJrMVgxS1ZaMFNtcHpqb0N5bUs1N0pmMW9Dbk5rMU84MzkxckhJVG5hTEFEc2FhZUZEaHdNTUl0NHJIelBic2RhVEJXcHpmQlNneUs0QWF3ZE13SEFZVlJnUmJNQmhlMXppYTVSTVpHYkJDTzN6c2dTRW5sZVRHSmVKYU81NlExRkFuQ3ZYblQwN293ekdPOXltc3JfZEhvWExKWVNnZGthUE5sRTZZOENOU2VJa0psTXdsU1o0YkhNckRRODNkNTdiR0dJT3Y3ZWZoZ2RqVGF3SVpsWmNKUXZhVWMyU09JYWU0MUpIellBeGhKSDZ4R3kxckhCZFR1dEV0UkhQNVdaSzVva1BLcG14Z1dPUGk4MW5KbHM3aVIzVEVKWktEMllwNTNPSENvdVZabjBZRFJqV19vR0t6UENmNnVMQ0VSb3RNZHNQXzBhSVBmSTk0LWxuM25WZnF1c1dSdGxIN253eEQ0eUF3VW1ndkVCLW5IYUFVb1RmdE9YMGUyQ2YtRWVHTjFmemZPQ1Bid2g3YWlXWmJLVnp2Tmg5clBBOXNRWUwyT1RtN1pPRmVOTXItZ01XWnZHUjZFVGl1OWwta3ZmVHdjMnpaZXRWbVFGVm5lazVKMGdhdmlZQ000WHZmNEZtVXktNTBtOVQxOWVhZnN1bXVlckJ6cDZaQ20xaTBmMmFSSVpXNGMwdXhMMXRQSlkwLVl2bFh4cEJNNERCdjJEc3h1MkxldDlpZV93c2RRd2NFTk1GWUxxbjY0ZmVWb2stUkVaeUt4V0tJR3pmWkloWkx3LTl4a0xDdEh3U2VCa2hMMC1pOVhqQXJnWEFteHVUYmhEV0NYMUFPQkFvOHJHOE0xSmJ2N2lzSk9mVENsQk5BQTFsWjlRcE9MOHViUFJOa3ZXeHhEWmFfYVVQWWt3aDZ4bFRwdXhzeXFYaTBHWnRqRi1jWkp4cVZSOExWcXN3WWo1cDdrTmpWMlpYMDRDS1ZjS0lZUjZ3dm9KUWM0T2FFV1FkSlhJb0NFZVNGVVpoaUNHZVljX1VCQ2tRcnplOHZoZUh2SmQzdFVLTHBqSzdXM2gyUHc0ZGhRNTVBUzhhMUNIMDJtNklQcU9FMVgyUmY5WEk5UUxKUzFyMXZwVE5fYjRzUnROaTUwR3MxODQ4LUxPb0U2RmJwaHdHVHZoc0pnWGxHakl2MHlucGJHRXMzX0lvVUc1dnpCZEdycHBUTEZaMjVEbXkwMzlVMG9neW4wRElia3l4S2dfbS1JVlVTdWdDckViZlFPV0swV3lscnpfYkVhZlFpUEJjMDJDeGNmQkJtcFNEUHBVVU1lZ1plRHc5eV9qbmx4X0R1ajFveU1pYzRvR1YxcEMtLUl5YVRGMWt6Z1hwUnlyUmd6NHlCVWFORlU4S0JVUmJ3cmJVd2hwX3BUSll1Q0lrTW53M1hqSEh0RHFEa1h1YWNLRWpVNGhvdjgzV1B4TnBiclV1VXUtVjZJSEY3b2R2MDE2R3pPbDVTVkxiNHNvN09MNzhWNDBjVWNQNVZJQnMzdzlyS0VnRVBBeFNVOHdzWjQxYkNGLVBDc2JMQTBmRE8zaUItOXh2bXpfNWJYUWdnLW5fLXcxVjV5NHd2ZnJNOTY5dk55VnJHX3NFeGtoNVN0QWp4Y2prN24yREZDVWM3UEFjU3hMYnVsbFVmdmFqZmI4Nm5FS0JnTjJtTGVCcjNtNnAyVlZGZ2c3bVlpS3BZY1dROHNHRG1Nei1lUlBITEl6TmFTZ1M0aC1fRVF5VnVWdWNUZklpTWJ5RGtfbXRJZG9rV1NXdmJqNjItMm5vd3VTVVE0RWtHbDYzSnlPODZWY21EbHJ1WFNWMmdydmpNZi1HVmY5WW9nakNPMURDb3JjcExTTk1DUUVUS251TEIyeWVIRkF3eldjSHlYN2hmeWVTcEx4X0l0WFItV3U5YlR0NmZidWNJSzk1dzVQNFZ6VTMwcUUxZExZdE41RWMuVDVZSHhTclU1RGpLYjNNY00xT2YwQSIsIm1hc2tlZENhcmQiOnsic3JjRGlnaXRhbENhcmRJZCI6ImJiN2I2ZjBiLWNmZDYtNGY0Yy1hNmIyLTdiYWNmM2RmZTcwYiIsInBhbkJpbiI6IjU0NTUwMyIsInBhbkxhc3RGb3VyIjoiNzQxNiIsImRpZ2l0YWxDYXJkRGF0YSI6eyJzdGF0dXMiOiJBQ1RJVkUiLCJwcmVzZW50YXRpb25OYW1lIjoiQ2l0aSBCYW5rIiwiZGVzY3JpcHRvck5hbWUiOiJtYXN0ZXJjYXJkIiwiYXJ0VXJpIjoiaHR0cHM6Ly9zdGFnZS5hc3NldHMubWFzdGVyY2FyZC5jb20vY2FyZC1hcnQvY29tYmluZWQtaW1hZ2UtYXNzZXQvOWQ0MmRmNTQtYzVmZC00MzhiLWE4ODYtZmYwYmQxZThmN2VjLnBuZyJ9LCJwYW5FeHBpcmF0aW9uTW9udGgiOiIwOCIsInBhbkV4cGlyYXRpb25ZZWFyIjoiMjAyMyIsIm1hc2tlZEJpbGxpbmdBZGRyZXNzIjp7ImFkZHJlc3NJZCI6ImI5MGVjYjM4LTg5N2QtNGY5NS1hYjQzLTE1NTY1ODkxOGE5NiIsIm5hbWUiOiJKKioqIEQqKiIsImxpbmUxIjoiMSoqIDUqKiBBKioqKioiLCJsaW5lMiI6IkYqKioqIDEqIiwiY2l0eSI6Ik5ldyBZb3JrIENpdHkiLCJzdGF0ZSI6Ik5ZIiwiY291bnRyeUNvZGUiOiJVUyIsInppcCI6IjEwMDExIiwiY3JlYXRlVGltZSI6IjIwMTktMTAtMTBUMjA6MzU6MTMuNTI2WiJ9LCJkY2YiOnsiYXBwbGljYXRpb25UeXBlIjoiV0VCX0JST1dTRVIiLCJ1cmkiOiJodHRwczovL3N0YWdlLnNyYy5tYXN0ZXJjYXJkLmNvbS9wYXkvIiwibG9nb1VyaSI6Imh0dHA6Ly9tYXN0ZXJjYXJkLmNvbS8iLCJuYW1lIjoibWFzdGVyY2FyZCJ9LCJkYXRlT2ZDYXJkQ3JlYXRlZCI6IjIwMTktMTAtMTBUMjA6MzU6MDMuODk1WiJ9LCJtYXNrZWRDb25zdW1lciI6eyJzcmNDb25zdW1lcklkIjoiODc2NjlkNTEtN2JlNC00MTk5LTkzMGItOTJjNjJhODk0ZmVjIiwibWFza2VkQ29uc3VtZXJJZGVudGl0eSI6eyJpZGVudGl0eVByb3ZpZGVyIjoiU1JDIiwiaWRlbnRpdHlUeXBlIjoiRU1BSUxfQUREUkVTUyIsIm1hc2tlZElkZW50aXR5VmFsdWUiOiJqKioqKio3QGR1bW15ZW1haWwuY29tIn0sIm1hc2tlZEVtYWlsQWRkcmVzcyI6ImoqKioqKjdAZHVtbXllbWFpbC5jb20iLCJtYXNrZWRNb2JpbGVOdW1iZXIiOnsiY291bnRyeUNvZGUiOiIxIiwicGhvbmVOdW1iZXIiOiIoKioqKSAqKiotKjg5NSJ9LCJtYXNrZWROYXRpb25hbElkZW50aWZpZXIiOiIqKioqKioqKioiLCJjb3VudHJ5Q29kZSI6IlVTIiwibGFuZ3VhZ2VDb2RlIjoiRU4iLCJtYXNrZWRGaXJzdE5hbWUiOiJqKioqIiwibWFza2VkTGFzdE5hbWUiOiJkKioiLCJtYXNrZWRGdWxsTmFtZSI6ImoqKiogZCoqIiwiZGF0ZUNvbnN1bWVyQWRkZWQiOiIyMDE5LTEwLTEwVDIwOjM0OjU3LjUzMloifSwic2hpcHBpbmdBZGRyZXNzWmlwIjoiMTAwMTEiLCJzaGlwcGluZ0NvdW50cnlDb2RlIjoiVVMifQ.JBqO5Y4HSNAwL6o6_-al7burrIU-5H6x-UxtK8jFxSQ5EsvDoGOEjRSxBu9dlHStodMQ2FndZhV29dCKVcw1cpmDVuFUevDFcnsD4oIwYLM-VgLocx_jF749RAI-4FyGXZoSPcZaOpI2N3thWU9S2XD2-sfxFnDfitUul0have4-mQWEVBm0h6PF8DVmjJMklk6rY4efP18RNTt73GFyP_g86TU5FxHhogXsWrBsQVXX8REh2wDfVNQPllhCmFElkjeUUmylgkbhioPddh3JtR2eLurZ4Ttuevvxk0fjeJtgNfkgXjk9zdpxRyjlf_jArjbU9dtE9dZT5Spx45hfSQ" } ``` ## 4. Decrypt the Payload {#4-decrypt-the-payload} Decrypt the `encryptedPayload` using your private key from the Payload Encryption public / private key pair. Mastercard uses the public key of this key-pair to encrypt response payloads containing payment card credentials. See [Key Management](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) to understand more about which keys to use to decrypt the payload. | dynamicDataType | Description | Payload format | |----------------------------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM | Payment authorization using DSRP cryptogram passed in **dynamicData** object. | **DSRP** : Dynamic Secure Remote Payments (DSRP) cryptogram is a type of dynamic data which the Integrator will have to pass within Dynamic Payment Data field (DE104 SE001) of the payment authorization request. This cryptogram is base64 encoded and can be up to 32 characters in length. It is passed in the [Checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API. | Diagram encryption_decryption 1. For decrypting the payload, you can use [Mastercard's encryption/decryption libraries](https://github.com/Mastercard?&q=client-encryption) 2. [Add the library](https://github.com/Mastercard/oauth1-signer-java#maven) to your project. 3. Define `util`, which will set the JWE Decryption configuration as per instructions defined in the library. ```Java private static JweConfig decryptionConfig; // Configuration defined by library public static JweConfig getDecryptionConfig() throws Exception { if (ObjectUtils.isEmpty(decryptionConfig)) { File decryptionCert = ResourceUtils.getFile("{{Decryption Certificate Path}}"); //.p12 file PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey( decryptionCert.getPath(), {{decryptionCertAlias}}, {{decryptionCertPassword}}); decryptionConfig = JweConfigBuilder.aJweEncryptionConfig() .withDecryptionKey(decryptionKey) .withDecryptionPath("$.encryptedPayload", "$") .withEncryptedValueFieldName("encryptedPayload") .build(); } return decryptionConfig; } ``` 4. Define a service interface and implementation for decryption using configuration defined in util. 1. Service Interface: To define behavior and structure of the decryption function. ```Java DecryptedPayloadDTO getDecryptedPayload(guestCheckoutTokenizationResponseDTO guestCheckoutTokenizationResponseDTO) throws Exception; ``` 2. Service Implementation: Implement service function as per the defined interface. ```Java public DecryptedPayloadDTO getDecryptedPayload(guestCheckoutTokenizationResponseDTO guestCheckoutTokenizationResponseDTO) throws Exception { JweConfig jweConfig = guestCheckoutTokenizationUtils.getDecryptionConfig(); String payload = JweEncryption.decryptPayload(new Gson().toJson(guestCheckoutTokenizationResponseDTO), jweConfig); DecryptedPayloadDTO decryptedPayload = new Gson().fromJson(payload,DecryptedPayloadDTO.class) return decryptedPayload; } ``` When the `encryptedPayload` field is decrypted, you will see a JSON object containing transaction information. * DSRP ```DSRP // DSRP cryptogram in the dynamicData object // Sample Decrypted Payload { "dynamicData": { "dynamicDataValue": "MMUJZa0RqWXo2M2NSZ29jS2xlOEgzYjRs", "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM" }, "token": { "paymentToken": "5455039458295123", "paymentAccountReference": "5001a9f027e5629d11e3949a0800b", "tokenExpirationMonth": "11", "tokenExpirationYear": "2031" } } ``` | Field | Description | |------------------------------------------------------|--------------------------------------------------------------------------------------------| | **token** object | Indicates that the transaction has been tokenized. | | ↳ **paymentToken** | A 16 digit token rather than a PAN. | | ↳ **tokenExpirationMonth** ↳ **tokenExpirationYear** | Parameters that provide the tokenized values for digitized card. | | ↳ **paymentAccountReference** | Non-transactable value that is paired with an FPAN, and is linked to the associated token. | | **dynamicData** object | A cryptogram object. | | ↳ **dynamicDataValue** | Containing the 32 char DSRP cryptogram in base64. | | ↳ **dynamicDataType** | `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM` indicates DSRP. | Once Mastercard Checkout Solution receives the payload response for a tokenized payment, they can proceed to make a payment authorization with their acquirer or payment provider. ## 5. Send the Payload for Authorization {#5-send-the-payload-for-authorization} When the consumer submits the order, send the decrypted payload for authorization. For tokenized transactions, the response payload fields are passed in a Payment Authorization request as follows: | Solution | Description | |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **DSRP** | PAN with the **paymentToken** value, DE 104(Digital Payment Data), sub-element 001 (Digital Payment Cryptogram) with the **dynamicDataValue** and Date Expiration (DE14) with **tokenExpirationMonth** and **tokenExpirationYear** in YYMM format. | Note: The API specification does not define requirements for transaction processing. For more information about DSRP transactions, refer to: * [DSRP --- Acquirer Implementation Guide](https://trc-techresource.mastercard.com/r/bundle/m_an5843/page/z/ndg1634167211641.html) * [AN3363 --- Mandatory Use of Digital Payment Data Field for Remote Commerce Transactions with Cryptograms](https://trc-techresource.mastercard.com/r/bundle/m_an3363_en-us/page/d/en-US/jvw1585260985294.html)