3DS with the Payer Authentication API
This topic outlines all the steps that are required to add 3DS to your Suncorp Bank Gateway integration using the Payer Authentication API, including how to use the authentication result to process a payment.
To view examples of the API requests and responses used in the 3DS flow with the Payer Authentication API, download the Postman collection.
After you have completed your integration, see Testing your 3DS Integration to test it.
- Step 1: Initiate Authentication
- Step 2: Authenticate Payer
- Step 3: Use the Authentication Result in a Payment Operation
Prerequisites
As a prerequisite for this implementation, you should have implemented your basic Direct Payment integration.
Step 1: Initiate Authentication
The Initiate Authentication operation is used to determine the 3DS versions available to you for a given card, based on the following:
- 3DS versions configured on your merchant profile.
- Card type.
- Preferences you have indicated in the request.
- Outcome of requests the gateway has sent to the relevant authentication providers to check availability or support for the given card, and
- Gateway's 3DS transaction filtering rules configured by you or your payment service provider (PSP).
The 3DS feature of the gateway supports 3DS2 only.
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.
Initiate Authentication request
You can initiate authentication by providing the following fields in the Initiate Authentication request:
Table: Initiate Authentication request fields
| Field | Required/Optional | Description |
|---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. 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 | Currency of the order. |
transaction.id |
Required | Unique identifier for this payment authentication. |
order.id |
Required | A unique identifier for this order. |
authentication.channel |
Required | Channel in which the authentication request is being initiated. You can specify one of the following:
|
authentication.purpose |
Optional | Purpose of the authentication. 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. If you are establishing a payment agreement and not processing a payment along with it, provide ADD_CARD as the authentication purpose. For more information, see How can I submit a non-payment authentication request ? For a detailed list of use cases related to 3D Secure authentication, see Cardholder-initiated Payments with 3D Secure. |
authentication.acceptVersions |
Optional | 3DS versions that you accept for this payment. If you do not specify a version, 3DS2 is accepted. The gateway uses 3DS2, if supported by the issuer and the card. If 3DS2 is not available, the authentication does not proceed. |
order.merchantCategoryCode |
Optional | Merchant Category Code. Provide the Merchant Category Code if you want to override the default value configured on your acquirer link. |
To allow any ACS method call process to complete before you attempt the AUTHENTICATE PAYER operation, submit the INITIATE AUTHENTICATION operation at the earliest opportunity in your checkout process, and act on the response immediately. The earliest opportunity is typically when the payer completes entering their card number on the checkout page. For example, when the onBlur event of the Card Number input field is triggered, or when the payer selects a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least 10 seconds for the ACS method call to complete.
If you submit the Authenticate Payer request before the ACS Method call completes, the Authenticate Payer request proceeds but the Authenticate Payer response contains authentication.3ds2.methodCompleted = false . If the issuer's ACS has successfully completed the method call to obtain additional information about the payer's browser, the authentication.3ds2.methodCompleted field the AUTHENTICATE PAYER response is true.
Method URL
Method URL is a script that allows an issuing bank or ACS to obtain additional browser information from the cardholder or merchant for risk-based decisioning if it is supported by the card scheme.
Adding Method URL to your integration
- Merchant can provide their Method Notification URL to the gateway in the INITIATE AUTHENTICATION operation request.
- The gateway receives notifications when the method is completed. The gateway then redirects the method completion notification to the merchant's URL.
- On successful redirect, the merchant gets a notification of the 'Method Completion'. Merchant can then proceed with the next step in the Authentication, that is AUTHENTICATE PAYER.
- If the method completion callback is delayed and received after Authenticate Payer request, the gateway logs Authenticate Payer request that has already occurred for this transaction and methodCompleted remains false. In this case, the gateway does not redirect to the Merchant Notification URL and Merchant does not get a notification of the Method completion.
Validation for merchant method notification URL
- Request parameter validation: The URL parameter is validated as per standard validation mechanism within directApi for URLs.
- Sanctions Screening: The new field needs to be passed to the Sanctions Service for screening as part of the flow for Initiate Authenticationrequests from Orchestrator.
Method completion callback
While redirecting the iframe to the merchant Method Notification URL, the HTTP POST parameters include the 3DS Server Transaction ID andencrypted session data.
Session data encryption
The usage of encrypted session data in the Method Completion Callback aids in preventing malicious users from viewing the data and any tampering of data.
An AES256 key, which is generated as part of the merchant's payment session, is used to encrypt the data. This is similar to the Challenge CompletionFlow. The encrypted session data includes the following information:
- OrderId
- TransactionId
- Initiate Authentication request sent by Merchant
- Authentication Status
Initiate Authentication response
The gateway returns the following key fields in the Initiate Authentication response:
authentication.version: If 3DS authentication is available for the payer, 3DS2 is returned. Otherwise,NONEwill be 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.- 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.
- RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS: Ask the payer for alternative payment details. For example, a new card or another payment method, and resubmit the request with the new details. Do not resubmit the same request. This is applicable from API version 70 and later.
authentication.redirect.html: Insert the content of this field into the page being displayed to the payer, if authentication.3ds2.methodSupported = SUPPORTED. 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.redirect.html;
eval(document.getElementById('initiate-authentication-script').text)
If the gateway recommends you to not proceed, then inserting the content of this field into your webpage will not execute any functionality.
| URL | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 |
| HTTP Method | PUT |
| Click here to download Postman Collection - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Frictionless Flow/1. INITIATE AUTHENTICATION | |
{
"apiOperation":"INITIATE_AUTHENTICATION",
"authentication":{
"channel":"PAYER_BROWSER"
},
"order":{
"currency":"{{currency}}"
},
"sourceOfFunds":{
"provided":{
"card":{
"number":"{{fpan}}"
}
}
}
}
{
"authentication": {
"3ds2": {
"directoryServerId": "A999999999",
"methodCompleted": false,
"methodSupported": "SUPPORTED",
"protocolVersion": "2.2.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name"
},
"acceptVersions": "3DS1,3DS2",
"channel": "PAYER_BROWSER",
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"customizedHtml": {
"3ds2": {
"methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==",
"methodUrl": "<method_url>"
}
},
"html": "<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=\"<method_url>\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9kbDAzYXNwYWxsMDN2Lm1wZ3NkZXYubWFzdGVyY2FyZC5pbnQvY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS9mOGIzNjQ5ZDRiOWU3OTg4M2M0ODE4MmRjZmRkY2JjYTAxMTE3MTc0ZTkxODRiODAzM2NkMzg3NTQ4MjlhMTRlIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYTdjMTU0YS1jZTZkLTRkNjYtYTc4My02MjdmZTcyMjQ4ZTEifQ==\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"version": "3DS2"
},
"correlationId": "test",
"merchant": "TEST3DS12AUTH",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2022-06-24T06:57:32.714Z",
"currency": "USD",
"id": "TEST4",
"lastUpdatedTime": "2022-06-24T06:57:32.661Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"fundingMethod": "CREDIT",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T06:57:32.661Z",
"timeOfRecord": "2022-06-24T06:57:32.714Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Step 2: Authenticate payer
If the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), and when all payer and payment data has been gathered, submit the Authenticate Payer request when the payer clicks the Pay Now button on the checkout page.
Use the same API version for the AUTHENTICATE PAYER request as you used in the INITIATE AUTHENTICATION request.
Authenticate Payer request
Submit this operation by providing the following fields.
Authenticate Payer request fields
| Field | Required/Optional | Description |
|---|---|---|
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token |
Required | Details of the card being used for the payment. Use the same details as in the preceding INITIATE AUTHENTICATION operation. |
order.amount |
Required | The total amount of the order. |
transaction.id |
Required | Transaction ID. Use the same transaction.id as in the preceding Initiate Authentication operation. |
order.id |
Required | Order ID. The same order.id as the Initiate Authentication operation that preceded it. |
device.ipAddress |
Optional | Required if authentication.channel=PAYER_BROWSER, but with provision to exclude where necessary to comply with local legislation. Required if you support ITMX Local Switch EMVCo authentications. EMV 3DS authentications support IPv4 and IPv6 addresses from the API version 79. IPv6 is only used in the EMV 3DS authentication, and not in any subsequent Authorize, Pay or other operation. |
sourceOfFunds.provided.card.nameOnCard |
Optional | Name on the card. Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.number |
Optional | Card number. Required if you support ITMX Local Switch EMVCo authentications. |
sourceOfFunds.provided.card.expiry |
Optional | Card expiration details. Required if you support ITMX Local Switch EMVCo authentications. |
authentication.redirectResponseUrl |
Required | URL to which you want to redirect the payer after completing the payer authentication process. You do not need to provide this URL if you are certain that there will be no interaction with the payer. |
device.browser |
Optional | User-Agent header of the payer’s browser. Required if authentication.channel = PAYER_BROWSER. |
device.browserDetails object |
Optional | Browser details. Required if authentication.channel = PAYER_BROWSER. |
billing.address object object |
Optional | Billing address of the payer. It is strongly recommended that you include this in your request whenever available. |
shipping.address object |
Optional | Shipping address of the payer. It is strongly recommended that you include this in your request whenever available. |
customer object |
Optional | Payer’s details. It is strongly recommended that you include this in your request whenever available. |
Authenticate Payer response
The fields returned in the AUTHENTICATE PAYER response depend on the following:
- Frictionless or challenge flow.
- How the authentication request is initiated (authentication.channel).
- The authentication mechanism for the request, session or certificate, or password.
For a session-authenticated operation, the response is filtered to remove data that is not related to the payer and only whitelisted fields are returned. For more information, see Session basics. For fields returned for a certificate/password authenticated request, see Response Fields for a Certificate/Password-authenticated Request.
The gateway returns the following key fields in the AUTHENTICATE PAYER response:
transaction.authenticationStatus:Details about the authentication status.response.gatewayRecommendation: Recommendation on whether you should proceed to a financial transaction or not, based on the 3DS transaction filtering rules configured by you or your PSP:- DO_NOT_PROCEED: Do not proceed with this card as authentication is declined or unavailable. However, you can 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, also known as the challenge flow, or proceed to complete the payment, also known as the frictionless flow.
- DO_NOT_PROCEED_ABANDON_ORDER: Do not submit the same request again. The payment service provider, scheme or issuer require you to abandon the order. This recommendation is applicable from API version 70 and later.
- RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS: Ask the payer for alternative payment details. For example, a new card or another payment method, and resubmit the request with the new details. Do not resubmit the same request. This recommendation is applicable from API version 70 and later.
authentication.redirect.html: 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.redirect.html; eval(document.getElementById(‘authenticate-payer-script’).text)
If the gateway recommends you to not proceed, inserting the content of this field into your webpage executes no functionality.
The gateway recommends you to proceed:
- If the ACS has selected a frictionless flow for the payer, it redirects the payer’s browser back to your website, and you can proceed to step 3 to submit a subsequent payment to the gateway. The gateway obtains the authentication data related to the payment and ensures that payments are processed only if all the 3DS transaction filtering rules, configured by you or your PSP, have passed.
- If the ACS has selected a challenge flow for the payer, redirect the payer to the ACS using the
authentication.redirect.htmlfield provided in the response. After the challenge is completed, the ACS redirects the payer back to your website and triggers a callback that contains the orderId, transactionId, response.gatewayRecommendation, and result fields. Determine the outcome of the authentication based on the value returned in theresponse.gatewayRecommendationfield. The same rules apply as described above for theAUTHENTICATE PAYERresponse. If the recommendation is PROCEED, continue with step 3.
You should not rely on data returned in the browser to determine the next processing step. Ensure that either you handle the authenticate payer response in your server, or you perform a retrieve transaction operation from your server to ensure the response is successful.
Response fields for a Certificate/Password-authenticated request
The following table lists the AUTHENTICATE PAYER response fields returned for a certificate/password authenticated request, that is, submitted with a merchant ID and API password from your server rather than with a session ID from your website or the payer’s browser. For more information, see Frequently asked questions.
The fields marked with * are returned based on the used 3DS version and flow from frictionless or challenge. For example,
authentication.3ds.authenticationToken is not provided if a frictionless flow is used.Table: Response Fields for a Certificate/Password-authenticated Request
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.protocolVersion | * |
| authentication.amount | Yes |
| authentication.redirect.html | Yes |
| authentication.time | Yes |
| response.gatewayRecommendation | Yes |
| transaction.type | Yes |
| version | Yes |
| timeOfRecord | Yes |
| result | Yes |
| response.debugInformation | * |
Authenticate Payer response fields
The fields returned in the Authentication Payer response depend on:
- The flow in effect, that is, frictionless vs challenge.
- How the authentication request was initiated (authentication.channel)
- The authentication mechanism for the request, such as 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.amount | Yes |
| authentication.redirect.html | Yes |
| authentication.time | Yes |
| response.gatewayRecommendation | Yes |
| transaction.type | Yes |
| version | Yes |
| timeOfRecord | Yes |
| result | Yes |
| response.debugInformation | * |
* Where applicable, based on the 3DS version and flow, such as frictionless versus challenge, are in effect.
Authenticate Payer request example
| URL | https://{{host}}/api/rest/version/100/merchant/{{merchantId}}/order/{{orderId}}/transaction/1 |
| HTTP Method | PUT |
| Click here to download Postman Collection - the path to this operation is /Security and Fraud Prevention/3D Secure Authentication/Frictionless Flow/4. AUTHENTICATE PAYER | |
{
"sourceOfFunds": {
"provided": {
"card": {
"number": "{{fpan}}",
"expiry": {
"month": "{{expMonth}}",
"year": "{{expYear}}"
}
}
}
},
"order": {
"amount": "100",
"currency": "{{currency}}"
},
"authentication": {
"redirectResponseUrl": "https://{{host}}/api/documentation/integrationGuidelines/index.html"
},
"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"
},
"apiOperation": "AUTHENTICATE_PAYER"
}
Authenticate Payer response example - challenge flow
{
"authentication": {
"3ds": {
"transactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8"
},
"3ds2": {
"3dsServerTransactionId": "cf976f0d-cb19-454f-a5b3-3cf09ae07e38",
"acsTransactionId": "c8027c6a-94da-480d-9270-85098bc680d5",
"directoryServerId": "A999999999",
"dsTransactionId": "a4d6ce7a-52ed-46c4-b1b8-0a64ffa3fdd8",
"methodSupported": "NOT_SUPPORTED",
"protocolVersion": "2.2.0",
"requestorId": "test40Field@S^2sfds2ID",
"requestorName": "test40Field@S^2sfds2Name",
"sdk": {
"timeout": 400,
"uiType": "TEXT"
},
"transactionStatus": "C"
},
"amount": 100.00,
"method": "OUT_OF_BAND",
"payerInteraction": "REQUIRED",
"redirect": {
"customizedHtml": {
"3ds2": {
"acsUrl": "<acs_url>",
"cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9"
}
},
"domainName": "<acs_domain>",
"html": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"<acs_url>\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNmOTc2ZjBkLWNiMTktNDU0Zi1hNWIzLTNjZjA5YWUwN2UzOCJ9\" /> </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(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>"
},
"time": "2022-06-24T07:04:34.836Z",
"version": "3DS2"
},
"correlationId": "test",
"device": {
"browser": "mozilla",
"ipAddress": "127.0.0.1"
},
"merchant": "TEST3DS12AUTH",
"order": {
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2022-06-24T07:03:43.780Z",
"currency": "USD",
"id": "TEST6",
"lastUpdatedTime": "2022-06-24T07:04:34.795Z",
"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": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"number": "512345xxxxxx8212",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2022-06-24T07:04:34.795Z",
"timeOfRecord": "2022-06-24T07:03:43.780Z",
"transaction": {
"acquirer": {
"merchantId": "123456"
},
"amount": 100.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "USD",
"id": "1",
"type": "AUTHENTICATION"
},
"version": "67"
}
Step 3: Use the authentication result in a payment
When the result of the AUTHENTICATE PAYER operation indicates that you can proceed with the payment response.gatewayRecommendation=PROCEED, you can initiate an Authorize or PAY operation. In addition to the standard fields, you must provide the following fields:
order.id: Use the sameorder.idthat you supplied in theINITIATE AUTHENTICATIONandAUTHENTICATE PAYERoperations.authentication.transactionId: Use the sametransaction.idthat you supplied in theINITIATE AUTHENTICATIONandAUTHENTICATE PAYERoperations. You do not need to include any of the fields in theauthenticationobject, as the gateway uses theauthentication.transactionIdto look up the authentication results that it stored when you asked it to perform authentication. The gateway passes the required information to the acquirer.
PAY request example
| URL | https://suncorp.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<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>"
}
}
PAY response example
{
"authentication":{
"3ds":{
"acsEci":"02",
"authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
"transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
},
"3ds2":{
"dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
"protocolVersion":"2.2.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"
}
Frequently asked questions
Can I use the Payer Authentication API as a client-side API?
You can use the Payer Authentication API as a server-side API, or a client-side API on your web site or the payer’s browser.
- Client-side API: You must first establish the authentication channel where your merchant server must communicate with the gateway server for creating the session on the gateway. Once the session is created, you can use it to authenticate all the subsequent API operations needed for managing the 3DS integration flows directly from the browser using the 3DS JavaScript API or using your own library.
- Server-side API: You must perform all the operations needed for managing the 3DS integration flows directly from your merchant server to the gateway server. You can support all authentication transaction modes via the Payer Authentication API.
- In Authentication Only mode, use the
INITIATE AUTHENTICATIONandAUTHENTICATE PAYERoperations.Authentication Only: Perform Initiate Authentication and Authenticate Payer. - In Authentication and Payment Transaction mode, use the
INITIATE AUTHENTICATION,AUTHENTICATE PAYER, and AUTHORIZE/PAY operations. - In Pre-authenticated Payment Transaction mode, use the AUTHORIZE/PAY operations using the authentication details from an external provider.
- In Authentication Only mode, use the
For more information about 3-D Secure general FAQs, see FAQs.