{"openapi":"3.0.0","info":{"title":"3DSecure v2.2 ACS AReq/ARes","description":"3DSecure v2.2 ACS AReq/ARes","contact":{"email":"owen.obyrne@fire.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"version":"1.0.0"},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/Mrrkha/3ds2.0/1.0.0"},{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/Mrrkha/3ds2/1.0.0"},{"url":"https://virtserver.swaggerhub.com/fire/openapi-3dsecure-v2.2-acs-areq-ares/1.0.0","description":"SwaggerHub API Auto Mocking"}],"paths":{"/authentication":{"post":{"summary":"Handles AReq and ARes messages","description":"Handles AReq and ARes messages","operationId":"handleAReq","requestBody":{"description":"The AReq message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AReq"}}}},"responses":{"200":{"description":"The ARes message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ARes"}}}},"400":{"description":"invalid input, object invalid"}},"x-swagger-router-controller":"Default"}}},"components":{"schemas":{"AReq":{"required":["acctNumber","browserAcceptHeader","browserJavascriptEnabled","browserLanguage","browserUserAgent","deviceChannel","deviceRenderOptions","messageCategory","messageType","messageVersion","notificationURL","sdkAppID","sdkEphemPubKey","sdkMaxTimeout","sdkReferenceNumber","sdkTransID","threeDSCompInd","threeDSRequestorAuthenticationInd","threeDSRequestorID","threeDSRequestorName","threeDSRequestorURL","threeDSServerRefNumber","threeDSServerTransID","threeDSServerURL","threeRIInd"],"type":"object","properties":{"threeDSCompInd":{"type":"string","description":"Indicates whether the 3DS Method successfully completed.","example":"Y","enum":["Y","N","U"]},"threeDSRequestorAuthenticationInd":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request.","example":"01"},"threeDSRequestorChallengeInd":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates whether a challenge is requested for this transaction. For example: For 01-PA, a 3DS Requestor may have concerns about the transaction, and request a challenge. For 02-NPA, a challenge may be necessary when adding a new card to a wallet. For local/regional mandates or other variables.","example":"01"},"threeDSRequestorDecMaxTime":{"type":"string","description":"Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes).","example":"5"},"threeDSRequestorDecReqInd":{"type":"string","description":"Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use.","example":"Y","enum":["Y","N"]},"threeDSRequestorID":{"maxLength":35,"type":"string","description":"DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis.","example":"RID73289587934"},"threeDSRequestorName":{"maxLength":40,"type":"string","description":"DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis.","example":"ACME LTD"},"threeDSRequestorURL":{"maxLength":2048,"type":"string","description":"Fully qualified URL of 3DS Requestor website or customer care site. This data element provides additional information to the receiving 3-D Secure system if a problem arises and should provide contact information","format":"uri","example":"https://server.domainname.com"},"threeDSServerRefNumber":{"maxLength":32,"type":"string","description":"Unique identifier assigned by the EMVCo secretariat upon testing and approval. ","example":"EMVCO-ID-Num"},"threeDSServerOperatorID":{"maxLength":32,"type":"string","description":"DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS Server on an individual basis.","example":"SERVER-ID"},"threeDSServerTransID":{"type":"string","description":"Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.","format":"uuid","example":"179eec9e-18da-4030-b1aa-7eb249799b6f"},"threeDSServerURL":{"maxLength":2048,"type":"string","description":"Fully qualified URL of the 3DS Server to which the DS will send the RReq message after the challenge has completed. Incorrect formatting will result in a failure to deliver the transaction results via the RReq message.","format":"uri","example":"https://server.domainname.com"},"threeRIInd":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing a 3RI request.","example":"01"},"acctType":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates the type of account. For example, for a multi-account card product.","example":"01"},"acquirerBIN":{"maxLength":11,"type":"string","description":"Acquiring institution identification code as assigned by the DS receiving the AReq message.","example":"534632"},"acquirerMerchantID":{"maxLength":35,"type":"string","description":"Acquirer-assigned Merchant identifier. This may be the same value that is used in authorisation requests sent on behalf of the 3DS Requestor and is represented in ISO 8583 formatting requirements.","example":"348252345"},"acsChallengeMandated":{"type":"string","description":"Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.","example":"Y","enum":["Y","N"]},"acsDecConInd":{"type":"string","description":"Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder.","example":"Y","enum":["Y","N"]},"acsEphemPubKey":{"type":"string","description":"Public key component of the ephemeral key pair generated by the ACS and used to establish session keys between the 3DS SDK and the ACS."},"addrMatch":{"type":"string","description":"Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same.","example":"Y","enum":["Y","N"]},"broadInfo":{"type":"object","description":"Unstructured information sent between the 3DS Server, the DS and the ACS."},"browserAcceptHeader":{"maxLength":2048,"type":"string","description":"Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser.","example":"application/json"},"browserIP":{"maxLength":45,"type":"string","description":"IP address of the browser as returned by the HTTP headers to the 3DS Requestor.","example":"1.2.3.4"},"browserJavaEnabled":{"type":"boolean","description":"Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.","example":true},"browserJavascriptEnabled":{"type":"boolean","description":"Boolean that represents the ability of the cardholder browser to execute JavaScript.","example":true},"browserLanguage":{"maxLength":8,"type":"string","description":"Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.","example":"en-ie"},"browserColorDepth":{"type":"string","description":"Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.","example":"24","enum":["1","4","8","15","16","24","32","48"]},"browserScreenHeight":{"maxLength":6,"type":"string","description":"Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.","example":"768"},"browserScreenWidth":{"maxLength":6,"type":"string","description":"Total width of the cardholder's screen in pixels. Value is returned from the screen.width property.","example":"1024"},"browserTZ":{"maxLength":5,"type":"string","description":"Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Value is returned from the getTimezoneOffset() method. Time zone offset values are in minutes","example":"300"},"browserUserAgent":{"maxLength":2048,"type":"string","description":"Exact content of the HTTP user-agent header.","example":"Mozilla 5.2/12"},"cardExpiryDate":{"maxLength":4,"minLength":4,"type":"string","description":"Expiry Date of the PAN or token supplied to the 3DS Requestor by the Cardholder.","example":"0424"},"acctNumber":{"maxLength":19,"minLength":13,"type":"string","description":"Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, token.","example":"5432123412341234"},"acctID":{"maxLength":64,"type":"string","description":"Additional information about the account optionally provided by the 3DS Requestor.","example":"347592"},"billAddrCity":{"maxLength":50,"type":"string","description":"The city of the Cardholder billing address associated with the card used for this purchase.","example":"Dublin"},"billAddrCountry":{"maxLength":3,"minLength":3,"type":"string","description":"The country of the Cardholder billing address associated with the card used for this purchase.","example":"IRL"},"billAddrLine1":{"maxLength":50,"type":"string","description":"First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.","example":"50, The Road"},"billAddrLine2":{"maxLength":50,"type":"string","description":"Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.","example":"The Area"},"billAddrLine3":{"maxLength":50,"type":"string","description":"Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.","example":"The Town"},"billAddrPostCode":{"maxLength":16,"type":"string","description":"ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.","example":"D01 NH23"},"billAddrState":{"maxLength":3,"type":"string","description":"The state or province of the Cardholder billing address associated with the card used for this purchase.","example":"NY"},"email":{"maxLength":254,"type":"string","description":"The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor.","format":"email","example":"test@example.com"},"cardholderName":{"maxLength":45,"minLength":2,"type":"string","description":"Name of the Cardholder.","example":"Sean O Brien"},"deviceChannel":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates the type of channel interface being used to initiate the transaction.","example":"01"},"dsReferenceNumber":{"maxLength":32,"type":"string","description":"EMVCo-assigned unique identifier to track approved DS.","example":"2347658923745"},"dsTransID":{"type":"string","description":"Universally unique transaction identifier assigned by the DS to identify a single transaction. ","format":"uuid","example":"179eec9e-18da-4030-b1aa-7eb249799b6f"},"dsURL":{"maxLength":2048,"type":"string","description":"URL of the DS to which the ACS will send the RReq if a challenge occurs. The ACS is responsible for storing this value for later use in the transaction for sending the RReq to the DS.","format":"uri","example":"https://example.domain.com"},"payTokenSource":{"maxLength":2,"minLength":2,"type":"string","description":"This data element will be populated by the system residing in the 3-D Secure domain where the detokenisation occurs.","example":"01"},"purchaseInstalData":{"maxLength":3,"type":"string","description":"Indicates the maximum number of authorisations permitted for instalment payments.","example":"02"},"mcc":{"maxLength":4,"minLength":4,"type":"string","description":"DS-specific code describing the Merchant's type of business, product or service.","example":"7995"},"merchantCountryCode":{"maxLength":3,"minLength":3,"type":"string","description":"Country Code of the Merchant. ","example":"IRL"},"merchantName":{"maxLength":40,"type":"string","description":"Merchant name assigned by the Acquirer or Payment System. ","example":"ACME LTD"},"messageCategory":{"maxLength":2,"minLength":2,"type":"string","description":"Identifies the category of the message for a specific use case.","example":"01"},"messageExtension":{"type":"array","items":{"$ref":"#/components/schemas/MessageExtension"}},"messageType":{"type":"string","description":"Identifies the type of message that is passed.","example":"AReq","enum":["AReq"]},"messageVersion":{"maxLength":8,"minLength":5,"type":"string","description":"Protocol version identifier. This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction.","example":"FIXME"},"notificationURL":{"maxLength":256,"type":"string","description":"Fully qualified URL of the system that receives the CRes message or Error Message. The CRes message is posted by the ACS through the Cardholder browser at the end of the challenge and receipt of the RRes message.","format":"uri","example":"https://example.domain.com"},"purchaseAmount":{"maxLength":48,"type":"string","description":"Purchase amount in minor units of currency with all punctuation removed. When used in conjunction with the Purchase Currency Exponent field, proper punctuation can be calculated. ","example":"1999"},"purchaseCurrency":{"maxLength":3,"minLength":3,"type":"string","description":"Currency in which purchase amount is expressed.","example":"978"},"purchaseExponent":{"maxLength":1,"minLength":1,"type":"string","description":"Minor units of currency as specified in the ISO 4217 currency exponent.","example":"2"},"purchaseDate":{"maxLength":14,"minLength":14,"type":"string","description":"Date and time of the purchase expressed in UTC.","example":"20190531152312"},"recurringExpiry":{"maxLength":8,"minLength":8,"type":"string","description":"Date after which no further authorisations shall be performed.","example":"20190821"},"recurringFrequency":{"maxLength":4,"type":"string","description":"Indicates the minimum number of days between authorisations.","example":"31"},"sdkAppID":{"type":"string","description":"Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.","format":"uuid","example":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"},"sdkEncData":{"maxLength":64000,"type":"string","description":"JWE Object (represented as a string) as defined in Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt. Note: This element is the only field encrypted in this version of the EMV 3D Secure specification.","example":"eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoiSEc2MUM0UURMV1ZGU002TjFZQkgyMXJkZ1BqNVpzRTNHOTZPUFJ4REpLT1R6ejVJayIsIml2IjoieGI0eHEyR2hvaDlSbnNPVSIsInRhZyI6ImRVeHNBRDV2ZURuWVdhaXF5ZXpCNWcifQ.MaQVGt6rsucf58ma1kLsRSIPOHPwjdQM6YlhF6WYI8NEtajLXYwzzywvPMtvJB7ef5GIl1Jwy2wT4sMbCmKd0g._nWJK9944KY3kFdMT23IrA.yvc_JUX6leJxi91mgIAEpd2pGIuhXDoGNMYTUfhDFCxwqMbZwbSayOvWwk58ftCnB72HCK3lGkXmw2xkk32Iqbu4NpyLBQXA13969KpX4o2sq65anuHyX2Xg5oZ6EXz8hBzY7_XmnYD4-LYGdkU14dYZcRJ7glZohXP-BrNWhUlM-4n_SQgm1FQIgDjvOrNwSX5QlyWWLQXnO9jAhwrSHricgytDXzEnGa7Xn6Dt3hiEk1Ivpu69C9imXhs11QryLln-Z3ngguyQRpYjOlEv_x7Wx6OapfDRhgelloHu3mqHABQnz-VMgyvl11ZHTwQUVnyKZ42b-7giA97Jl-5cZY35H-pm4lmgDUvSnrxcJKQ5OzXESe1XgaYTDE2uysGU.E_R_1bxSep_yGxgfXAht-u4NWVAL0EJ21OEASUXQt5Y"},"transType":{"type":"string","description":"Identifies the type of transaction being authenticated.","example":"01","enum":["01","03","10","11","28"]}}},"ARes":{"required":["acsReferenceNumber","acsTransID","dsReferenceNumber","dsTransID","messageType","messageVersion","sdkTransID","threeDSServerTransID","transStatus"],"type":"object","properties":{"threeDSServerTransID":{"type":"string","description":"Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.","format":"uuid","example":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"},"acsChallengeMandated":{"type":"string","description":"Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable.","example":"Y","enum":["Y","N"]},"acsDecConInd":{"type":"string","description":"Indicates whether the ACS confirms utilisation of Decoupled Authentication and agrees to utilise Decoupled Authentication to authenticate the Cardholder.","example":"Y","enum":["Y","N"]},"acsOperatorID":{"maxLength":32,"type":"string","description":"DS assigned ACS identifier. Each DS can provide a unique ID to each ACS on an individual basis.","example":"3245782395"},"acsReferenceNumber":{"maxLength":32,"type":"string","description":"Unique identifier assigned by the EMVCo Secretariat upon Testing and Approval.","example":"ACS-EMVCO-REF"},"acsSignedContent":{"type":"string","description":"Contains the JWS object (represented as a string) created by the ACS for the ARes message. ","example":"eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.hZnl5amPk_I3tb4O-Otci_5XZdVWhPlFyVRvcqSwnDo_srcysDvhhKOD01DigPK1lJvTSTolyUgKGtpLqMfRDXQlekRsF4XhAjYZTmcynf-C-6wO5EI4wYewLNKFGGJzHAknMgotJFjDi_NCVSjHsW3a10nTao1lB82FRS305T226Q0VqNVJVWhE4G0JQvi2TssRtCxYTqzXVt22iDKkXeZJARZ1paXHGV5Kd1CljcZtkNZYIGcwnj65gvuCwohbkIxAnhZMJXCLaVvHqv9l-AAUV7esZvkQR1IpwBAiDQJh4qxPjFGylyXrHMqh5NlT_pWL2ZoULWTg_TJjMO9TuQ"},"acsTransID":{"type":"string","description":"Universally Unique transaction identifier assigned by the ACS to identify a single transaction.","format":"uuid","example":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"},"authenticationType":{"maxLength":2,"minLength":2,"type":"string","description":"Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message.","example":"01"},"authenticationValue":{"maxLength":28,"minLength":28,"type":"string","description":"Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.","example":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="},"broadInfo":{"type":"object","description":"Unstructured information sent between the 3DS Server, the DS and the ACS."},"cardholderInfo":{"maxLength":128,"type":"string","description":"Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder","example":"Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx."},"dsReferenceNumber":{"maxLength":32,"minLength":32,"type":"string","description":"EMVCo-assigned unique identifier to track approved DS.","example":"12345678901234567890123456789012"},"dsTransID":{"type":"string","description":"Universally unique transaction identifier assigned by the DS to identify a single transaction. ","format":"uuid","example":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"},"eci":{"maxLength":2,"minLength":2,"type":"string","description":"Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.","example":"05"},"messageExtension":{"type":"array","items":{"$ref":"#/components/schemas/MessageExtension"}},"messageType":{"type":"string","description":"Identifies the type of message that is passed.","example":"ARes","enum":["ARes"]},"messageVersion":{"maxLength":8,"minLength":5,"type":"string","description":"Protocol version identifier. This shall be the Protocol Version Number of the specification utilised by the system","example":"3DS-2.2"},"sdkEphemPubKey":{"type":"string","description":"Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS."},"sdkTransID":{"type":"string","description":"Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. ","format":"uuid","example":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"},"transStatus":{"type":"string","description":"Indicates whether a transaction qualifies as an authenticated transaction or account verification.","example":"Y","enum":["Y","N","U","A","C","D","R","I"]},"transStatusReason":{"maxLength":2,"minLength":2,"type":"string","description":"Provides information on why the Transaction Status field has the specified value.","example":"01"},"whiteListStatus":{"type":"string","description":"Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS Requestor.","example":"Y","enum":["Y","N","E","P","R","U"]},"whiteListStatusSource":{"maxLength":2,"minLength":2,"type":"string","description":"This data element will be populated by the system setting Whitelist Status.","example":"01"}},"example":{"acsDecConInd":"Y","acsTransID":"b0d53d99-197c-4bf9-b789-981b5ba1ce51","whiteListStatus":"Y","cardholderInfo":"Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.","broadInfo":{},"eci":"05","sdkEphemPubKey":"sdkEphemPubKey","dsReferenceNumber":"12345678901234567890123456789012","acsReferenceNumber":"ACS-EMVCO-REF","messageType":"ARes","acsRenderingType":{"acsUiTemplate":"01","acsInterface":"01"},"dsTransID":"b0d53d99-197c-4bf9-b789-981b5ba1ce51","whiteListStatusSource":"01","transStatusReason":"01","acsOperatorID":"3245782395","authenticationType":"01","messageVersion":"3DS-2.2","acsSignedContent":"eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.hZnl5amPk_I3tb4O-Otci_5XZdVWhPlFyVRvcqSwnDo_srcysDvhhKOD01DigPK1lJvTSTolyUgKGtpLqMfRDXQlekRsF4XhAjYZTmcynf-C-6wO5EI4wYewLNKFGGJzHAknMgotJFjDi_NCVSjHsW3a10nTao1lB82FRS305T226Q0VqNVJVWhE4G0JQvi2TssRtCxYTqzXVt22iDKkXeZJARZ1paXHGV5Kd1CljcZtkNZYIGcwnj65gvuCwohbkIxAnhZMJXCLaVvHqv9l-AAUV7esZvkQR1IpwBAiDQJh4qxPjFGylyXrHMqh5NlT_pWL2ZoULWTg_TJjMO9TuQ","sdkTransID":"b0d53d99-197c-4bf9-b789-981b5ba1ce51","acsChallengeMandated":"Y","authenticationValue":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=","messageExtension":[{"data":{},"name":"sharedData","criticalityIndicator":true,"id":"234756238475623084576234805"},{"data":{},"name":"sharedData","criticalityIndicator":true,"id":"234756238475623084576234805"}],"transStatus":"Y","threeDSServerTransID":"b0d53d99-197c-4bf9-b789-981b5ba1ce51"}},"MessageExtension":{"required":["criticalityIndicator","data","id","name"],"type":"object","properties":{"name":{"maxLength":64,"type":"string","description":"The name of the extension data set as defined by the extension owner.","example":"sharedData"},"id":{"maxLength":64,"type":"string","description":"A unique identifier for the extension.","example":"234756238475623084576234805"},"criticalityIndicator":{"type":"boolean","description":"A Boolean value indicating whether the recipient must understand the contents of the extension to interpret the entire message.","example":true},"data":{"type":"object","description":"The data carried in the extension."}},"description":"Data necessary to support requirements not otherwise defined in the 3D Secure message are carried in a Message Extension.","example":{"data":{},"name":"sharedData","criticalityIndicator":true,"id":"234756238475623084576234805"}}}}}