--- title: "Stepup" method: POST path: "/pws/stepup/" tags: ["VCAS"] --- # Stepup `POST /pws/stepup/` ## Request - Base URL: `https://api.uat.paymentology.com/ppws/api` - URL: `https://api.uat.paymentology.com/ppws/api/pws/stepup/` - Auth: none declared Stepup request is communicate by the VCAS platform to the partner, and the partner responds with parameters necessary for VCAS to perform the step-up challenge. ## Request body - StepupRequest - `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 - `DeviceLocale` string: Device Locale from the browser header or from the app's language settings. This value can be a single locale value or multiple concatenated together via commas. In 3DS1 this value will be directly from the browser's "Accept-Language" header. However, in 3DS2 this is not available due to new flows so this will be a single language value following BCP 47 format e.g. en-US or en,es-PE;q=0.9,es;q=0.8 - `DeviceUserAgent` string: Device user agent from the browser header or the app's device identifier. Length - Up to 2048 Characters - `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 - `StepupReason` 'CARDHOLDER_RESEND': Used to identify the reason the Stepup request was initiated. Only available for Cardholder Resend, future values and scenarios may be added. - `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. - `CardholderSelectionInfo` CardholderSelectionInfo: Object defining the consumers selection during the Cardholder Selection OTP flow. This feature is only populated and enabled for Issuers supporting this flow. - `Type` 'P' | 'S': Type describing the cardholder selection e.g. Primary (P) or Secondary (S) cardholder. - `Name` string: The name of the selected cardholder. Only needed if Secondary cardholder is selected to match against. - `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. - `MessageCategory` string: Identifies the category of the message for a specific use case. ## Response `200` Successful Response - StepupResponse - `Credentials` Credential[], required: A list of Credential objects that will be used to challenge the user. This must contain at least one credential object. If multiple objects 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 the 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. - `StepupType` 'CHOICE' | 'OTP' | 'KBA' | 'BIOMETRIC' | 'OUTOFBAND' | 'OTP_AND_KBA' | 'OTP_CHOICE_AND_KBA': Used to identify what type of stepup. - `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. - `WhyInfo` WhyInfo: Object defining dynamic text values that can be shown to the consumer during the challenge flow. These fields will be mapped directly to both browser templates and SDK info fields. Note: this field is also configurable for SDK screens today via our template configuration. If this value is passed on RDX it will override the current configurable value. - `Label` string: Label to be displayed to the Cardholder for the "why" information section. - `Text` string: Text provided by the Issuer to be displayed to the Cardholder to explain why the Cardholder is being asked to perform the authentication task. Note: Carriage return is supported in this data element and is represented by an “\n”. - `IsBbConsentRequired` boolean: Indicates if legal consent is required for the behavioral biometrics flow. - `TransStatusReason` string: Provides information on why the Transaction Status field has the specified value. - `oobAppURL` string: URL provided for OOB app-based authentication flow. The URL will redirect the user to the appropriate location within the authentication app. Not applicable for browser-based authentication. ## 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/stepup/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)