Payer Authentication Processing

On This Page
This section shows you how to process authorizations that use these payer authentication methods:
  • Mastercard
    : Identity Check
  • Visa
    : Visa Secure

Related Information

Providing Payer Authentication Information for Authorization

The values that are returned from payer authentication must be provided when seeking authorization for the transaction. Authentication information that is not included when considering authorization may cause the transaction to be refused or downgraded and prevent the normal liability shift from occurring.
The level of security in payer authentication is denoted by the two digit Electronic Commerce Indicator (ECI) that is assigned to the transaction. These digital values have text equivalents which are assigned to the
e_commerce_indicator
 field.
The American Express, Diners, Discover, UPI, and Visa card brands use 05, 06, and 07 digit values to express the authentication level for a 3-D Secure transaction.
Text Values for ECI Values
ECI Value
Meaning
Visa
Diners
Discover
UPI
Amex
05
Authenticated
vbv
pb
dipb
up3ds
aesk
06
Attempted authentication with a cryptogram
vbv_attempted
pb_attempted
dipb_attempted
up3ds_attempted
aesk_attempted
07
Internet, not authenticated
vbv_failure/internet
internet
internet
up3ds_failure/internet
internet
Mastercard and Maestro cards use 00, 01, 02, 06, and 07 digit values to indicate the authentication level of the transaction.
Mastercard/Maestro Text Values for ECI Values
ECI Value
Meaning
Mastercard/Maestro
00
Internet, not authenticated
spa/internet
01
Attempted authentication
spa
02
Authenticated
spa
06
Exemption from authentication or network token without 3‑D Secure
spa
07
Authenticated merchant-initiated transaction
spa
The payer authentication response contains other information that needs to be passed on for successful authorization. Be sure to include these fields when requesting a separate authorization:
  • ccAuthService_directoryServerTransactionID
     (Mastercard, Maestro
    , UPI only
    )
  • ccAuthService_eciRaw
  • ccAuthService_paresStatus
  • ccAuthService_paSpecificationVersion
  • payerAuthEnrollReply_ucafAuthenticationData
     (Mastercard/Maestro only)
  • payerAuthValidateReply_ucafCollectionIndicator
    (Mastercard/Maestro only)
  • ccAuthService_cavv
  • ccAuthService_xid

Mastercard Identity Check

Mastercard Identity Check is the authentication service in the Mastercard card network that uses the 3-D Secure protocol in online transactions to authenticate customers at checkout.
Mastercard Identity Check generates a unique, 32-character transaction token, called the account authentication value (AAV) each time a Mastercard Identity Check-enabled account holder makes an online purchase. The AAV binds the account holder to a specific transaction. Mastercard Identity Check transactions use the universal cardholder authentication field (UCAF) as a standard to collect and pass AAV data.
Before implementing payer authentication for Mastercard Identity Check, contact customer support to have your account configured for this feature.

Fields Specific to the Mastercard Identity Check Use Case

These API fields are required specifically for this use case.
Set this field to the transaction ID returned by Mastercard Identity Check during the authentication process.
Set this field to the Mastercard Identity Check version returned by Mastercard Identity Check during the authentication process.
ucaf_collectionIndicator
Set to the last digit of the raw ECI value returned from authentication. For example, if ECI=02, this value should be 2.
Set this field to one of these values:
  • spa
    : Successful authentication (3-D Secure value of
    02
    ).
  • spa
    : Authentication was attempted (3-D Secure value of
    01
    ).
  • spa
     or
    internet
    : Authentication failed or was not attempted (3-D Secure value of
    00
    )

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Processing an Authorization Using Mastercard Identity Check

Use these required fields to process an authorization using Mastercard Identity Check.
When relaxed requirements for address data and the expiration date are being used, not all fields in this list are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. For details about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccAuthService_run
Set the value to
true
.
ccAuthService_cavv
ccAuthService_commerceIndicator
Set this field to one of these values:
  • spa
    : Successful authentication (3-D Secure value of
    02
    ).
  • spa
    : Authentication was attempted (3-D Secure value of
    01
    ).
  • spa
     or
    internet
    : Authentication failed or was not attempted (3-D Secure value of
    00
    ).
ccAuthService_directoryServerTransactionID
ccAuthService_paSpecificationVersion
mercahnt_id
merchant_referenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount
ucaf_collectionIndicator
Set to the last digit of the raw ECI value returned from authentication. For example, if ECI=02, this value should be 2.

Simple Order Example: Processing an Authorization Using Mastercard Identity Check

Visa Secure

Visa Secure is the authentication service in the Visa card network that uses the 3-D Secure protocol to authenticate customers at checkout. This authentication is a two-step process. First, the cardholder is authenticated by 3-D Secure. Then, the transaction is authorized based on the 3-D Secure evaluation. This section explains how to authorize a card payment based on the 3-D Secure evaluation.
Before implementing Visa Secure, contact customer support to have your account configured for this feature.

Fields Specific to the Visa Secure Use Case

These API fields are required specifically for this use case.
ccAuthService_commerceIndicator
Set the value to
vbv
 for a successful authentication (3-D Secure value of
05
),
vbv_attempted
 if authentication was attempted but did not succeed (3-D Secure value of
06
), or
vbv_failure
 if authentication failed (3-D Secure value of
07
).
ccAuthService_cavv
Required when payer authentication is successful.

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Processing an Authorization Using Visa Secure

Use these required fields to process an authorization using Visa Secure.
When relaxed requirements for address data and the expiration date are being used, not all fields in this list are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. For details about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.

Required Fields

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccAuthService_cavv
This field is required when payer authentication is successful. Otherwise, this field is optional.
ccAuthService_commerceIndicator
Set the value of this field to one of these values:
  • vbv
    : Successful authentication (EMV 3-D Secure value of
    05
    ).
  • vbv_attempted
    : Authentication was attempted (EMV 3-D Secure value of
    06
    ).
  • vbv_failure
    : or
    internet
    : Authentication failed or was not attempted (EMV 3-D Secure value of
    07
    )
ccAuthService_run
Set the value of this field to
true
.
ccAuthService_xid
merchant_referenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Validating and Authorizing an Authorization

Light Dark
Request
12345678910111213141516171819
billTo=Sao Paulo
billTo_country=BR
billTo_email=null@cybersource.com
billTo_firstname=Julia
billTo_lastname=Fernandez
billTo_postalCode=01310-000
billTo_state=SP
billTo_street1=R. Augusta
card_accountNumber=41111111XXXXXXXX
card_expirationMonth=12
card_expirationYear=2023
ccAuthService_run=true
ccAuthService_cavv=ABCDEFabcdefABCDEFabcdef0987654321234567
ccAuthService_commerceIndicator=spa
ccAuthService_paSpecificationVersion=1
merchant_id=MID23
merchant_referenceCode=Merchant_REF
ucaf_collectionIndicator=1
purchaseTotals_currency==100
Response to a Successful Request
123456789101112
merchantReferenceCode=Merchant_REF=6461515866500167772420
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=mxn
ccAuthReply_cardCategory=F
ccAuthService_reconciliationID=ZUDCXJO8KZRFXQJJ
ccAuthReply_reasonCode=100
ccAuthReply_amount=100.00
ccAuthReply_avsCode=5
ccAuthReply_authorizationCode=570110
ccAuthReply_processorResponse=1
ccAuthReply_authorizedDateTime=2022-03-01T161947Z=111222
Light Dark
Request
1234567891011121314151617
billTo=Sao Paulo
billTo_country=BR
billTo_email=julia@example.com
billTo_firstname=Julia
billTo_lastname=Fernandez
billTo_postalCode=01310-000
billTo_state=SP
billTo_street1=R. Augusta
card_accountNumber=41111111XXXXXXXX
card_expirationMonth=12
card_expirationYear=2023
ccAuthService_run=true
ccAuthService_cavv=ABCDEFabcdefABCDEFabcdef0987654321234567
ccAuthService_commerceIndicator=vbv
ccAuthService_xid=MID23
merchant_referenceCode=Merchant_REF
purchaseTotals_currency==100
Response to a Successful Request
12345678910111213
=Merchant_REF
request_id=6461515866500167772420
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=mxn
ccAuthReply_cardCategory=F
ccAuthService_reconciliationID=ZUDCXJO8KZRFXQJJ
ccAuthReply_reasonCode=100
ccAuthReply_amount=100.00
ccAuthReply_avsCode=5
ccAuthReply_authorizationCode=570110
ccAuthReply_processorResponse=1
ccAuthReply_authorizedDateTime=2022-03-01T161947Z=111222