EVO Payment API Portal

ENG

简体中文

ENG

简体中文

3D Secure ​

Overview ​

A transaction that qualifies for 3D Secure 2 can go through either a frictionless flow or a challenge flow, depending on the issuer's requirements.

A. 3D Secure 2 Frictionless Authentication Flow

In a frictionless flow, the acquirer, issuer, and card scheme exchange all necessary information in the backend through passive authentication using the user's device fingerprint. The transaction is completed without further user interaction.

B. 3D Secure 2 Challenge Authentication Flow

In a challenge flow, the issuer requires additional user interaction, either through biometrics, two-factor authentication, a one-time authentication code received on user's phone or a password.

C. EVO Payment Implementation

In EVO Payment, each merchant is configured with one of the following options on the store level:

  1. Non-Authentication:

    • Your store is not applied to authentication; all payments will NOT go through the authentication flow.
    • With this option, you CANNOT enable the tokenization feature.

  2. Require-Authentication:

    • Your store is required to perform authentication for every card payment.
    • You must submit the authentication-related fields in your initial payment request.
    • With this option and the required tokenization parameters set up, you can enable the tokenization feature.
    • After the authentication has been completed, the authentication result parameter threeDS.mpiData or securePlus.securePlusData will be returned in the response message.

  3. Optional-Authentication:

    • It is up to you to decide whether to perform the authentication before payment using the allowAuthentication field when making the payment request.
    • If you specify allowAuthentication as true, you must submit the authentication-related fields in your initial payment request.
    • With this option and the required tokenization parameters set up, you can enable the tokenization feature.
    • After the authentication has been completed, the authentication result parameter threeDS.mpiData or securePlus.securePlusData will be returned in the response message.

EVO Payment 3D Secure Support Options

EVO Payment provides the following 2 options to support both 3D Secure versions:

  1. Redirect for 3D Secure 2:

    • Implement the fastest way to support 3D Secure by redirecting the user to another site to verify the payment.
    • This mode is named threeDSPage, and it is the default setting in EVO Payment when you integrate 3D Secure processing, unless you specify authentication.type as threeDSIntegrator to choose the other option.

  2. Native for 3D Secure 2:

    • Provide a better customer experience by performing 3D Secure 2 authentication within your website or mobile app.

Redirect for 3D Secure 2 ​

EVO Payment implements 3D Secure 2 using a redirection. EVO Payment will check which version the issuer supports and provide a redirect URL where the user can complete 3D Secure 2 authentication.

This is the easiest way to support 3D Secure, as most of the backend processing steps are handled by the redirect URL provided by EVO Payment.

The diagram above describes both server-side integration and the client-side implementation that you have to build.

Step 1: Collect Additional Parameters ​

In addition to the basic parameters collected in Payment / Tokenization, you need to gather additional information from your user to perform 3D Secure authentication. You can obtain the list of additional parameters from the authenticationInfo array returned in the HTTP GET response for /g2/v1/payment/mer/{sid}/paymentMethod. See Step 2 in Chapter Payment for more details.

Step 2: Make a Payment or Tokenization ​

With the additional parameters collected, make an HTTP POST request from your server to the EVO Payment endpoint:

/g2/v1/payment/mer/{sid}/payment

for payment. Or to

/g2/v1/payment/mer/{sid}/paymentMethod

for tokenization.

Here are the additional parameters required in the request for 3D Secure authentication with threeDSPage mode:

Body ParameterRequiredDescription
authenticationMThe information used for user authentication before payment or tokenization.
transInitiatorMThe information used for user authentication before payment or tokenization.
transInitiator.browserInfo OThe user browser information for 3DS authentication, which will be sent to the authentication service provider.
userInfoOThe information used for user authentication before payment or tokenization.
returnURLMThe URL to redirect your customer back to after they complete the authentication.
authenticationOnlyOIn POST /g2/v1/payment/mer/{sid}/payment request, indicates whether it is an authentication-only payment request. See Chapter Authentication Only for more details.
allowAuthenticationOApplied when your store is configured as Optional-Authentication. In POST /g2/v1/payment/mer/{sid}/payment or POST /g2/v1/payment/mer/{sid}/paymentMethod request to indicate whether the payment needs to conduct authentication. Note that this field does not apply when authenticationOnly is true.

More details about the authentication object:

  1. authentication.type: The authentication mode applied for this payment, optional. You can specify it as threeDSPage, which is also the default value, to inform EVO Payment that you want to use the redirection solution for 3D Secure 2.
  2. authentication.threeDS.merchantRiskIndicator: The object containing the additional risk fields for 3D Secure 2, optional. See EVO Payment API Specification for more details.

More details about the transInitiator object:

  1. transInitiator.userCreateIP: The IP address of the device that initiates the payment, optional.
  2. transInitiator.browserInfo.acceptHeader: The accept header value of the user's browser, required.
  3. transInitiator.browserInfo.colorDepth: The color depth of the user's browser in bits per pixel, required. Use the browser's screen.colorDepth property to obtain the value. Accepted values: 1, 4, 8, 15, 16, 24, 32, or 48 bits.
  4. transInitiator.browserInfo.javaEnabled: A Boolean value indicating whether the user's browser is able to execute Java, required.
  5. transInitiator.browserInfo.language: The browser language defined in IETF BCP47, required. Use the browser's navigator.language property to obtain the value. For example, NL, FR, US.
  6. transInitiator.browserInfo.screenHeight: The total height of the user's screen in pixels, required. Use the browser's screen.height property to obtain the value.
  7. transInitiator.browserInfo.screenWidth: The total width of the user's screen in pixels, required. Use the browser's screen.width property to obtain the value.
  8. transInitiator.browserInfo.timeZoneOffset: The time difference in minutes between the UTC time and the local time of the user's browser, required. Use the browser's getTimezoneOffset() method to obtain the value.
  9. transInitiator.browserInfo.userAgent: The user agent value of the user's browser, required.

More details about the userInfo object:

  1. userInfo.billingAddress: The object containing the user's billing address, optional. See EVO Payment API Specification for more details.

  2. userInfo.deliveryAddress: The object containing the address to deliver the goods, optional. See EVO Payment API Specification for more details.

  3. userInfo.accountInfo: The object containing the user account information for 3D Secure 2, optional. See EVO Payment API Specification for more details.

  4. userInfo.email: The user's email address, optional.

Here is an example of making a 10 USD payment with credit card requiring 3D Secure authentication:

js
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment \  
2.-H "Content-Type: application/json" \  
3.-H "DateTime: 2021-12-31T08:30:59+0800" \  
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
5.-H "SignType: SHA256" \  
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
7.-d '{  
8.    "merchantTransInfo": {  
9.        "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",  
10.        "merchantTransTime": "2021-12-31T08:30:59+08:00"  
11.    },  
12.    "transAmount": {  
13.        "currency": "USD",  
14.        "value": "10.00"  
15.    },  
16.    "allowAuthentication": true,  
17.    "returnURL": "https://YOUR_COMPANY.com/RETURNURL",  
18.    "paymentMethod": {  
19.        "type": "card",  
20.        "card": {  
21.            "cardInfo": {  
22.                "cardNumber": "4761340000000019",  
23.                "expiryDate": "2212",  
24.                "cvc": "946"  
25.            }  
26.        }  
27.    },  
28.    "transInitiator": {  
29.        "browserInfo": {  
30.            "acceptHeader": "application/json, text/plain, */*",  
31.            "colorDepth": "1",  
32.            "javaEnabled": true,  
33.            "language": "US",  
34.            "screenHeight": "300",  
35.            "screenWidth": "200",  
36.            "timeZoneOffset": "480",  
37.            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36"  
38.        }  
39.    },  
40.    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",  
41.    "metadata": "This is a metadata"  
42.}'

If you don't receive an action object in the response, use the result.code and payment.status / paymentMethod.token.status to present the payment / tokenization result to your user.

Otherwise, additional steps are required to complete the payment / tokenization, you need to send the action object to your web frontend or client APP, then proceed to the next step.

Here is an example of the response of the payment that requires a redirection:

js
1.{  
2.    "result": {  
3.        "code": "S0000",  
4.        "message": "Success"  
5.    },  
6.    "action": {  
7.        "type": "threeDSRedirect",  
8.        "threeDSData": {  
9.            "url": "https://YOUR_REDIRECT_URL",  
10.            "method": "GET"  
11.        }  
12.    },  
13.    "paymentMethod": {  
14.        "card": {  
15.            "first6No": "476134",  
16.            "last4No": "0019",  
17.            "paymentBrand": "Visa",  
18.            "fundingType": "credit"  
19.        }  
20.    },  
21.    "payment": {  
22.        "status": "Verifying",  
23.        "merchantTransInfo": {  
24.            "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",  
25.            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
26.        },  
27.        "evoTransInfo": {  
28.            "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",  
29.            "evoTransTime": "2021-12-31T00:30:59Z"  
30.        },  
31.        "pspTransInfo": {  
32.            "pspTransTime": "2021-12-31T08:30:59+08:00",  
33.            "authorizationCode": "091410"  
34.        },  
35.        "transAmount": {  
36.            "currency": "USD",  
37.            "value": "10.00"  
38.        }  
39.    },  
40.    "pspData": {  
41.        "name": "Visa"  
42.    },  
43.    "metadata": "This is a metadata"  
}

Step 3: Process threeDSRedirect ​

For the redirection solution for 3D Secure 2 (authentication.type is threeDSPage), usually the action.type you received in the response is threeDSRedirect, meaning that you need to redirect the user to an EVO Payment hosted page to complete the 3DS 2 authentication with action.threeDSData in the same response.

A. Redirect User to EVO Payment Hosted Page

Redirect the user to action.threeDSData.url using the HTTP method specified in action.threeDSData.method.

Here is an example of performing the threeDSRedirect action on your frontend when action.threeDSData.method is GET:

TIP

Please note that the user is then redirected to an EVO Payment hosted page, and then EVO Payment will process the following 3D Secure authentication procedures with the user and issuer ACS.

B. Redirect Back After User Completes the Authentication

The user will be redirected back by EVO Payment to your returnURL with an HTTP GET request within 10 minutes. You can use the merchantTransID parameter in the response to match your initial request.

  • If the status parameter in the response is finished, the 3D Secure authentication is successful. You will need to obtain the transaction details by requesting the GET interface or receiving a notification from EVO Payment.

  • If you do not receive any response within 10 minutes, or if the status parameter is not finished, the 3D Secure authentication has failed. In this case, you should obtain the transaction details by requesting the GET interface or receiving a notification from EVO Payment.

Step 4: Present the result ​

After the user completes the payment or tokenization, and no further actions are required on the frontend or client app, you can receive a notification or initiate a GET request to obtain details. Use the result.code and payment.status / paymentMethod.status to inform your user of the payment or tokenization status.

Result CodeDescription
S0000Success

For other possible result.code values and recommended messages that you can present to your user, see the Appendix in the EVO Payment API Specification.

StatusDescription
AuthorisedUsed for card transactions; means the transaction authorization is successfully completed and pending for capture (the merchant can submit a cancel).
CapturedFor card transactions, means transaction authorization and capture are successfully completed; for e-wallet transactions, means the transaction is successfully completed.
FailedPayment failed
StatusDescription
SuccessMeans the token is created
FailedMeans token creation failed

For other possible payment.status / paymentMethod.status values and descriptions, see payment.status / paymentMethod.status in the EVO Payment API Specification.

Error handling ​

  • For HTTP POST request to EVO Payment: It is suggested to wait at least 45 seconds after the request is sent to EVO Payment. If you don’t get the response within the time frame, you need to retrieve the result from EVO Payment. See Step 6 in chapter Payment / Tokenization to initiate the request.
  • For HTTP PUT request to EVO Payment: The HTTP PUT request is idempotent, meaning that if you don’t get the response from EVO Payment within a certain time frame, for example 45 seconds, you can resend the request with exactly the same request message. If you still fail to get the response after several times of the request, you can initiate another payment / tokenization request instead.

Native for 3D Secure 2 ​

EVO Payment can implement 3D Secure 2 in a native way to provide a better customer experience.

Step 1: Collect Additional Parameters ​

This step is similar to Step 1 in Redirect for 3D Secure 2. See it for more details.

Step 2: Make a Payment or Tokenization ​

This step is similar to Step 2 in Redirect for 3D Secure 2. See it for more details. The only differences are:

  1. You need to specify authentication.type in your POST request as threeDSIntegrator instead of threeDSPage.
  2. You need to specify transInitiator.browserInfo in your POST request.
  3. It is suggested to specify your merchantTransInfo.merchantTransID in your returnURL, so that you can easily process the response in the following steps. For example: R_COMPANY.com/RETURNURL/YOUR_MERCHANT_TRANS_ID.
  4. Except for the action.type with threeDSRedirect, you may also receive threeDSIdentify or threeDSChallenge in the response from EVO Payment.

Step 3-1: Process threeDSIdentify ​

If your server receives an action.type with threeDSIdentify, you are required to perform the 3D Secure 2 device fingerprinting.

A. Create an iframe and initiate the device fingerprint request to the issuer

Render a hidden HTML iframe in the browser and perform an HTTP request in the iframe to the action.threeDSData.url using the HTTP method specified in action.threeDSData.method.

If action.threeDSData.method is GET:

js
curl {action.threeDSData.url}

If action.threeDSData.method is POST and action.threeDSData.parameter exists, the action.threeDSData.parameter needs to contain a threeDSMethodData in base64 encoded format:

js
1.{  
2.    "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9ZT1VSX0NPTVBBTlkuY29tL1JFVFVSTlVSTCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiN2MzOWJkOTYtOThlZS00N2IwLTgzYWYtNjMwNjE2NmE3MDE4In0="  
3.}

In this case, you need to perform the threeDSIdentify action on your frontend with a form POST:

js
1.<form method="POST" action="{action.threeDSData.url}" id="threeDSIdentify" target="NAME_OF_YOUR_IFRAME">  
2.  <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9ZT1VSX0NPTVBBTlkuY29tL1JFVFVSTlVSTCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiN2MzOWJkOTYtOThlZS00N2IwLTgzYWYtNjMwNjE2NmE3MDE4In0=" />  
3.</form>

Please keep the letters case of the key(s) in your POST request consistent with the parameter(s) name in action.threeDSData.parameter returned from the EVO Payment response.

Tips:

  • If you don't specify merchantTransID in your returnURL in the previous POST request, you need to decode the base64-encoded threeDSMethodData.
  • Get and store the threeDSServerTransID with the decoded data to process the response in the next step.

B. Wait for the Device Fingerprint Result to Your Return URL

Wait for the issuer's response posted in your returnURL for 10 seconds from initiating the request. Use the merchantTransID in the returnURL to match your initial request:

  • Mark threeDSCompInd as Y.
  • Save the threeDSMethodData parameter from the response and proceed to the next step.

If you don't specify the merchantTransID in your returnURL, you need to:

  1. Decode the threeDSMethodData parameter in the response using the base64 method.
  2. Get the threeDSServerTransID to match your initial request.

If you don’t receive any response in 10 seconds, or fail to get the threeDSMethodData parameter from the response, you can mark threeDSCompInd as N and proceed to the next step.

C. Send the Device Fingerprint Result

From your server, you can make an HTTP PUT request to the EVO Payment endpoint:

  • For payment: /g2/v1/payment/mer/{sid}/payment
  • For tokenization: /g2/v1/payment/mer/{sid}/paymentMethod

Specify the parameters below.

Query ParameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the initial payment/tokenization request.
Body ParameterRequiredDescription
authentication.threeDS.redirectData.threeDSCompIndMThe fingerprinting result.

Here is an example:

js
1.curl -X PUT https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_REQUEST} \  
2.-H "Content-Type: application/json" \  
3.-H "DateTime: 2021-12-31T08:30:59+0800" \  
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
5.-H "SignType: SHA256" \  
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
7.-d '{  
8.    "authentication": {    
9.        "threeDS": {  
10.            "redirectData": {  
11.                "threeDSCompInd": "Y"  
12.            }  
13.        }  
14.    },  
15.    "metadata": "This is a metadata"  
16.}'

If the response doesn’t contain an action object, you can use the result.code and payment.status / paymentMethod.token.status to present the payment/tokenization result to your user.

Otherwise, if the response includes an action object, additional steps are required to complete the payment/tokenization. You need to send the action object to your web frontend or client app, then proceed to the next step.

Here is an example of the response requiring challenge authentication for the user:

js
1.{  
2.    "result": {  
3.        "code": "S0000",  
4.        "message": "Success"  
5.    },  
6.    "action": {  
7.        "type": "threeDSChallenge",  
8.        "threeDSData": {  
9.            "url": "https://YOUR_REDIRECT_URL",  
10.            "method": "GET",  
11.            "parameter": {  
12.                "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI3YzM5YmQ5Ni05OGVlLTQ3YjAtODNhZi02MzA2MTY2YTcwMTgiLCJhY3nUcmFuc0lEIjoiMTE4ZDNiNjEtYjU5Ny00Nzg2LTg1ZWMtNzA0Mzc3ZDhjMWU4IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0="  
13.            }  
14.        }  
15.    },  
16.    "paymentMethod": {  
17.        "card": {  
18.            "first6No": "476134",  
19.            "last4No": "0019",  
20.            "paymentBrand": "Visa",  
21.            "fundingType": "credit"  
22.        }  
23.    },  
24.    "authentication": {  
25.        "type": "threeDSIntegrator"  
26.    },  
27.    "payment": {  
28.        "status": "Verifying",  
29.        "merchantTransInfo": {  
30.            "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",  
31.            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
32.        },  
33.        "evoTransInfo": {  
34.            "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",  
35.            "evoTransTime": "2021-12-31T00:30:59Z"  
36.        },  
37.        "pspTransInfo": {  
38.            "pspTransTime": "2021-12-31T08:30:59+08:00",  
39.            "authorizationCode": "091410"  
40.        },  
41.        "transAmount": {  
42.            "currency": "USD",  
43.            "value": "10.00"  
44.        }  
45.    },  
46.    "pspData": {  
47.        "name": "Visa"  
48.    },  
49.    "metadata": "This is a metadata"  
50.}

Step 3-2: Process threeDSChallenge ​

If your server receives an action.type with threeDSChallenge, it means that the issuer wants to perform an additional check to verify that the user is indeed the cardholder.

A. Create an Iframe and Initiate to Send cReq (ChallengeRequest) to the Issuer

Render an HTML iframe in the browser and perform an HTTP request in the iframe to the action.threeDSData.url using the HTTP method specified in action.threeDSData.method.

If action.threeDSData.method is POST and action.threeDSData.parameter exists, specify the sub field(s) within the parameter object as the form data of the POST request. This will initiate the challenge window in the iframe.

Example of Performing threeDSChallenge Action on Your Frontend (GET Method)

bash
curl {action.threeDSData.url}

If action.threeDSData.method is POST and action.threeDSData.parameter exists, the action.threeDSData.parameter needs to contain a creq in base64-encoded format:

js
{
    "creq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI3YzM5YmQ5Ni05OGVlLTQ3YjAtODNhZi02MzA2MTY2YTcwMTgiLCJhY3nUcmFuc0lEIjoiMTE4ZDNiNjEtYjU5Ny00Nzg2LTg1ZWMtNzA0Mzc3ZDhjMWU4IiwiY2hhbGVuZ2V3aW5kb3dTaXplIjoiMDIifQ=="
}

In this case, you need to perform the threeDSData action on your frontend with a form POST:

js
1.<form method="POST" action="{action.threeDSData.url}" id="threeDSChallenge" target="NAME_OF_YOUR_IFRAME">  
2.  <input name="creq" value="eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI3YzM5YmQ5Ni05OGVlLTQ3YjAtODNhZi02MzA2MTY2YTcwMTgiLCJhY3nUcmFuc0lEIjoiMTE4ZDNiNjEtYjU5Ny00Nzg2LTg1ZWMtNzA0Mzc3ZDhjMWU4IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0=" />  
</form>

Please keep the letters case of the key(s) in your POST request consistent with the parameter(s) name in action.threeDSData.parameter returned from EVO Payment response.

TIP

If you don't specify merchantTransID in your returnURL in the previous POST request, you need to decode the base64-encoded creq, get and store the threeDSServerTransID from the decoded data to process the response in the next step.

B. Wait for the Cres (ChallengeResponse) to Your Return URL

Wait for the issuer's response, which will be posted to your returnURL for 10 minutes from sending the request. Use the merchantTransID in the returnURL to match your initial request:

  • Mark threeDSFinished as Y.
  • Save the cres parameter from the response, and then proceed to the next step.

Tips:

  • If you don't specify the merchantTransID in your returnURL, you need to decode the cres parameter in the response using the base64 method, and get the threeDSServerTransID to match your initial request.
  • If you don’t get any response in 10 minutes or fail to get the cres parameter from the response, you can mark threeDSFinished as N and proceed to the next step.

C. Send the Challenge Result

From your server, you can make an HTTP PUT request to the EVO Payment endpoint:

  • For payment: /g2/v1/payment/mer/{sid}/payment
  • For tokenization: /g2/v1/payment/mer/{sid}/paymentMethod

Specify the parameters below.

Query ParameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the initial payment/tokenization request.
Body ParameterRequiredDescription
authentication.threeDS.redirectData.threeDSFinishedMThe challenge result.
authentication.threeDS.redirectData.cresOThe challenge response returned from the issuing bank in the response to your returnURL, in base64-encoded format. Please do NOT decode it; just forward to EVO Payment without any change.

Here is an example:

js
1.curl -X PUT https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_REQUEST} \  
2.-H "Content-Type: application/json" \  
3.-H "DateTime: 2021-12-31T08:30:59+0800" \  
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
5.-H "SignType: SHA256" \  
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
7.-d '{  
8.    "authentication": {    
9.        "threeDS": {  
10.            "redirectData": {  
11.                   "cres":"eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI3YzM5YmQ5Ni05OGVlLTQ3YjAtODNhZi02MzA2MTY2YTcwMTgiLCJhY3nUcmFuc0lEIjoiMTE4ZDNiNjEtYjU5Ny00Nzg2LTg1ZWMtNzA0Mzc3ZDhjMWU4IiwiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6IlkiLCJ0cmFuc1N0YXR1cyI6IlkifQ==",  
12.                "threeDSFinished": "Y"  
13.            }  
14.        }  
15.    },  
16.    "metadata": "This is a metadata"  
17.}'

INFO

If the payment or tokenization is successful, you'll receive a result.code of S0000 which indicates successful.

js
1.{  
2.    "result": {  
3.        "code": "S0000",  
4.        "message": "Success",  
5.        "pspResponseCode": "00",  
6.        "pspMessage": " Approval and completed successfully; Accepted and processed"  
7.    },  
8.    "paymentMethod": {  
9.        "card": {  
10.            "first6No": "476134",  
11.            "last4No": "0019",  
12.            "paymentBrand": "Visa",  
13.            "fundingType": "credit"  
14.        }  
15.    },  
16.    "authentication": {  
17.        "type": "threeDSIntegrator",  
18.        "threeDS": {  
19.            "mpiData": {  
20.                "status": "Y",  
21.                "eci": "05"  
22.            }  
23.        }  
24.    },  
25.    "payment": {  
26.        "status": "Authorised",  
27.        "merchantTransInfo": {  
28.            "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",  
29.            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
30.        },  
31.        "evoTransInfo": {  
32.            "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",  
33.            "evoTransTime": "2021-12-31T00:30:59Z"  
34.        },  
35.        "pspTransInfo": {  
36.            "pspTransTime": "2021-12-31T08:30:59+08:00",  
37.            "authorizationCode": "091410"  
38.        },  
39.        "transAmount": {  
40.            "currency": "USD",  
41.            "value": "10.00"  
42.        }  
43.    },  
44.    "pspData": {  
45.        "name": "Visa"  
46.    },  
47.    "metadata": "This is a metadata"  
48.}

Step 4: Present the result ​

After the user completes the payment or tokenization and no further actions are required on the frontend or client app, you can use the result.code and payment.status / paymentMethod.status to inform your user of the payment or tokenization status.

Result CodeDescription
S0000Success
V0007Missing field {} when
B0025Authentication not finished
B00263DS version not supported

For other possible result.code values and recommended messages to present to users, see the Appendix in the EVO Payment API Specification.

If the result.code is S0000, you need to check the payment.status / paymentMethod.status to determine and inform your user of the payment or tokenization status.

StatusDescription
AuthorisedUsed for card transactions; means the transaction authorization is successfully completed and pending for capture (merchant can submit cancel).
CapturedIf card transaction, means transaction authorization and capture are successfully completed; if e-wallet transaction, means the transaction is successfully completed.
FailedPayment failed.
StatusDescription
SuccessMeans the token is created.
FailedMeans token creation has failed.

For other possible payment.status / paymentMethod.status values and descriptions, see the payment.status / paymentMethod.status section in the EVO Payment API Specification.

Error handling ​

For HTTP POST request to EVO Payment: It is suggested to wait at least 45 seconds after the request is sent to EVO Payment. If you don’t get the response within the time frame, you need to retrieve the result from EVO Payment. See Step 6 in chapter Payment / Tokenization to initiate the request. For HTTP PUT request to EVO Payment: The HTTP PUT request is idempotent, meaning that if you don’t get the response from EVO Payment within a certain time frame, for example 45 seconds, you can resend the request with exactly the same request message. If you still fail to get the response after several times of the request, you can trigger another payment / tokenization request instead.