Check 3DS Enrollment

If you want to authenticate card identity with 3D-secure before performing charge, you can user this API (you can pass created tokenId or card information directly)

EndPoint

POST /credit-card/enrollment

Header Params

Param	Required	Type	Description	Note
X-APPOTAPAY-AUTH	required	String	How to generate JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	UUIDv4 format. Request ID to check when a problem occurs	max:42
Language	optional	String	The value vi or en corresponding to the payment link will be Vietnamese or English, (default: vi)	in:vi,en
X-Account-Ref-ID	optional	String	Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request Params

Parameters	Requirement	Data type	Description	Note
card	required	Object	Card information
card.number	required	String	Card number	16 numbers
card.holderName	required	String	Card holder	Min: 1 Max: 50 Including: 0- 9, a-z, A-Z, Space
card.expirationMonth	required	String	Card expiration month, including leading 0 (E.g.: 03 for March)	Format: MM
card.expirationYear	required	String	Card expiration year (E.g.: 25)	Format: YY
card.cvv	required	String	Card verification number, also known as CVV The card's secret code includes 3 or 4 numbers
tokenId	required_if	String	Required if card isn't provided Token ID for payment instead of card information
amount	required	Float	Amount of the payment processed on the card, being submitted for authentication (E.g.: 1000)	Support VND
merchantRefId	required	String	Reference ID you can use to identify the transaction	Min: 1 Max: 40
returnUrl	required	String	Should be a valid URL that end-customers will be redirected to after 3DS is performed	It is a valid URL
currency	required	String	Payment currency. Should be a 3-letter code following the ISO-4217 standard	Support: VND
customer	optional	Object	Customer Information
customer.browser	optional	Object	Customer's browser information.
customer.browser.clientIp	optional	String	IP address of the customer device	IPv4 Min: 7 Max: 45
customer.browser.userAgent	optional	String	User Agent of customer. Information is collected from header sent from the client's device Used for risk management E.g: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/92.0.4512.0 Safari/537.36	Max: 500
customer.browser.referrer	optional	String	The previous address is redirected to the merchant page Used for risk management E.g: AppotaPay - The leading online payment company in Vietnam	Min: 1 Max: 500
customer.browser.acceptLanguage	optional	String	Customer device language E.g: vi-VN, en-US Used for risk management	Min: 2 Max: 10
billing	optional	Object	Billing details of the cardholder. If entered, should correspond with billing details registered by the cardholder with their issuer.
billing.firstName	optional	String	First name of cardholder Useful with frictionless 3DS 2.0	Min: 1 Max: 50
billing.lastName	optional	String	Last name of cardholder Useful with frictionless 3DS 2.0	Min: 1 Max: 50
billing.email	optional	String	Cardholder’s email address on record with issuer Useful with frictionless 3DS 2.0	Min: 1 Max: 255
billing.phoneNumber	optional	String	Cardholder’s mobile phone number on record with issuer Useful with frictionless 3DS 2.0	Min: 8 Max: 20
billing.province	optional	String	Use this to enter province, state or region of residence. If the user is USA citizen, make sure to use state code (e.g put CA instead of California) Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.city	optional	String	City, village or town as appropriate Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.country	optional	String	2-letter ISO 3166-2 country code for the customer's country of residence Useful with frictionless 3DS 2.0	Min: 2 Max: 2
billing.addressLine1	optional	String	Building name and apartment unit number Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.addressLine2	optional	String	Building name and apartment unit number Useful with frictionless 3DS 2.0	Min: 1 Max: 100
billing.postalCode	optional	String	Postal, zip or rural delivery code, if applicable Useful with frictionless 3DS 2.0	Min: 1 Max: 10

Example Request

{
  "merchantRefId": "7Xthy1kbi",
  "amount": 1000000,
  "currency": "VND",
  "returnUrl": "https://devtool.vn",
  "tokenId": "01hjag3z1dfmznj52hhk33njy8",
  "customer": {
    "browser": {
      "clientIp": "127.0.0.1",
      "userAgent": "127.0.0.1",
      "referrer": "127.0.0.1",
      "acceptLanguage": "en-US"
    }
  },
  "billing": {
    "firstName": "Sheryl",
    "lastName": "Nhung",
    "email": "nhunghoang@email.com",
    "phoneNumber": "02345686432",
    "alternatePhoneNumber": "02345686432",
    "province": "VP",
    "city": "VT",
    "country": "VN",
    "addressLine1": "81 Lang Ha",
    "addressLine2": "17 Mai Anh Tuan",
    "postalCode": "10000"
  }
}

When a user is redirected to the 3DS Authentication page to perform 3DS during the verification process, AppotaPay will collect device data directly from the user’s browser. Merchants are not required to collect this data from users and send this to AppotaPay.

This device data will be used by our fraud detection service to further secure transactions. The data collected is as follows:

• IP Address of end customer
• Browser configuration (user-agent, language, screen size, time zone)
• Referrer

Response Params

{
  "id": "01HQHR9W32E2RDSF6KM51PSJ92",
  "merchantRefId": "HJ1OsUcDI",
  "tokenId": "01hqhr8vgdw64qhqgvm2tsbpew",
  "status": "PENDING",
  "amount": 1000000,
  "currency": "VND",
  "deviceDataCollectionUrl": "https://acpg.dev.appotapay.com/credit-card/authenticate?id=01HQHR9W32E2RDSF6KM51PSJ92&signature=cf6e30824b5e66e0c401701f3416e72c5b069a01c3a80a316cf9e54f9b855675",
  "card": {
    "number": "400000XXXXXX0010",
    "expirationMonth": "12",
    "expirationYear": "29",
    "cardBrand": "MASTERCARD",
    "cardType": "CREDIT",
    "country": "VN"
  }
}

Success

Http Status Code 200 - OK

Parameters	Data type	Description	Note
id	String	Unique authentication ID returned by AppotaPay to identify the 3DS transaction. Merchant can use the id in Charge API, corresponding to authenticationId field if requesting charge with authentication.
merchantRefId	String	Your reference ID for identifying the transaction, sent in the request	Min:1 Max:40
tokenId	String	Required if card isn't provided ID of a token created via the AppotaPay Tokenization API	Min:1 Max:32
amount	String	Amount of the payment processed on the card, being submitted for authentication
currency	String	Payment currency. Should be a 3-letter code following the ISO-4217 standard	Support: VND
card	String	Data of the card being charged
card.number	String	Card number	16 numbers
card.expirationMonth	String	Card expiration month, including leading 0 (E.g.: 03 for March)	Format: MM
card.expirationYear	String	Card expiration year (E.g.: 27)	Format: YY
status	String	Authentication status classified as: CARD_ENROLLED Card is 3DS enrolled and pending verification by user ENROLLMENT_CHECK_FAILED Failed to check enrollment status. Likely due to an issue with the issuer or card network. CARD_NOT_ENROLLED Card is not 3DS enrolled VERIFIED 3DS verification succeeded. When authentication is successful, the eci value will be one of the following values: 05, 02, 06, 01. Proceed with authorization. FAILED 3DS verification failed PENDING Only returned for 3DS 2.0 transactions or where the processor used is MIGS. Redirect the user to the 3DS page to continue the process.
deviceDataCollectionUrl	String	If the status is CARD_ENROLLED or PENDING, cardholder needs to be redirected to this URL to proceed with 3DS verification
eci	String	Electronic Commerce Indicator (ECI) status code for card's enrollment. Only returned when authentication is completed or failed. 05 or 02 - Successful authentication. Proceed with authorization. 06 or 01 - Card not enrolled or authentication skipped due to frictionless flow. Proceed with authorization. 07 or 00 - Failed authentication.

Error

HTTP Status Code != 200

Note

• CARD_ENROLLED | PENDING → Transaction should be verified before charge. Render a 3DS window for the cardholder to verify.
• CARD_NOT_ENROLLED → Clear to proceed to charge (verification not required)
• ENROLLMENT_CHECK_FAILED → Clear to proceed to charge (verification not possible at this time)

3DS Verification Window

• If the card is enrolled in 3DS, redirect the cardholder to deviceDataCollectionUrl to perform 3DS or render the 3DS page in an iframe.

After 3DS Verification

• After the cardholder completes the 3DS, the cardholder will be redirected to the return_url that was sent in the initial enrollment request. The authentication_id and status will be appended in the URL query through POST method.
• The full authentication response is not sent to the return_url. The URL queries in the redirect request cannot fully be trusted as a malicious user might perform the redirect call manually to trick the merchant’s system into thinking that the authentication was successful.
• To see the full authentication response, the merchant needs a separate backend call to retrieve the authentication object.

Redirect users back to the merchant’s page

Parameters	Data type	Description
authenticationId	String	When redirecting user to merchant's page, authentication is appended in the URL query Merchant can perform a GET request to check the full request object before performing a charge If authenticating successfully, you can pass the field value to authenticationId of Charge API to create request.
status	String	Final authentication status - VERIFIED (3DS verification is successful) - FAILED (3DS verification has failed)