Guides
Sub-processorsAbout PismoContact us

Client webhooks for VCAS

Visa Consumer Authentication Service (VCAS) is a Visa-provided service to support 3-D Secure (3DS), a global protocol designed to help issuers authenticate cardholders during card-not-present transactions, such as e-commerce purchases. Issuers need to implement the following webhooks to support VCAS.

Summary diagram of the workflow for VCAS

1—Use case #1—VCAS generates, delivers, and validates the OTP.

2—Use case #2—Issuer generates, delivers, and validates the OTP.

3—Use case #3—VCAS generates, issuer delivers, and VCAS validates the OTP.

*For more information on VCAS and the three use cases noted, refer to the Visa Consumer Authentication Service (VCAS) guide.

VCAS StepUp

Webhook request to issuer to provide authentication method and display text.

If the risk assessment results in a status of StepUp, this will determine how the issuer can challenge the cardholder.

Webhook specifications
Request fields
Field Type Description Req
id string Pismo-generated unique authorization ID Y
provider enum
string		 Third-party provider name:
* VCAS		 Y
type enum
string		 Call type:
* STEPUP
card object Card information object Y
id integer Card ID Y
mode_id integer Card mode ID Y
type enum
string		 Card type:
* PLASTIC
* VIRTUAL
* RECURRING
* TEMPORARY		 Y
hash string Encrypted PAN using 2048 rsa key and base64 encoded. Pismo provides the encrypt/decrypt keys for this field. Y
bin string Card Bank Identification Number (BIN). A 6 or 8 digit value Y
last_four_digits string Card last 4 PAN digits Y
account object Account information object Y
id string Pismo account ID Y
document_number string Cardholder document number. A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Y
email string E-mail. Y
phones object
array		 Phone objects Y
area_code string Phone area code Y
country_code string Phone number country code Y
number string Phone number without area code Y
type enum
string		 Phone type:
* mobile
* commercial
* residential		 Y
program object Program information object Y
id integer Program ID Y
customer object Customer information object Y
id integer Customer ID Y
raw_provider object All non-PCI information received from provider. Check provider documentation for details. Y
Sample request 
{
  "id": "ff77635e-1cd6-4fda-992d-5ceb71d75644",
  "provider": "VCAS",
  "type": "stepup",
  "card": {
    "id": 869572,
    "mode_id": 102,
    "type": "PLASTIC",
    "hash": "WEPvOQuZvjfYEd0iBmr43bhWyOsylIsW95ebYrLD89App2iEq9IizP+8w73pxKQ4mI47EdhzYHF9RfXjrBOyug==",
    "bin": "885692",
    "last_four_digits": "0153"
  },
  "account": {
    "id": 10045896,
    "document_number": "00011122233",
    "phones": [
      {
        "area_code": "31",
        "country_code": "55",
        "number": "998675309",
        "type": "mobile"
      }
    ],
    "email": "[email protected]"
  },
  "program": {
    "id": 986
  },
  "customer": {
    "id": 867604
  },
  "raw_provider": {
    "ProcessorId": "5723ae630063ac1a9c3ab079",
    "IssuerId": "5723ae630063ac1a9c3ab083",
    "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "DSTransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f987",
    "ThreeDSRequestorAuthenticationInd": "01",
    "StepupRequestId": "878f4751-4140-4881-9e4a-003e83524f22",
    "DeviceLocale": "en-US",
    "DeviceUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
    "MessageVersion": "2.2.0",
    "RDXMessageVersion": "2.2.3",
    "MessageCategory": "01",
    "MerchantInfo": {
      "AcquirerId": "1337",
      "AcquirerCountryCode": "840",
      "MerchantId": "876543210",
      "MerchantName": "Ranier Expeditions",
      "MerchantURL": "https://www.requestor.com",
      "MerchantCategoryCode": "0123",
      "MerchantCountryCode": "840",
      "MerchantAppRedirectURL": "merchantScheme://appName?transID=b2385523-a66c-4907-ac3c-91848e8c0067"
    },
    "TransactionInfo": {
      "TransactionCurrency": "840",
      "Channel": "WEB"
    }
  }
}
Response fields
Field Type Description Req
raw_response object Raw response to VCAS StepUp request, according with VCAS documentation Y
Sample response 
{
    "raw_response": {
        "ProcessorId": "5723ae630063ac1a9c3ab07976",
        "IssuerId": "5723ae630063ac1a9c3ab080",
        "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
        "StepupRequestId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
        "StepupType": "OTPEMAIL",
        "Language": "en-US",
        "Status": "SUCCESS",
        "RiskIndicator": "string",
        "Credentials": [
            {
                "Id": "d94fd3fd-bef1-49cb-88ab-a6841261cea9",
                "Type": "OTPEMAIL",
                "Text": "[email protected]"
            }
        ],
        "Reason": {
            "ReasonCode": "string",
            "ReasonDescription": "string"
        },
        "Error": {
            "ReferenceNumber": "string",
            "ReasonDescription": "string",
            "Description": "string",
            "Message": "string"
        },
        "WhyInfo": {
            "Label": "string",
            "Text": "string"
        }
    }
}

VCAS Initiate Action

Webhook to notify issuer to take action, such as generating a verification code.

The Initiate Action call takes place once the method of StepUp authentication is identified. The objective of this endpoint is to send the cardholder notification, so the cardholder can be aware of the authentication.

Webhook specifications
Request fields
Field Type Description Req
id string Pismo-generated unique authorization ID Y
provider enum
string		 Third-party provider name:
* VCAS		 Y
type enum
string		 Call type:
* INITIATE_ACTION_CALL
card object Card information object Y
id integer Card ID Y
mode_id integer Card mode ID Y
type enum
string		 Card type:
* PLASTIC
* VIRTUAL
* RECURRING
* TEMPORARY		 Y
hash string Encrypted PAN using 2048 rsa key and base64 encoded. Pismo provides the encryt/decrypt keys for this field. Y
bin string Card Bank Identification Number (BIN). A 6 or 8 digit value Y
last_four_digits string Card last 4 PAN digits Y
account object Account information object Y
id string Pismo account ID Y
document_number string Cardholder document number. A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Y
email string E-mail. Y
phones object
array		 Phone objects Y
area_code string Phone area code Y
country_code string Phone number country code Y
number string Phone number without area code Y
type enum
string		 Phone type:
* mobile
* commercial
* residential		 Y
program object Program information object Y
id integer Program ID Y
customer object Customer information object Y
id integer Customer ID Y
raw_provider object All non-PCI information received from provider. Check provider documentation for details. Y
Sample request 
{
  "id": "ff77635e-1cd6-4fda-992d-5ceb71d75644",
  "provider": "VCAS",
  "type": "initiate_action",
  "card": {
    "id": 869572,
    "mode_id": 102,
    "type": "PLASTIC",
    "hash": "WEPvOQuZvjfYEd0iBmr43bhWyOsylIsW95ebYrLD89App2iEq9IizP+8w73pxKQ4mI47EdhzYHF9RfXjrBOyug==",
    "bin": "885692",
    "last_four_digits": "0153"
  },
  "account": {
    "id": 10045896,
    "document_number": "00011122233",
    "phones": [
      {
        "area_code": "31",
        "country_code": "55",
        "number": "998675309",
        "type": "mobile"
      }
    ],
    "email": "[email protected]"
  },
  "program": {
    "id": 986
  },
  "customer": {
    "id": 867604
  },
  "raw_provider": {
    "ProcessorId": "5723ae630063ac1a9c3ab079",
    "IssuerId": "5723ae630063ac1a9c3ab083",
    "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "DSTransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f987",
    "ThreeDSRequestorAuthenticationInd": "01",
    "StepupRequestId": "878f4751-4140-4881-9e4a-003e83524f22",
    "DeviceLocale": "en-US",
    "DeviceUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
    "MessageVersion": "2.2.0",
    "RDXMessageVersion": "2.2.3",
    "MessageCategory": "01",
    "MerchantInfo": {
      "AcquirerId": "1337",
      "AcquirerCountryCode": "840",
      "MerchantId": "876543210",
      "MerchantName": "Ranier Expeditions",
      "MerchantURL": "https://www.requestor.com",
      "MerchantCategoryCode": "0123",
      "MerchantCountryCode": "840",
      "MerchantAppRedirectURL": "merchantScheme://appName?transID=b2385523-a66c-4907-ac3c-91848e8c0067"
    },
    "TransactionInfo": {
      "TransactionCurrency": "840",
      "Channel": "WEB"
    }
  }
}
Response fields
Field Type Description Req
raw_response object Raw response to VCAS initiate action request, according with VCAS documentation Y
Sample response 

{
  "raw_response": {
    "ProcessorId": "7723ae630063ac1a9c3ab07976",
    "IssuerId": "5723ae630063ac1a9c3ab080",
    "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "StepupRequestId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "StepupType": "OTP",
    "Language": "string",
    "Status": "SUCCESS",
    "TransStatusReason": "string",
    "RiskIndicator": "string",
    "Credentials": [
      {
        "Id": "d94fd3fd-bef1-49cb-88ab-a6841261cea9",
        "Type": "OTPEMAIL",
        "Text": "******@cardinalcommerce.com"
      }
    ],
    "Reason": {
      "ReasonCode": "string",
      "ReasonDescription": "string"
    },
    "Error": {
      "ReferenceNumber": "string",
      "ReasonDescription": "string",
      "Description": "string",
      "Message": "string"
    }
  }
}

VCAS Validate

Webhook request to validate the verification code.

In the case of the authentication method, the Validate call is used to send the OTP the cardholder entered into the VCAS Validate screen.

Webhook specifications
Request fields
Field Type Description Req
id string Pismo-generated unique authorization ID Y
provider enum
string		 Third-party provider name:
* VCAS		 Y
type enum
string		 Call type:
* VALIDATE
raw_provider object All non-PCI information received from provider. Check provider documentation for details. Y
Sample request 
{
  "id": "ff77635e-1cd6-4fda-992d-5ceb71d75644",
  "provider": "VCAS",
  "type": "validate",
  "raw_provider": {
    "ProcessorId": "5723ae630063ac1a9c3ab079",
    "IssuerId": "5723ae630063ac1a9c3ab481",
    "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "DSTransactionId": "521fa021-4791-4579-a3e9-76de87c219c0",
    "StepupRequestId": "878f4751-4140-4881-9e4a-003e83524f22",
    "MessageVersion": "2.2.0",
    "RDXMessageVersion": "2.2.3"
  }
}
Response fields
Field Type Description Req
raw_response object Raw response to VCAS initiate action request, according with VCAS documentation Y
Sample response 

{
  "raw_response": {
    "ProcessorId": "5723ae630063ac1a9c3ab079",
    "IssuerId": "5723ae630063ac1a9c3ab671",
    "TransactionId": "00ec043e-40b5-4ce4-95c2-9e83b644f412",
    "StepupRequestId": "00ec043e-40b5-4ce4-95c2-9e83b644f618",
    "Language": "string",
    "CredentialId": "string",
    "Status": "SUCCESS",
    "TransStatusReason": "string",
    "RiskIndicator": "string",
    "Reason": {
      "ReasonCode": "string",
      "ReasonDescription": "string"
    },
    "Error": {
      "ReferenceNumber": "string",
      "ReasonDescription": "string",
      "Description": "string",
      "Message": "string"
    },
    "RReqOverrides": {
      "AuthenticationMethod": "SMS_OTP",
      "TransStatusReason": "CARD_AUTH_FAILED",
      "AuthenticationAttempts": "string",
      "CustomerCancel": true
    }
  }

Updated 16 days ago

Related pages

For more information on VCAS and its use cases, refer to: