--- title: "Validate an existing alias" method: POST path: "/v1/transactions/validate" tags: ["/v1/transactions"] --- # Validate an existing alias `POST /v1/transactions/validate` An existing alias can be validated at any time with the transaction validate API. No amount will be blocked on the customers account. Only credit cards (including Apple Pay and Google Pay), `PFC`, `KLN` and `PAP` support validation of an existing alias. ## Request body - ValidateRequest - `refno` string, required — The merchant's reference number. It should be unique for each transaction. - `refno2` string — Optional customer's reference number. Supported by some payment methods or acquirers. - `currency` string, required — 3 letter ISO-4217 character code. For example `CHF` or `USD` - `card` CardValidateRequest — The card object to be submitted when validating with an existing credit card alias. - `alias` string — An alias (token) received from a previous transaction if `option.createAlias` was set to `true`. In order to retrieve the alias from a previous transaction, use the [Status API](#operation/status). - `number` string — Merchants that have the option to store card information on their end can use the `number` property instead of `alias`. Please note that this option is only available to merchants that fulfill the requirements by PCI DSS to store sensitive information on their side and only upon request. - `expiryMonth` string — The expiry month of the credit card alias. - `expiryYear` string — The expiry year of the credit card alias - `cardOnFile` CardOnFileAuthorize — Card On File (COF) parameters. COF usually is handled by Datatrans aliases. This feature is only for specific use cases where the Datatrans alias solution cannot be used. This feature needs to be enabled on the merchant configuration by Datatrans. - `enroll` boolean — If `true`, a Card On File (COF) enrollment is performed. The created card on file ID will be returned in the authorize response. This COF ID can be reused in subsequent MIT authorizations. - `id` string — The card on file ID to be used for this transaction. - `3D` EMVCo3DAuthenticationDataAuthorizeRequest — If 3D authentication data is available, the `3D` object can be used to send the relevant 3D parameters. Please get in contact with us if you have a dedicated 3D provider. - `eci` '01' | '02' | '05' | '06' | '07' — The Electronic Commerce Indicator - `xid` string — The transaction ID returned by the directory server - `threeDSTransactionId` string — The transaction ID returned by the 3D Secure Provider - `cavv` string — The Cardholder Authentication Verification Value - `threeDSVersion` string — The 3D version - `cavvAlgorithm` string — The 3D algorithm - `directoryResponse` 'Y' | 'N' | 'U' | 'C' | 'R' | 'A' — Transaction status after `ARes` |Value|3Dv1|3Dv2| |:---|:---|:---| |Y| enrolled| authenticated| |N| not enrolled| authentication failed| |U| not available| not available| |C| |challenge needed| |R| |rejected| |A| |authentication attempt| - `authenticationResponse` 'Y' | 'N' | 'U' | 'A' | 'C' | 'R' | 'I' | 'D' — Transaction status after `RReq` (Challenge flow) |Value|3Dv1|3Dv2| |:---|:---|:---| |Y| authenticated| authenticated| |N| authentication failed| authentication failed| |U| not available| not available| |A| authentication attempt| authentication attempt| |C| process incomplete| process incomplete| |R| |authentication/account verification rejected| |I| |informational only| |D| not enrolled| | - `transStatusReason` string — Transaction status reason |Value|Description| |:---|:---| |01| Card authentication failed| |02| Unknown Device| |03| Unsupported Device| |04| Exceeds authentication frequency limit| |05| Expired card| |06| Invalid card number| |07| Invalid transaction| |08| No Card record| |09| Security failure| |10| Stolen card| |11| Suspected fraud| |12| Transaction not permitted to cardholder| |13| Cardholder not enrolled in service| |14| Transaction timed out at the ACS| |15| Low confidence| |16| Medium confidence| |17| High confidence| |18| Very High confidence| |19| Exceeds ACS maximum challenges| |20| Non-Payment transaction not supported| |21| 3RI transaction not supported| |22| ACS technical issue| |23| Decoupled Authentication required by ACS but not requested by 3DS Requestor| |24| 3DS Requestor Decoupled Max Expiry Time exceeded| |25| Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt| |26| Authentication attempted but not performed by the cardholder| |27–79| Reserved for EMVCo future use (values invalid until defined by EMVCo)| |80–99 | Reserved for DS use| - `cbAvalgo` string - `cbScore` string - `cbExemption` string - `PFC` PfcValidateRequest — PostFinance Card specific parameters - `alias` string, required — An alias (token) received from a previous transaction if `option.createAlias` was set to `true`. In order to retrieve the alias from a previous transaction, use the [Status API](#operation/status). - `KLN` KlarnaValidateRequest — Klarna specific parameters - `alias` string — An alias (token) received from a previous transaction if `option.createAlias` was set to `true`. In order to retrieve the alias from a previous transaction, use the [Status API](#operation/status). - `PAP` PayPalValidateRequest — PayPal specific parameters for the validate request. - `alias` string — An alias (token) received from a previous transaction if `option.createAlias` was set to `true`. In order to retrieve the alias from a previous transaction, use the [Status API](#operation/status). - `PAY` GooglePayValidateRequest — Google Pay specific parameters for the validate request. - `signature` string — Verifies that the message came from Google. It's Base64-encoded, and created with ECDSA by the intermediate signing key. - `protocolVersion` string — Identifies the encryption or signing scheme under which the message was created. It allows the protocol to evolve over time, if needed. - `signedMessage` string — A JSON object serialized as a string that contains the encryptedMessage, ephemeralPublicKey, and tag. It's serialized to simplify the signature verification process. - `intermediateSigningKey` IntermediateSigningKey — A JSON object that contains the intermediate signing key from Google. It contains the signedKey with keyValue, keyExpiration, and signatures. It's serialized to simplify the intermediate signing key signature verification process. - `signedKey` string - `signatures` object[] - `APL` ApplePayValidateRequest — Apple Pay specific parameters for the validate request. - `data` string — Encrypted payment data. - `header` Header — Additional version-dependent information used to decrypt and verify the payment. - `publicKeyHash` string — Hash of the X.509 encoded public key bytes of the merchant’s certificate. - `ephemeralPublicKey` string — Ephemeral public key bytes. `EC_v1` only. - `transactionId` string — Transaction identifier, generated on the device. - `signature` string — Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. - `version` string — Version information about the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data. - `ESY` EasyPayValidateRequest — Swisscom Pay specific parameters - `alias` string — An alias (token) received from a previous transaction if `option.createAlias` was set to `true`. In order to retrieve the alias from a previous transaction, use the [Status API](#operation/status). ## Response `200` Alias successfully validated - AuthorizeResponse - `transactionId` string — The transactionId to use for subsequent actions like settlement. - `acquirerAuthorizationCode` string — The authorization code returned by the acquirer or payment method provider. - `card` AuthorizeCardDetail — Details of the used card. - `alias` string — The resulting alias, if requested or available. - `masked` string — Masked credit card number. Can be used to display on a users profile page. For example: `424242xxxxxx4242` - `cardOnFile` AuthorizeCardOnFileResponse — Card On File (COF) parameters. COF usually is handled by Datatrans aliases. This feature is only for specific use cases where the Datatrans alias solution cannot be used. This feature needs to be enabled on the merchant configuration by Datatrans. - `id` string — The external card on file (CoF) Id in case `card.cardOnFile.enroll` was set to `true` - `accertify` Accertify — Accertify decision (Accepted, Review, Declined ## Other responses - `400` — Invalid request --- [API](https://skmtc.net/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints.md) · [All operations](https://skmtc.net/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pci-proxy/pci-proxy-api-reference-datatrans-endpoints/versions/1f4f905fd175/schema)