--- title: "Initiate Action" method: POST path: "/pws/initiateaction/" tags: ["VCAS"] --- # Initiate Action `POST /pws/initiateaction/` ## Request - Base URL: `https://api.uat.paymentology.com/ppws/api` - URL: `https://api.uat.paymentology.com/ppws/api/pws/initiateaction/` - Auth: none declared Initiate Action request is used to signal to the partner to take action on an item. ## Request body - InitiateActionRequest - `Credentials` Credential[], required: Credentials for authentication - `Id` string, required: Identifier for the credential requested, this will be passed on the InitiateAction request as well as the ValidateRequest. Length will be 36 Characters. The Id must be unique per credential object returned. The Id is used to distinguish the specific authenticate type in preceding InitiateAction and ValidateRequest calls. - `Type` 'OTPEMAIL' | 'OTPSMS' | 'OTPIVR' | 'KBASINGLE' | 'KBAMULTI' | 'BIOMETRIC' | 'OUTOFBANDOTHER', required: Type of the Credential used for stepup, this is meta data and will not be used in any business logic - `Text` string: Dynamic data to be displayed to the cardholder i.e. masked phone number or email address. Note: certain browser screen templates will only be able to show a certain number of characters before showing an elipsis (...). Up to 35 characters. Note: in EMV SDK flows the text space is limited. Up to 40 characters. - `CustomerId` string: Holds issuer’s customer ID for creating/building behavioral biometrics profile. - `Token` string: Token field will be contained in the post request to the issuer and posted in the embedded iframe. - `IssuerId` string, required: Cardinal provided identifier for the partner. Length - Up to 24 Characters - `MessageVersion` string, required: Version of the message based on 3DS spec. Examples - 1.0.2, 2.1.0, 2.2.0 - `ProcessorId` string, required: Cardinal provided identifier for the partner. Length - Up to 24 Characters - `StepupCounter` integer, required: Counter for tracking the number of Stepups. Each stepup can go from Stepup -> InitiateAction -> Validate. If the user requests a "resend" via the browser templates it will initiate another Stepup request. - `StepupRequestId` string, required: Unique identifier to identify the particular Stepup request. Length will be 36 Characters. - `TransactionId` string, required: VCAS generated transaction reference id. Length - Up to 36 Characters. 3DS 1.0.2 - 28 character alpha-numeric. EMV 3DS - 36 character GUID. - `DSTransactionId` string: Directory Server (DS) generated transaction reference id. GUID Format. Note: EMV 3DS Transactions only - `StepupType` 'CHOICE' | 'OTP' | 'KBA' | 'BIOMETRIC' | 'OUTOFBAND' | 'OTP_AND_KBA' | 'OTP_CHOICE_AND_KBA': Used to identify what type of stepup. - `OtpReferenceCode` string: This is a unique value generated with each new OTP value or 'VerificationToken'. In the instance where the consumer can receive multiple OTPs for the same transaction, this can be leveraged to show the consumer which OTP the system is expecting to be entered. This value should be sent in the SMS or Email along with the VerificationToken and then displayed on the consumer screen. - `VerificationToken` string: Token to be sent to cardholder. - `RDXMessageVersion` string: Version of the RDX protocol being used. This will be used to enable new features without breaking current integrations. Example: 2.2.0 and 2.2.1 - `MerchantInfo` MerchantInfo - `merchantId` string - `merchantName` string - `PaymentInfo` PaymentInfo: Payment information - `CardExpiryMonth` string, required: Expiration month - `CardExpiryYear` string, required: Expiration year. For 3DS1 Transactions this value is 4-digits e.g. 2019. For 3DS2 Transactions this value is 2-digits e.g. 19. - `CardNumber` string, required: Payment card number used in transaction. Length - between 13 and 19 Characters - `CardType` 'Credit' | 'Debit' | 'NotApplicable': Card or account type e.g. Debit or Credit. - `CardHolderName` string: Name of the cardholder. Length - Up to 45 Characters - `TransactionInfo` BasicTransactionInfo: Transaction information - `TransactionTimeStamp` string: Transaction timestamp in UTC per ISO 8601 UTC. Length - 24 Characters e.g 2019-03-21T20:55:49.000Z - `TransactionAmount` number: Transaction Amount (raw amount, example 1000 for $10.00). Length - Up to 48 Characters - `TransactionCurrency` string: ISO 4217 3 digit numeric standard.[ISO 4217 Link] https://en.wikipedia.org/wiki/ISO_4217 Length - 3 Characters - `TransactionExponent` integer: Exponent for formatting the given currency ISO 4217 code. Length - 1 Character - `TransactionType` 'Purchase' | 'CardAdd': Type of the transaction. - `MandatedRegion` 'EEA' | 'NONE' | 'UNKNOWN': A value describing the region in which mandates may apply to the current transaction. Added to support the new PSD2 transactions in the EEA. A value of EEA will denote that the transaction falls under the PSD2 mandates, otherwise the value will be null. Note - you must account for new values being added to this field over time due to new regulations being rolled out in other regions - `Channel` 'WEB' | 'APP' | 'MWEB' | 'THREERI': Channel in which the transaction occurs. - `3RIIndicator` string: Indicates the type of 3RI request for EMV transactions. - `ThreeDSRequestorAuthenticationInd` string: Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request. ## Response `200` Successful Response - InitiateActionResponse - `Credentials` Credential[], required: A list of Credential objects that will be used to challenge the user. This must contain at least one consumer contact information. If multiple are returned VCAS can configure your setup to show the user a “choice screen”. - `Id` string, required: Identifier for the credential requested, this will be passed on the InitiateAction request as well as the ValidateRequest. Length will be 36 Characters. The Id must be unique per credential object returned. The Id is used to distinguish the specific authenticate type in preceding InitiateAction and ValidateRequest calls. - `Type` 'OTPEMAIL' | 'OTPSMS' | 'OTPIVR' | 'KBASINGLE' | 'KBAMULTI' | 'BIOMETRIC' | 'OUTOFBANDOTHER', required: Type of the Credential used for stepup, this is meta data and will not be used in any business logic - `Text` string: Dynamic data to be displayed to the cardholder i.e. masked phone number or email address. Note: certain browser screen templates will only be able to show a certain number of characters before showing an elipsis (...). Up to 35 characters. Note: in EMV SDK flows the text space is limited. Up to 40 characters. - `CustomerId` string: Holds issuer’s customer ID for creating/building behavioral biometrics profile. - `Token` string: Token field will be contained in the post request to the issuer and posted in the embedded iframe. - `IssuerId` string, required: Echoed from Request. Length - Up to 24 Characters - `ProcessorId` string, required: Echoed from Request. Length - Up to 24 Characters - `Status` 'SUCCESS' | 'FAILURE' | 'RETRY' | 'PENDING' | 'BLOCKED' | 'STEPUP' | 'ERROR' | 'ATTEMPTS' | 'FAILWITHFEEDBACK' | 'REJECTED' | 'FAIL' | 'CHALLENGE' | 'AUTHENTICATED', required: ERROR is returned on any interal/technical issues. ATTEMPTS is only supported for 1.0.2 transactions. REJECTED is only supported for 2.x.x transactions. AUTHENTICATED will return a Y back to merchant - `StepupRequestId` string, required: Echoed from Request. Length - 36 Characters - `TransactionId` string, required: Echoed from Request. Length - Up to 36 Characters - `Language` string: Language to display the instructions and prompt to the cardholder. This value will decide which template is loaded, provided the correct template language is available. If not provided, the language is selected based on Issuer configuration and browser preference e.g. en-US. Length - Up to 8 Characters - `Reason` Reason: An object that can be used for sending a status code and description. - `ReasonCode` string: Used by the issuer for informational purposes. Length - Up to 32 Characters - `ReasonDescription` string: Used by the issuer for informational purposes. Length - Up to 256 Characters - `Error` ErrorMessage: An object that can be used to convey an error message on the response. - `ReferenceNumber` string: System reference number for the error message. Length - Up to 15 Characters - `Description` string: A description of the error. Length - Up to 50 Characters - `Message` string: A message that will be displayed to the customer on the error screen. Length - Up to 100 Characters - `ReasonDescription` string: Used by the issuer for informational purposes. Up to 256 characters. - `RiskIndicator` string: If returned, this value will be used in the creation of certain Authentication Values (AV) for EMV 3DS. The value passed must conform to the current AV value the Issuer is using. This may also depend on the card brand of the transaction. For example, CAVV and IAV accept different values. On Challenge responses (Stepup, Initiate, Validate) this value is currently ignored for CAVV usages in favor of mapping to the 'Credential Type'. For Enhanced IAV SPA2 usage, if passed, this value will override the mapping to the 'Credential Type'. Note: This field is only available for EMV 3DS transactions and not available on 3DS 1 transactions Note: The value here will be converted to the Hexadecimal equivalent. Please see 'VCAS Enhanced AV' document for more details on current AVs available and the corresponding values. - `TransStatusReason` string: Provides information on why the Transaction Status field has the specified value. 2 characters. ## Other responses - `404`: Webservices does not exist - `500`: Internal Server error ## Changes - **2026-11-03** `73c2771493b1`: 1 info - endpoint added [Operation history](https://skmtc.dev/paymentology/apis/payapi-docs/changes/pws/initiateaction/post.md) --- [API](https://skmtc.dev/paymentology/apis/payapi-docs.md) - [All operations](https://skmtc.dev/paymentology/apis/payapi-docs/llms.txt) - [OpenAPI document](https://skmtc.dev/paymentology/apis/payapi-docs/revisions/73c2771493b1?raw)