# Integrate with Mastercard Merchant Presented QR: SRC source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-sqr-tutorial/index.md Use this tutorial to learn about the required steps to integrate with Mastercard Merchant Presented QR: SRC (SQR). ## 1. Onboard to Mastercard Checkout Solutions {#1-onboard-to-mastercard-checkout-solutions} You should work with your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) to complete all the onboarding activities. ## 2. Generate QR Codes using SDKs {#2-generate-qr-codes-using-sdks} Acquirers or Payment Service Providers (PSPs) are responsible for generating the QR codes for participating merchants. The QR code must follow the [EMVCo Merchant Presented QR specifications](https://www.emvco.com/emv-technologies/qrcodes/). To learn more details about Device SDKs, see the [Generate QR Code for Merchants](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/sqr/generate-qr-codes/index.md) use case. ## 3. Integrate the APIs {#3-integrate-the-apis} * To get started with the API integration, you can 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. ## 4. Call the APIs {#4-call-the-apis} * If you are a Digital Wallet Operator integrating with Mastercard Checkout Solutions, you can follow the [use-cases](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/sqr/index.md#use-cases) to call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card enrollment and tokenization, followed by [POST checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API to initiate payment. * If you are an Acquirer/PSP integrating with Mastercard Checkout Solutions, you must process the payload for authorization and notify the merchant about the transaction status. * 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 `SQR_DEVICE`. ### General API Execution Flow {#general-api-execution-flow} 1. Digital Wallet Operator calls the [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API and retrieves the `srcDigitalCardId` associated with the consumer's profile for the consumer's chosen PAN (Primary Account Number). Optionally, call the other card related [APIs](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md) such as card notifications. 2. Digital Wallet Operator calls the [POST checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API using `srcDigitalCardId` for the token associated with the chosen card to retrieve the transaction credentials from Mastercard Checkout Solutions. The response will be a summary request without the payload. 3. An Acquirer/PSP receives the encrypted payload via Make Payment API -- [POST /transaction/credentials](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/index.md#make-payments). Extract the `encryptedPayload` value from the checkoutResponseJWS. This value contains a JWE in compact serializable form. The JWE content is signed or encrypted using the public Payload Encryption key (which is a part of the public/private payload encryption key pair) provided by you at the time of onboarding. 4. Mastercard Checkout Solutions sends transaction notifications to Digital Wallet Operator via [POST /notifications/transactions](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/index.md#push-transaction-details) if the transaction is eligible, provided the Issuer of the card used to make payment supports Transaction Detail Service (TDS). **Example of an encryptedPayload object** ```Javascript "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.MIq_v15_eowvwX8MRgrb_H1EevZKB9CZSMMD8-lcbTjQvPFwAyx1USZbZRDB3RGfA_of6aDggnbmQmgsUStPQEpzYMma5mxlv5-VT6ry94xyttBFuCjBV0hudmcOEHiQeIiwS5xBb1iBPFaXTEmMpgDv8lvAm_ncbJ0V5FFDUYYVhK0-SbaODY5OKMdP2N3Y9bCkqjLCAcmkkN3mkrJ6WbzJURmNdfPyL344Cxc14NLZW3fk_yHkmjXybIXJWnUUsdxwFWS5ImwaZGEhbeLGGdpsPTkTkwD86uZCYJlx_dsZi02Vbm9AIiPpKE4L8GS_ltmOQ3YfgfxS6UuzYzaxKw.Xi3KLm7BvjSQuPMSVwSepg.U6Yp-DXd55F6jqy8-LIbmxmExzLaZNCF9Rcmg0g7ViUN3ydm_G5IqJmCFgXg1aO50HYJvnxi5OWG_rs6uV-1I2rrpu3bkuSjkj03N82yhFJBbhr8W_ahlgAMv2FPu4k7aeGp5rWm5lEdvH2UpSvKG2Ae111iFtL842Pk0pgPLOv4jnxFaCrvAPZ4vTvHS1RU27XGW7qXfAOtqpZ38oUJFamYueCIycDrsvacPT650O_JM_QS0ReXkH49bgAt1Sog9r2PY7fjU22ff1oGno51uVK_D9EXyHWcD4I5LYdVd6NenPDfycuQZ_wA98nqMCTzrqx5yQjUQDNYOoDF8ztoKVpYsTJeIUcFTpGXfoLLPTWjoIUds3mIyrXtBWO46rqN8c2nQ6FKC04-CBK9RGbWr1q1ENgfmsBvfXPCIUZ5ACzM1UaU2LkgEYlyiaxn-I3MfauP1adsA3ZOhrDHwSNgA0aVejT_9OTOaBUmywKGtdD7E8PhP7JqbMTXH2gM_9xU7t7TRvntE5uXeALKv4EDurn0p5bASwsYie7xWbsMHGF8lN0aGqJhNKiHL_NFGnR0wzPWS3UXFP7wZFbLM9qSPw.XFMSREEcssFqUM5kIwChIA", ``` ## 5. Acquirer or PSP Decrypts the Payload {#5-acquirer-or-psp-decrypts-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. The payload will be returned in the most secure format possible and in accordance with the `DpaTransactionOptions.PaymentOptions.dynamicDataType` parameter passed in the [Checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API. | 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_sqr 1. For decrypting the encrypted payload, add [Mastercard's encryption/decryption libraries](https://github.com/Mastercard/client-encryption-java#adding-the-library-to-your-project-) to your project. 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(clicktopayResponseDTO clicktopayResponseDTO) throws Exception; ``` 2. Service Implementation: Implement service function as per the defined interface. ```Java public DecryptedPayloadDTO getDecryptedPayload(clicktopayResponseDTO clicktopayResponseDTO) throws Exception { JweConfig jweConfig = clicktopayUtils.getDecryptionConfig(); String payload = JweEncryption.decryptPayload(new Gson().toJson(clicktopayResponseDTO), 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 { "token": { "paymentToken": "5480983179133165", "tokenExpirationMonth": "07", "tokenExpirationYear": "22", "paymentAccountReference": "50017Q9JP3JRJXIZ1BXQL2MKMX4LE" }, "shippingAddress": { "addressId": "adb12da8-474b-4e53-9c3b-5541af7c27bf", "name": "John doe", "line1": "test address", "city": "New York", "state": "NY", "countryCode": "US", "zip": "10011" }, "consumerEmailAddress": "johndoe@dummyemail.com", "consumerFirstName": "john", "consumerLastName": "doe", "consumerFullName": "john doe", "consumerMobileNumber": { "countryCode": "1", "phoneNumber": "9912797896" }, "srcTokenResultsData": { "unpredictableNumber": "63f43cff", "tokenRequesterId": "50123197928" }, "dynamicData": { "dynamicDataValue": "AIrqb3XZSbgpAAl2lQeDGgADFA==", "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM" }, "billingAddress": { "addressId": "3374e6e9-293a-4612-aa5d-0e42a8ff7aae", "name": "John doe", "line1": "test address", "city": "New York", "state": "NY", "countryCode": "US", "zip": "10011" } } ``` | 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-transactional value that is paired with a FPAN and is linked to any token created that represents that FPAN. | | **dynamicData** object | A cryptogram object. | | ↳ **dynamicDataValue** | Containing the 32 char DSRP cryptogram in base64. | | ↳ **dynamicDataType** | `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM` indicates DSRP. | | **srcTokenResultsData** object | Additional token data. | | ↳ **tokenRequesterId** | Token Requester identifier. | | ↳ **unpredictableNumber** | Unpredictable Number used to generate this cryptogram. | Once the 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. ## 6. Send the Payload for Authorization {#6-send-the-payload-for-authorization} PSP or Acquirer sends 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), subelement 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) ## 7. Notify the Digital Wallet Operator of Transaction Status {#7-notify-the-digital-wallet-operator-of-transaction-status} Once the payload is authorized, the Acquirer notifies merchant of a successful transaction. Mastercard Checkout Solution uses the [Push Transaction Notifications](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/index.md#push-transaction-details) API to notify the Digital Wallet Operator about the status of the transaction, provided the Issuer of the card used to make payment supports Transaction Detail Service (TDS).