This guide outlines all the steps that are required to add 3DS to your gateway integration using the Authentication API, including how to use the authentication result to process a payment.
The Initiate Authentication operation is used to determine the 3DS versions available to you for a given card, which will be based on
The operation also enables any background activities (such as a ACS Method call) to be carried out for purposes such as gathering additional payer data to support a subsequent Authenticate Payer operation.
You can initiate authentication by providing the following fields in the Initiate Authentication request:
Parameter | Existence | Description |
---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. Note that you can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see FAQs. |
order.currency |
Required | The currency of the order. |
transaction.id |
Required | A unique identifier for this payment authentication. |
order.id |
Required | A unique identifier for this order. |
authentication.channel |
Required | The channel in which the authentication request is being initiated. You can specify one of the following:
|
authentication.purpose |
Optional | By default, this field is set to "PAYMENT_TRANSACTION" to indicate that authentication is to be performed when processing a card payment. However, you can specify a different purpose to indicate non-payment authentication. See Submit a Non-Payment Authentication Request. . |
authentication.acceptVersions |
Optional | The 3DS versions that you will accept for this payment. If you do not specify a version, both 3DS1 and 3DS2 will be accepted. The gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed. |
order.merchantCategoryCode |
Optional | Provide the Merchant Category Code if you want to override the default value configured on your acquirer link. |
The gateway returns the following key fields in the Initiate Authentication response:
authentication.version
: If 3DS authentication of the payer is available, this field shows the type 3DS1 or 3DS2. If both are available, 3DS2 is returned.authentication.3ds2.methodSupported
: If 3DS2 is available and if the issuer's ACS supports a Method call, this field shows SUPPORTED. The Method call can be used by the ACS to gather additional data prior to the authentication request to increase the likelihood of frictionless authentication being available. The method call is triggered in a hidden iframe, so is invisible to the payer. It also does not provide any callback upon completion.transaction.authenticationStatus
: Check out this field if you want more details about the authentication status.response.gatewayRecommendation
: This field allows you to determine the next step. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.response.gatewayRecommendation |
Next step |
---|---|
DO_NOT_PROCEED | Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
PROCEED | You can proceed to authenticate the payer using the Authenticate Payer operation. |
authentication.redirectHtml
: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a hidden DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,
div.innerHtml= response.authentication.redirectHtml; eval(document.getElementById('initiate-authentication-script').text)
URL | https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
HTTP Method | PUT |
{ "authentication":{ "acceptVersions":"3DS1,3DS2", "channel":"PAYER_BROWSER", "purpose":"PAYMENT_TRANSACTION" }, "correlationId":"test", "order":{ "currency":"AUD" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>" } } }, "apiOperation":"INITIATE_AUTHENTICATION" }
{ "authentication":{ "3ds2":{ "directoryServerId":"A000000004", "methodCompleted":false, "methodSupported":"SUPPORTED", "protocolVersion":"2.1.0", "requestorId":"test2ID", "requestorName":"test2Name" }, "acceptVersions":"3DS1,3DS2", "channel":"PAYER_BROWSER", "purpose":"PAYMENT_TRANSACTION", "redirect":{ "customized":{ "3DS":{ "methodPostData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5LzIxY2FlYjc1MDIyMGEyMDg0Y2E5MjRkYzhlNTAzYjZhZjIyNDc4NzU5ZjgwODMyMGZmMTZkZDJhZWExNGQyN2MiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9", "methodUrl":"<method_url>" } } }, "redirectHtml":"<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5LzIxY2FlYjc1MDIyMGEyMDg0Y2E5MjRkYzhlNTAzYjZhZjIyNDc4NzU5ZjgwODMyMGZmMTZkZDJhZWExNGQyN2MiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>", "version":"3DS2" }, "correlationId":"test", "merchant":"TEST_3DS2-1", "order":{ "authenticationStatus":"AUTHENTICATION_AVAILABLE", "creationTime":"2019-10-28T05:00:27.234Z", "currency":"AUD", "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "lastUpdatedTime":"2021-04-12T01:29:25.551Z", "merchantCategoryCode":"1234", "status":"AUTHENTICATION_INITIATED", "totalAuthorizedAmount":0, "totalCapturedAmount":0, "totalRefundedAmount":0 }, "response":{ "gatewayCode":"AUTHENTICATION_IN_PROGRESS", "gatewayRecommendation":"PROCEED" }, "result":"SUCCESS", "sourceOfFunds":{ "provided":{ "card":{ "number":"512345xxxxxx0008", "scheme":"MASTERCARD" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-12T01:29:25.551Z", "timeOfRecord":"2019-10-28T05:00:27.234Z", "transaction":{ "amount":0, "authenticationStatus":"AUTHENTICATION_AVAILABLE", "currency":"AUD", "id":"42090084", "type":"AUTHENTICATION" }, "version":"60" }
{ "authentication":{ "3ds1":{ "veResEnrolled":"Y" }, "acceptVersions":"3DS1,3DS2", "channel":"PAYER_BROWSER", "purpose":"PAYMENT_TRANSACTION", "redirect":{ "customized":{ "3DS":{ "methodPostData":"e30=", "methodUrl":"<method_url>" } } }, "redirectHtml":"<script id=\"initiate-authentication-script\"></script>", "version":"3DS1" }, "correlationId":"test", "merchant":"TEST_3DS2-1", "order":{ "authenticationStatus":"AUTHENTICATION_AVAILABLE", "creationTime":"2021-04-13T02:52:24.532Z", "currency":"AUD", "id":"3bdbe65b-d0db-4a7d-a8a1-59ae3723da77", "lastUpdatedTime":"2021-04-12T01:40:40.317Z", "merchantCategoryCode":"1234", "status":"AUTHENTICATION_INITIATED", "totalAuthorizedAmount":0, "totalCapturedAmount":0, "totalRefundedAmount":0 }, "response":{ "gatewayCode":"AUTHENTICATION_IN_PROGRESS", "gatewayRecommendation":"PROCEED" }, "result":"SUCCESS", "sourceOfFunds":{ "provided":{ "card":{ "number":"512345xxxxxx8246", "scheme":"MASTERCARD" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-12T01:40:40.317Z", "timeOfRecord":"2021-04-13T02:52:24.532Z", "transaction":{ "amount":0, "authenticationStatus":"AUTHENTICATION_AVAILABLE", "currency":"AUD", "id":"2e1d", "type":"AUTHENTICATION" }, "version":"60" }
Where the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), and once all payer and payment data has been gathered, you can submit the Authenticate Payer request. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.
Submit this operation by providing the following fields. If you only support 3DS1, the gateway ignores the fields specific to 3DS2.
Parameter | Existence | Description |
---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. |
order.amount |
Required | The total amount of the order. |
transaction.id |
Required | The same transaction.id as the Initiate Authentication operation that preceded it. |
order.id |
Required | The same order.id as the Initiate Authentication operation that preceded it. |
authentication.redirectResponseUrl |
Optional | The URL to which you want to redirect the payer after completing the payer authentication process. You must provide this URL, unless you are certain that there will be no interaction with the payer. |
order.merchantCategoryCode |
Optional | If you do not provide a value, the default configured on your merchant profile will be used. |
device.browser |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER. |
device.ipAddress |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation. |
device.browserDetails parameter group |
Optional | Required if you support 3DS2 and if authentication.channel=PAYER_BROWSER. |
billing.address parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
shipping.address parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
customer parameter group |
Optional | Applies only to 3DS2. It's strongly recommended that you include this in your request whenever available. |
The gateway returns the following key fields in the Authenticate Payer response:
transaction.authenticationStatus
: Check out this field if you want more details about the authentication status.response.gatewayRecommendation
: This field allows you to determine whether you should proceed to a financial transaction or not. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.response.gatewayRecommendation |
Next step |
---|---|
DO_NOT_PROCEED | Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
PROCEED | You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow). |
authentication.redirectHtml
: Insert the content of this field into the page being displayed to the payer. To do this, add the text content to a DIV element and specify the script identifier in the HTML DOM. This will construct and post the form automatically. For example,
div.innerHtml= response.authentication.redirectHtml; eval(document.getElementById('authenticate-payer-script').text)
This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.
This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.
You can determine the authentication outcome using the value returned in the response.gatewayRecommendation
field. This recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.
If you want additional response data, you can use the Retrieve Transaction operation.
response.gatewayRecommendation |
Next step |
---|---|
DO_NOT_PROCEED | Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method. |
PROCEED | You can proceed with the payment as authentication is granted. |
The fields returned in the Authentication Payer response depend on the flow in effect (frictionless vs challenge), how the authentication request was initiated (authentication.channel), and the authentication mechanism for the request (session or certificate or password).
The following fields are returned for a certificate/password authenticated request. For a session-authenticated operation, the response is filtered to remove data that's not related to the payer and only whitelisted fields are returned. For more information, see session-authentication.
Response Field |
Merchant-authenticated |
---|---|
authentication.method | Yes |
authentication.3ds.authenticationToken | * |
authentication.3ds.acsEci | Yes |
authentication.3ds.transactionId | Yes |
authentication.3ds2.transactionStatus | * |
authentication.3ds2.acsTransactionId | * |
authentication.3ds2.dsTransactionId | * |
authentication.3ds2.3dsServerTransactionId | * |
authentication.3ds2.3dsServerTransactionId | * |
authentication.3ds2.protocolVersion | * |
authentication.3ds1.veResEnrolled | * |
authentication.redirectHtml | Yes |
response.gatewayRecommendation | Yes |
transaction.type | Yes |
version | Yes |
timeOfRecord | Yes |
result | Yes |
response.debugInformation | * |
URL | https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
HTTP Method | PUT |
{ "authentication":{ "redirectResponseUrl":"<host>/merchantSimulator/jsp/simple/output.jsp" }, "correlationId":"test", "device": { "browser": "MOZILLA", "browserDetails": { "3DSecureChallengeWindowSize": "FULL_SCREEN", "acceptHeaders": "application/json", "colorDepth": 24, "javaEnabled": true, "language": "en-US", "screenHeight": 640, "screenWidth": 480, "timeZone": 273 }, "ipAddress": "127.0.0.1" }, "order":{ "amount":"100", "currency":"AUD" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>", "expiry":{ "month":"1", "year":"39" } } } }, "apiOperation": "AUTHENTICATE_PAYER" }
{ "authentication":{ "3ds":{ "transactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91" }, "3ds2":{ "3dsServerTransactionId":"8c4a911c-289a-46c2-a615-887e1cc01a6a", "acsTransactionId":"2a8234c9-e8ac-449d-a693-97a113b491fc", "directoryServerId":"A000000004", "dsTransactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91", "methodCompleted":false, "methodSupported":"SUPPORTED", "protocolVersion":"2.1.0", "requestorId":"test2ID", "requestorName":"test2Name", "transactionStatus":"C" }, "method":"OUT_OF_BAND", "payerInteraction":"REQUIRED", "redirect":{ "customized":{ "3DS":{ "acsUrl":"https://<host_name>/acs/v2/prompt", "cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9" } }, "domainName":"<domain_name>" }, "redirectHtml":"<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); e.remove(); } </script> </div>", "version":"3DS2" }, "correlationId":"test", "device":{ "browser":"MOZILLA", "ipAddress":"127.0.0.1" }, "merchant":"TEST_3DS2-1", "order":{ "amount":100, "authenticationStatus":"AUTHENTICATION_PENDING", "creationTime":"2021-04-13T02:22:59.113Z", "currency":"AUD", "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "lastUpdatedTime":"2021-04-13T02:44:07.161Z", "merchantCategoryCode":"1234", "status":"AUTHENTICATION_INITIATED", "totalAuthorizedAmount":0, "totalCapturedAmount":0, "totalRefundedAmount":0, "valueTransfer":{ "accountType":"NOT_A_TRANSFER" } }, "response":{ "gatewayCode":"PENDING", "gatewayRecommendation":"PROCEED" }, "result":"PENDING", "sourceOfFunds":{ "provided":{ "card":{ "expiry":{ "month":"1", "year":"39" }, "number":"512345xxxxxx0008", "scheme":"MASTERCARD" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-13T02:44:07.161Z", "timeOfRecord":"2021-04-13T02:22:59.113Z", "transaction":{ "acquirer":{ "merchantId":"99554411" }, "amount":100, "authenticationStatus":"AUTHENTICATION_PENDING", "currency":"AUD", "id":"42090084", "type":"AUTHENTICATION" }, "version":"60" }
{ "authentication":{ "3ds1":{ "veResEnrolled":"Y" }, "payerInteraction":"REQUIRED", "redirect":{ "domainName":"<domain_name>" }, "redirectHtml":"<div id=\"redirectTo3ds1AcsSimple\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"redirectTo3ds1Frame\" name=\"redirectTo3ds1Frame\" height=\"100%\" width=\"100%\" > </iframe> <form id =\"redirectTo3ds1Form\" method=\"POST\" action=\"https://<host_name>/acs/b6594e88-608f-4897-a8b5-dd491dc1e54d\" target=\"redirectTo3ds1Frame\"> <input type=\"hidden\" name=\"PaReq\" value=\"eAFVUd9vgjAQfjfxfyBkr6OlgENz1uDUaBadmZr9eFlYaYRFwNEi7r9fizC3e7rvu97Xu+9gdE4PxokXIsmzoWlb2DR4xvIoyfZDc7ed3frmiHY7sI0LzicbzsqCU1hyIcI9N5JI9XiuT8hdz6SwDp74F4VGjio1iwBqoeoqWBxmkkLIvsaLFbWbANQQkPJiMaGSCwnokkMWppxulo8P03dnslF6NQEsLzNZfFPs9AC1AMriQGMpjwOEqqqyRJrIWFgsTwHpEqDrDOtSTyPUNuckovPpYo484o53n1XwHK9Orx9sFvRexFs+BKRfQBRKTgm2+9gnvoGdgY0H2AVU8xCmeiAa7CbGjY2xhbHa6sLBUX8VXICq6dJfCpSphXK9XaZFwM/HPONKVW39mwO6Tn4/114yqTzzbOK4Xr8On7jKlKagVRJlFLGxV8toAEi3ouZgypX6nor5d+du5wf/BK8K\" /> <input type=\"hidden\" name=\"TermUrl\" value=\"https://<host_name>/callbackInterface/gateway/e91c0cc18c143f205a081cde25a3a8cec28b04bb90169115295beb29d0c1dc28\" /> <input type=\"hidden\" name=\"MD\" value=\"\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectTo3ds1Form\"); if (e) { e.submit(); e.remove(); } </script> </div>", "version":"3DS1" }, "correlationId":"test", "device":{ "browser":"MOZILLA", "ipAddress":"127.0.0.1" }, "merchant":"TEST_3DS2-1", "order":{ "amount":100, "authenticationStatus":"AUTHENTICATION_PENDING", "creationTime":"2021-04-13T02:52:24.532Z", "currency":"AUD", "id":"3bdbe65b-d0db-4a7d-a8a1-59ae3723da77", "merchantCategoryCode":"1234", "status":"AUTHENTICATION_INITIATED", "totalAuthorizedAmount":0, "totalCapturedAmount":0, "totalRefundedAmount":0, "valueTransfer":{ "accountType":"NOT_A_TRANSFER" } }, "response":{ "gatewayCode":"PENDING", "gatewayRecommendation":"PROCEED" }, "result":"PENDING", "sourceOfFunds":{ "provided":{ "card":{ "expiry":{ "month":"1", "year":"39" }, "number":"512345xxxxxx8246", "scheme":"MASTERCARD" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-13T02:54:19.182Z", "timeOfRecord":"2021-04-13T02:52:24.532Z", "transaction":{ "acquirer":{ "merchantId":"99554411" }, "amount":100, "authenticationStatus":"AUTHENTICATION_PENDING", "currency":"AUD", "id":"three", "type":"AUTHENTICATION" }, "version":"60" }
When the result of the Authenticate Payer operation indicates that you can proceed with the payment (response.gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:
URL | https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID> |
HTTP Method | PUT |
{ "apiOperation":"PAY", "authentication":{ "transactionId":"<your_transaction_ID>" }, "order":{ "amount":"100", "currency":"AUD", "reference":"<your_order_ID>" }, "sourceOfFunds":{ "provided":{ "card":{ "number":"<card_number>", "expiry":{ "month":"1", "year":"39" } } }, "type":"CARD" }, "transaction":{ "reference":"<your_order_ID>" } }
{ "authentication":{ "3ds":{ "acsEci":"02", "authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af" }, "3ds2":{ "dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af", "protocolVersion":"2.1.0", "transactionStatus":"Y" }, "transactionId":"249213216", "version":"3DS2" }, "authorizationResponse":{ "posData":"1605S0100130", "transactionIdentifier":"TidTest" }, "device":{ "browser":"MOZILLA", "ipAddress":"127.0.0.1" }, "gatewayEntryPoint":"WEB_SERVICES_API", "merchant":"TEST_3DS2-1", "order":{ "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "chargeback":{ "amount":0, "currency":"AUD" }, "creationTime":"2021-04-13T02:11:06.102Z", "currency":"AUD", "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "lastUpdatedTime":"2021-04-13T02:11:57.049Z", "merchantAmount":100.00, "merchantCategoryCode":"1234", "merchantCurrency":"AUD", "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "status":"CAPTURED", "totalAuthorizedAmount":100.00, "totalCapturedAmount":100.00, "totalRefundedAmount":0.00 }, "response":{ "acquirerCode":"00", "gatewayCode":"APPROVED" }, "result":"SUCCESS", "sourceOfFunds":{ "provided":{ "card":{ "brand":"MASTERCARD", "expiry":{ "month":"1", "year":"39" }, "fundingMethod":"CREDIT", "issuer":"<issuer>", "number":"512345xxxxxx0008", "scheme":"Mastercard", "storedOnFile":"NOT_STORED" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-13T02:11:57.049Z", "timeOfRecord":"2021-04-13T02:11:56.973Z", "transaction":{ "acquirer":{ "batch":1, "id":"<acquirer_id>", "merchantId":"99554411" }, "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "authorizationCode":"028941", "currency":"AUD", "id":"1", "receipt":"1908266016", "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496", "source":"INTERNET", "stan":"496", "terminal":"1234", "type":"PAYMENT" }, "version":"60" }
{ "authentication":{ "3ds":{ "acsEci":"02", "authenticationToken":"jHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId":"3nzQOuTJDVOsRLuDT9V671B8QkU=" }, "3ds1":{ "paResStatus":"Y", "veResEnrolled":"Y" }, "transactionId":"5791", "version":"3DS1" }, "authorizationResponse":{ "posData":"1605S0100130", "transactionIdentifier":"TidTest" }, "device":{ "browser":"MOZILLA", "ipAddress":"127.0.0.1" }, "gatewayEntryPoint":"WEB_SERVICES_API", "merchant":"TEST_3DS2-1", "order":{ "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "chargeback":{ "amount":0, "currency":"AUD" }, "creationTime":"2021-04-13T03:17:44.895Z", "currency":"AUD", "id":"f808076a-0bc6-4f1b-8100-cfe46e43676e", "lastUpdatedTime":"2021-04-13T03:19:45.964Z", "merchantAmount":100.00, "merchantCategoryCode":"1234", "merchantCurrency":"AUD", "reference":"9b57808a-474e-445d-b2ca-09d571f5ea75", "status":"CAPTURED", "totalAuthorizedAmount":100.00, "totalCapturedAmount":100.00, "totalRefundedAmount":0.00 }, "response":{ "acquirerCode":"00", "gatewayCode":"APPROVED" }, "result":"SUCCESS", "sourceOfFunds":{ "provided":{ "card":{ "brand":"MASTERCARD", "expiry":{ "month":"1", "year":"39" }, "fundingMethod":"CREDIT", "issuer":"<issuer>", "number":"512345xxxxxx8246", "scheme":"Mastercard", "storedOnFile":"NOT_STORED" } }, "type":"CARD" }, "timeOfLastUpdate":"2021-04-13T03:19:45.964Z", "timeOfRecord":"2021-04-13T03:19:45.703Z", "transaction":{ "acquirer":{ "batch":1, "id":"<acquirer_id>", "merchantId":"99554411" }, "amount":100.00, "authenticationStatus":"AUTHENTICATION_SUCCESSFUL", "authorizationCode":"003879", "currency":"AUD", "id":"1", "receipt":"1908286018", "reference":"9b57808a-474e-445d-b2ca-09d571f5ea75", "source":"INTERNET", "stan":"499", "terminal":"1234", "type":"PAYMENT" }, "version":"60" }
If you wish to retrieve the authentication results at any stage, use the Retrieve Transaction operation. Note that fields that are only used during the authentication, for example, authentication.redirectHtml
, are not persisted in the gateway hence not returned.
If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Authorize or Pay operation.
All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication version (3DS1 or 3DS2) and the status of the transaction. However, if you have the data it's recommended that you provide it.
authentication.3ds.acsEci
: The Electronic Commerce Indicator that may be returned to you in the authentication response message.authentication.3ds.authenticationToken
: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.authentication.3ds.transactionId
: A unique transaction identifier generated by the gateway for the 3DS authentication. authentication.3ds1.paResStatus:
Indicates the result of payer authentication with the issuer. authentication.3ds1.veResEnrolled:
Indicates whether or not payer authentication is available for the card number you provided. authentication.3ds2.protocolVersion
: The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo. For example, 2.1.0authentication.3ds2.transactionStatus
: Indicates the result of payer authentication with the issuer.authentication.3ds2.statusReasonCode
: A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus
. You must provide this when authentication.3ds2.transactionStatus
returns N, U, or R.authentication.3ds.authenticationToken
.If you want to perform authentication to only verify the identity of the payer without proceeding to the payment, you must indicate the authentication purpose in the Initiate Authentication
request. For example, you may want to authenticate the payer when the payer enters their card details for later use during customer registration or account creation on your website. The ability to complete the authentication process in a non-payment environment enhances payer experience and reduces payer drop-off rates.
To perform a non-payment authentication, provide the following fields in the Initiate Authentication
request:
If the authentication scheme does not support the purpose you have requested, the gateway returns AUTHENTICATION_NOT_SUPPORTED
in the response. Note that by default the gateway sets this field to PAYMENT_TRANSACTION
to allow the authentication to be used for a payment transaction.
If you have used a payment session (session Id) to store the authentication details, the POST request submitted by the payer’s browser to your website on completion of the Authenticate Payer request will be parameterised allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data
, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. To do this, you can submit a Retrieve Transaction request or choose to decrypt the encrypted authentication data (see the following steps):
encryptedData
field. It is an encrypted JSON object containing the authentication data obtained during the authentication process. It contains the following fields:
encryptedData.ciphertext
authentication.3ds.acsEci
authentication.3ds.authenticationToken
authentication.3ds.transactionId
authentication.3ds1.veResEnrolled
authentication.3ds1.paResStatus
authentication.3ds2.transactionStatus
authentication.3ds2.dsTransactionId
transaction.authenticationStatus
authentication.3ds2.statusReasonCode
sourceOfFunds.provided.card.number
sourceOfFunds.provided.card.expiry.month
sourceOfFunds.provided.card.expiry.year
sourceOfFunds.token
order.id
transaction.id
encryptedData.nonce
encryptedData.tag
public final class SessionDataDecrypter { /** * The algorithm used for encryption/decryption */ private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding"; /** * The algorithm to be associated with the secret key material */ private static final String SYMMETRIC_KEY_TYPE = "AES"; /** * The secret key associated with the session, as returned in the session.aes256Key in a Create Session response. */ private final byte[] key; /** * Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key * field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and * authenticate data for that session. * * @param encodedKey Key to be used for decryption. */ public SessionDataDecrypter(String encodedKey) { key = Base64.getDecoder().decode(encodedKey); } /** * Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce. * The tag is used to authenticate the ciphertext. * * @param ciphertext Encrypted and authenticated session data * @param nonce Nonce/Initialization vector associated with the ciphertext * @param tag Authentication tag * @return The decrypted session data * @throws AEADBadTagException if the data cannot be authenticated with the given tag * @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been * correctly retrieved from the response field * @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should * not be thrown in a correctly set up environment */ public String decrypt(String ciphertext, String nonce, String tag) throws GeneralSecurityException { Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE); // The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext); byte[] tagBytes = Base64.getDecoder().decode(tag); byte[] input = new byte[encryptedBytes.length + tagBytes.length]; System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length); System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length); // Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector byte[] iv = Base64.getDecoder().decode(nonce); GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv); final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM); decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec); // Perform the decryption and return the value. byte[] decryptedBytes = decrypter.doFinal(input); return new String(decryptedBytes, StandardCharsets.UTF_8); } }
Aggregator merchants can enable their sub-merchants to use the Authentication API on the gateway. The sub-merchants are not required to have a contractual relationship with the acquirer nor with the gateway. The aggregator merchant can submit the sub-merchant details required for initiating the authentication via the Initiate Authentication
operation. For more information, see Aggregator Support.
You can use the Authentication API as a server-side or a client-side API.
The Authentication API records the details of the payer authentication using 3DS1 or 3DS2 as a separate AUTHENTICATION transaction on the order.
When you retrieve an order using the Retrieve Order operation or receive a Reporting API response, it may contain an additional AUTHENTICATION transaction. Also, when you use Webhook Notifications, you may receive an additional notification for the AUTHENTICATION transaction.
For details about AUTHENTICATION transactions please refer to the list of response parameters for the Authenticate Payer operation.
You can use network tokens for payer authentication from API v55 onwards. The Suncorp Gateway currently supports processing network tokens obtained from the following tokenization service providers: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).
If you have obtained a network token by integrating directly to the network tokenization service provider, then you must supply token details using the following fields:
sourceOfFunds.type=SCHEME_TOKEN
: Enables the gateway to identify the source of fund provided in the request as a network token. MDES and VTS are supported from API v51 and v53 respectively.sourceOfFunds.provided.card.number
: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token".sourceOfFunds.provided.card.expiry
: (optional) The network token expiry. If you have been enabled for network tokenization by your payment service provider, any request to the gateway for a gateway token will also attempt to generate a corresponding network token for enabled schemes, where supported by the card issuer. The gateway will also attempt network tokenization for any applicable cards already stored in the gateway token repository. The Initiate Authentication request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used. This model currently only supports MDES tokens.
You can use device payment tokens for payer authentication, from API v55 onwards. Only payment tokens obtained from Google Pay SDK are supported. You can provide an encrypted payment token or the "pan" obtained from a decrypted payment token for payer authentication. The gateway only accepts authentication requests with FPAN, requests with DPANs will be rejected. To supply card details via payment token, provide the following field:
order.walletProvider
=GOOGLE_PAY
sourceOfFunds.provided.card.devicePayment.paymentToken
: Applicable only if payment token is decrypted by the gateway. It's the encrypted payment token obtained from the Google Pay SDK.sourceOfFunds.provided.card.number
: Applicable only if payment token is decrypted by you. The value corresponding to the Google Pay JSON Key "pan".The Authenticate Payer request can take a large volume of information about the payer and the transaction. For example, you can provide the following data in the request using the fields in the customer.account
parameter group, which helps the issuer's ACS to assess the level of risk associated with the activity. This means in the case of legitimate payments it helps the ACS to confirm that the payer is likely to be the actual cardholder.
customer.account.history.creationDate
customer.account.history.lastUpdated
customer.account.history.passwordLastChanged
customer.account.history.addCardAttempts
customer.account.history.annualActivity
customer.account.history.recentActivity
customer.account.history.shippingAddressDate
customer.account.history.issuerAuthentication.acsTransactionId
customer.account.history.issuerAuthentication.time
customer.account.history.issuerAuthentication.type
customer.account.history.suspiciousActivity
customer.account.authentication.method
customer.account.authentication.time
You can also provide the following recommended fields for each card scheme in the Authenticate Payer request. Note that this list is not definitive and may be subject to change.
Field | Mastercard | Visa | American Express | Notes |
---|---|---|---|---|
shipping.contact.email | - | - | Y | Required to calculate merchant risk |
shipping.method | - | - | Y | Required to calculate merchant risk |
order.valueTransfer.amount | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
order.valueTransfer.numberOfCards | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
order.valueTransfer.currency | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
order.supply.preorderAvailabilityDate | - | - | Y | Required to calculate merchant risk |
order.supply.preorder | - | - | Y | Required to calculate merchant risk |
order.supply.reorder | - | - | Y | Required to calculate merchant risk |
order.valueTransfer.accountType | - | Y | - | Required by Visa and by other schemes in certain markets (e.g. Brazil). Not applicable if order.valueTransfer.accountType=NOT_A_TRANSFER |
The gateway provides the authentication status in the transaction.authenticationStatus
field. This field may return one of the following values depending on the authentication stage:
AUTHENTICATION_ATTEMPTED
: Payer authentication was attempted and a proof of authentication attempt was obtained.AUTHENTICATION_AVAILABLE
: Payer authentication is available for the payment method provided.AUTHENTICATION_FAILED
: The payer was not authenticated. You should not proceed with this transaction.AUTHENTICATION_NOT_SUPPORTED
: The requested authentication method is not supported for this payment method.AUTHENTICATION_NOT_IN_EFFECT
: There is no authentication information associated with this transaction.AUTHENTICATION_PENDING
: Payer authentication is pending completion of a challenge process.AUTHENTICATION_REJECTED
: The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.AUTHENTICATION_REQUIRED
: Payer authentication is required for this payment, but was not provided.AUTHENTICATION_SUCCESSFUL
: The payer was successfully authenticated.AUTHENTICATION_UNAVAILABLE
: The payer was not able to be authenticated due to a technical or other issue.You can view authentication details for both individual authentications and authentications that proceeded with the payment in the Merchant Administration portal. Search for the order or transaction in the search page and view the authentication details.
If you want to view authentication details for a 3DS1 authentication, for example, to view data for fields such as PARes, PAReq, then use the Authentications search option in the Merchant Administration portal.
Yes, you can bypass 3DS authentication for payers where payments are deemed low risk by the external risk provider. For more information, see Dynamic 3DS.
You can test your integration for 3DS Authentication via the gateway by using the 3DS Emulator. To access the emulator, use your test merchant profile (type "TEST" as a prefix to the Merchant ID supplied by your payment service provider).
Testing is supported for the following 3DS schemes:
To test 3DS functionality:
authentication.version
=3DS2 or 3DS1)authentication.redirectHtml
field into the page displayed to the payer to redirect the payer's browser to the 3DS Emulator challenge page. authentication.transactionId
in a subsequent Authorize or Pay transaction request. It should indicate only where authentication is successful and if the card allows for subsequent authorization or payment.Test Cards | Purpose | Card Number | 3DS1 Enrolled | 3DS2 Enrolled | Method URL | tranStatus | tranStatusReason | ECI | Authentication Token |
---|---|---|---|---|---|---|---|---|---|
Mastercard | 3DS2 - Challenge (Method URL provided) | 5123450000000008 2223000000000007 |
Yes | Yes |
Yes |
C | - | - | - |
3DS2 - Frictionless (Method URL provided) | 5123456789012346 | Yes | Yes | Yes | Y | - | 02 | mHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
3DS2 - Frictionless (No Method URL) | 5555555555000018* | Yes | Yes | No | Y | - | 02 | mHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
3DS2 - Authentication Attempted | 5500005555555559 | Yes | Yes | No | A | - | 01 | nHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
3DS2 - Authentication Rejected | 5506900140100503 | No | Yes | No | R | 04 | - | - | |
3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 | 5506900140100305 | Yes | No | No | - | - | - | - | |
3DS2 - Error during Initiate Authentication operation resulting in Generic Error Response | 5210760000000004 | Yes | Exception | - | - | - | - | - | |
3DS2 - Error during Authenticate Payer operation resulting in Generic Error Response | 5455031257390496 | Yes | Yes | No | Exception | - | - | - | |
5455031252665454 | Yes | Yes | No | Exception | - | - | - | ||
3DS1 & 3DS2 - Not Enrolled Response | 5111111111111118 | No | No | - | - | - | - | - | |
2223000000000023 | No | No | - | - | - | - | - | ||
3DS2 - Authentication Unavailable Error during Authenticate Payer operation resulting in a response of authenticationStatus = AUTHENTICATION_UNAVAILABLE | 5123459999998221 | Yes | Yes | No | Recoverable Exception | - | - | - | |
Visa | 3DS2 - Challenge (No Method URL) | 4440000009900010 | Yes | Yes | No | C | - | - | - |
3DS2 - Frictionless (No Method URL) | 4440000042200014 | Yes | Yes | Yes | Yes | - | 05 | mHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
3DS2 - Authentication Attempted | 4440000042200022 | No | Yes | No | A | - | 06 | nHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
American Express | 3DS2 - Challenge (No Method URL) | 340000099900051 | No | Yes | No | C | - | - | - |
3DS2 - Frictionless (Method URL provided) | 340353278080900 | Yes | Yes | Yes | Yes | - | 05 | mHyn+7YFi1EUAREAAAAvNUe6Hv8= | |
Discover | 3DS1 - Not enrolled for 3DS2 resulting in fallback to 3DS1 | 6011000991300009 | Yes | No | No | - | - | - | - |
3DS1 & 3DS2 - Not Enrolled Response | 6011640745800505 | - | No | - | - | - | - | - | |
Maestro | PSD2 Exemptions and Whitelisted Merchants | 5000000000000000005 | Yes | Yes | No | No | 81 | 06 | kNyn+7YFi1EUAREAAAAvNUe6Hv8= |
In the case of a "C" transStatus, the following outcomes are possible via drop-down selection in the 3DS Emulator:
Description | transStatus | challengeCancel | eci |
---|---|---|---|
Successful authentication |
Y | - | 05 / 02 |
Failed authentication |
N | - | 07 / 00 |
Cancelled authentication |
N | 01 | 07 / 00 |
Unable to authenticate | U | - | 07 / 00 |
Authentication rejected | R | - | 07 / 00 |
Copyright © 2022 Suncorp