# Consent using Consent Management APIs source: https://developer.mastercard.com/consent-management/documentation/use-cases/single-card-enrolment/card-auth-consent-apis/index.md ## Mastercard Consent Management APIs {#mastercard-consent-management-apis} If you are PCI compliant, currently managing cardholder data, and wish to construct your own authentication user interface for customer verification, Consent Management APIs offer a solution that can be used in conjunction with your own UI to authenticate your customers. Diagram consentapis ## Create Consent {#create-consent} Consents are created by calling `POST /consents`. This will add the consents to a card, but initially they will be in the state `REQAUTH` (requires authentication), so they are not actually active yet. When authentication is required, the response to `POST /consents` will contain an `auth` object, which contains the details of what needs to be done to authenticate the consent, for example: ```json { "cardReference": "xxxx", "auth": { "type": "THREEDS", "status": "AUTH_READY_TO_START" ... } ... } ``` For now only available type is `THREEDS`.3DS Authentication may require fingerprinting in the browser, and it may also require a challenge window (usually both). ### 3DS Fingerprinting {#3ds-fingerprinting} When `POST /consents` is called, if fingerprinting is required, the `auth` response will contain the information required. For example: ```json "auth": { "type": "THREEDS", "status": "AUTH_READY_TO_START", "params": { "threeDSServerTransID": "xxx", "threeDsMethodUrl": "xxx", "threeDSMethodNotificationURL": "xxx", "threeDSMethodData": "xxx" } } ``` These four parameters need to be passed in the form POST for the fingerprint iframe. When the fingerprinting iframe is complete it uses browser `Window.postMessage` to send a message with type `threeds-method-notification` that it is finished, so you need to create a listener for that event. An example of how to display the iframe and listen for the completion event is shown in the [tutorial](https://developer.mastercard.com/consent-management/documentation/tutorials/consents-tutorial/index.md). Fingerprinting can complete successfully, timeout, or be unavailable (ie. fingerprinting is not required or there is another error). The result of the fingerprinting needs to be passed to the call to start authentication, along with some browser parameters. ## Start Authentication {#start-authentication} For `THREEDS` authentication, first browser fingerprinting may need to be done before calling `start-authentication`. Once fingerprinting is complete, a call to `start-authentication` is made, which will usually return the URL for the 3DS challenge. The 3DS Challenge iframe needs to be displayed to the consumer, so they can verify their identity. ### 3DS Start Authentication {#3ds-start-authentication} When calling `/consents/{cardReference}/start-authentication`, the following parameters must be passed: | Parameter | Description | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | fingerprintStatus | From fingerprinting processing, either `complete`, `timeout` or `unavailable` | | merchantName | Displayed in challenge iframe | | browserAcceptHeader | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. | | browserColorDepth | Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. | | browserIP | IP address of the browser as returned by the HTTP headers to the 3DS Requestor. | | browserJavaEnabled | Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. | | browserLanguage | Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. | | browserScreenHeight | Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. | | browserScreenWidth | Total width of the cardholder's screen in pixels. Value is returned from the screen.width property. | | browserTZ | Time difference--zone offset in minutes between UTC time and the Cardholder browser local time, in minutes. | | browserUserAgent | Exact content of the HTTP user--agent header. | | challengeWindowSize | Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window. Value accepted: 01 = 250 x 400, 02 = 390 x 400, 03 = 500 x 600, 04 = 600 x 400, 05 = Full screen | "If a challenge is required, the response to `start-authentication` will contain the details needed to display the challenge window. If a challenge is not required (or not possible), there will be no challenge details in the response. When no challenge is required, this is called **frictionless** . In the frictionless case, you should receive **auth.Status = AUTHENTICATED** in the `start-authentication` response. **At this point, user authentication is considered completed, and no further API call is required.** If a challenge is required, the challenge parameters will be included in auth.params and will consist of the following: | Parameter | Description | |-------------|--------------------------| | acsUrl | URL for challenge window | | encodedCReq | Encoded 3DS creq | Both of these need to be passed to the challenge iframe. Similar to the fingerprinting iframe, when the challenge iframe is complete it uses browser `Window.postMessage` to send a message with type `threeds-challenge-notification` that it is finished, so you need to create a listener for that event. An example of how to display the iframe and listen for the completion event is shown in the tutorial. If authentication fails due to an ACS/issuer error, the error details will be returned in auth.params along with **auth.Status = AUTH_FAILED**. The error details will include the following fields: | Parameter | Description | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | cardholderInfo | If populated, this field may be optionally displayed to the cardholder. It contains text provided by the ACS/Issuer to the cardholder during a frictionless transaction. For example, Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx--xxx--xxxx. | | transStatus | Indicates whether a transaction qualifies as an authenticated transaction or account verification. | | transStatusReason | Provides information on why the transStatus field has the specified value. | ## Verify Authentication {#verify-authentication} Once consumer has completed the challenge iframe, the final call is `/consents/{cardReference}/verify-authentication`. No additional parameters need to be sent in the request. The call checks if the 3DS challenge was success. Upon success, the consent status is set to `APPROVED` and the consent becomes active. If authentication fails for any reason, such as the user canceling or failing the challenge, failure details will be provided in the auth.param using the following fields: cardholderInfo, transStatusReason, and transStatus. ## Consent States {#consent-states} When a Consent is created for a card, its status is either set to `APPROVED`, if authentication is not required, or `REQAUTH` if it requires authentication. After authentication, the status is changed to `APPROVED`, if successful, or `FAILED`. Consent is only valid for a certain period of time, for example six months. Once that time has passed, the state is changed to `EXPIRED`. If the same consent is later requested again, then a new consent is created. This means that a card may have the same consent multiple times with different states. The reason for this is to allow consent to be renewed i.e. if user has granted consent and it is due to expire, then a new consent can be created without interfering with the new one. ## Next Steps {#next-steps} To learn how to use mastercard consent management apis, check out the following [tutorial](https://developer.mastercard.com/consent-management/documentation/tutorials/consents-tutorial/index.md).