--- title: "Initialize a Secure Fields transaction" method: POST path: "/v1/transactions/secureFields" tags: ["/v1/transactions"] --- # Initialize a Secure Fields transaction `POST /v1/transactions/secureFields` ## Request - Base URL: `https://api.sandbox.datatrans.com` - URL: `https://api.sandbox.datatrans.com/v1/transactions/secureFields` - Auth: HTTP basic Proceed with the steps below to process [Secure Fields payment transactions](https://docs.datatrans.ch/docs/integrations-secure-fields): - Call the /v1/transactions/secureFields endpoint to retrieve a `transactionId`. The success result of this API call is a `HTTP 201` status code with a `transactionId` in the response body. - Initialize the `SecureFields` JavaScript library with the returned `transactionId`: ```js var secureFields = new SecureFields(); secureFields.init( transactionId, { cardNumber: "cardNumberPlaceholder", cvv: "cvvPlaceholder", }); ``` - Handle the `success` event of the `secureFields.submit()` call. Example `success` event data: ```json { "event":"success", "data": { "transactionId":"{transactionId}", "cardInfo":{"brand":"MASTERCARD","type":"credit","usage":"consumer","country":"CH","issuer":"DATATRANS"}, "redirect":"https://pay.sandbox.datatrans.com/upp/v1/3D2/{transactionId}" } } ``` - If 3D authentication is required, the `redirect` property will indicate the URL that the browser needs to be redirected to. - Use the [Authorize an authenticated transaction](#operation/authorize-split) endpoint to authorize the Secure Fields transaction. This is required to finalize the authorization process with Secure Fields. - Use the `transactionId` to check the [status](#operation/status) and to [settle](#operation/settle), [cancel](#operation/cancel) or [credit (refund)](#operation/credit) a transaction. ## Request body - DefaultSecureFieldsInitRequest - `amount` integer: The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. - `currency` string, required: 3 letter ISO-4217 character code. For example `CHF` or `USD` - `returnUrl` string: The URL where the browser will be redirected after the 3D authentication process. Required unless `authentication.apply` is explicitly set to `false`. - `returnMethod` 'GET' | 'POST': The preferred HTTP method for the redirect request (`GET` or `POST`). - `mcp` InitMcpRequest - `currency` string, required: The targeted currency - `amount` integer, required: The amount in your targeted currency - `conversionRate` number, double: Conversion rate received from the currency rates endpoint. Required in case of dynamic MCP. - `transactionDate` string, date-time: Transaction datetime received from the currency rates endpoint - `retrievalReferenceNumber` string: RetrievalReferenceNumber received from the currency rates endpoint - `userId` string, required - `provider` string, required: The provider for multi currency processing - `reasonIndicator` string, required: If received from acquirer the reason indicator can be set - `3D` SecureFieldsThreeDSecure: Refer to the official EMVCo. specifications for parameter requirements. - `threeDSRequestor` ThreeDSRequestor: Contains information for the 3DS Requestor. - `threeDSRequestorAuthenticationInd` '01' | '02' | '03' | '04' | '05' | '06' | '80' | '81' | '82' | '83' | '84' | '85' | '86' | '87' | '88' | '89' | '90' | '91' | '92' | '93' | '94' | '95' | '96' | '97' | '98' | '99' - `threeDSRequestorAuthenticationInfo` ThreeDSRequestorAuthenticationInformation - `threeDSReqAuthMethod` '01' | '02' | '03' | '04' | '05' | '06' - `threeDSReqAuthTimestamp` string, date-time - `threeDSReqAuthData` string - `threeDSRequestorChallengeInd` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '82' | '90' - `threeDSRequestorDecReqInd` 'Y' | 'N' - `threeDSRequestorDecMaxTime` integer - `threeDSRequestorURL` string, url: Fully qualified URL of 3DS Requestor website or customer care site. This field is optional and it is recommended to be configured in the configuration. - `cardholderAccount` CardholderAccount: Contains information for the Cardholder Account. - `cardExpiryDate` string - `acctInfo` CardholderAccountInformation - `chAccDate` string, date-time - `chAccChangeInd` '01' | '02' | '03' | '04' - `chAccChange` string, date-time - `chAccPwChangeInd` '01' | '02' | '03' | '04' | '05' - `chAccPwChange` string, date-time - `shipAddressUsageInd` '01' | '02' | '03' | '04' - `shipAddressUsage` string, date-time - `txnActivityDay` integer - `txnActivityYear` integer - `provisionAttemptsDay` integer - `nbPurchaseAccount` integer - `suspiciousAccActivity` '01' | '02' - `shipNameIndicator` '01' | '02' - `paymentAccInd` '01' | '02' | '03' | '04' | '05' - `paymentAccAge` string, date-time - `acctID` string - `cardholder` Cardholder: Contains information for the Cardholder. This field is required unless market or regional mandate restricts sending this information. - `addrMatch` 'Y' | 'N' - `billAddrCity` string: The city of the Cardholder billing address associated with the card used for this purchase. This field is limited to maximum of 50 characters. Required unless market or regional mandate restricts sending this information. - `billAddrCountry` string: The country of the Cardholder billing address associated with the card used for this purchase. This field is limited to 3 characters. This value shall be the ISO 3166-1 numeric country code, except values from range 901 - 999 which are reserved by ISO. - `billAddrLine1` string: First line of the street address or equivalent local portion of the Carholder billing address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `billAddrLine2` string: Second line of the street address or equivalent local portion of the Carholder billing address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `billAddrLine3` string: Third line of the street address or equivalent local portion of the Carholder billing address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `billAddrPostCode` string: ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. This field is limited to maximum 16 characters. - `billAddrState` string: The state or province of the Cardholder billing address associated with the card used for this purchase. This field is limited to 3 characters. The value should be the country subtivision code defined in ISO 3166-2. - `email` string: The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. This field is limited to maximum 256 characters and shall meet requirements of Section 3.4 of IETF RFC 5322. This field is required unless market or regional mandate restricts sending this information. - `homePhone` CardholderPhoneNumber: The work phone provided by the Cardholder. The object contains the following fields: cc -> Country Code of the phone, limited to 1-3 characters subscriber -> subscriber section of the number, limited to maximum 15 characters. Refer to ITU-E.164 for additional information on format and length. - `cc` string - `subscriber` string - `mobilePhone` CardholderPhoneNumber: The work phone provided by the Cardholder. The object contains the following fields: cc -> Country Code of the phone, limited to 1-3 characters subscriber -> subscriber section of the number, limited to maximum 15 characters. Refer to ITU-E.164 for additional information on format and length. - `cc` string - `subscriber` string - `workPhone` CardholderPhoneNumber: The work phone provided by the Cardholder. The object contains the following fields: cc -> Country Code of the phone, limited to 1-3 characters subscriber -> subscriber section of the number, limited to maximum 15 characters. Refer to ITU-E.164 for additional information on format and length. - `cc` string - `subscriber` string - `cardholderName` string: Name of the Cardholder. This field is limited to maximum of 50 characters. This field is required unless market or regional mandate restricts sending this information. - `shipAddrCity` string: City portion of the shipping address requested by the Cardholder. - `shipAddrCountry` string: Country of the shipping address requested by the Cardholder. This field is limited to 3 characters. This value shall be the ISO 3166-1 numeric country code, except values from range 901 - 999 which are reserved by ISO. - `shipAddrLine1` string: First line of the street address or equivalent local portion of the shipping address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `shipAddrLine2` string: Second line of the street address or equivalent local portion of the shipping address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `shipAddrLine3` string: Third line of the street address or equivalent local portion of the shipping address associated with the card use for this purchase. This field is limited to maximum 50 characters. - `shipAddrPostCode` string: ZIP or other postal code of the shipping address associated with the card used for this purchase. This field is limited to maximum 16 characters. - `shipAddrState` string: The state or province of the shipping address associated with the card used for this purchase. This field is limited to 3 characters. The value should be the country subtivision code defined in ISO 3166-2. - `purchase` Purchase: Contains purchase information. - `purchaseInstalData` integer - `merchantRiskIndicator` MerchantRiskIndicator - `shipIndicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' - `deliveryTimeframe` '01' | '02' | '03' | '04' - `deliveryEmailAddress` string - `reorderItemsInd` '01' | '02' - `preOrderPurchaseInd` '01' | '02' - `preOrderDate` string, date-time - `giftCardAmount` integer - `giftCardCurr` string - `giftCardCount` string - `purchaseAmount` integer - `purchaseCurrency` string - `purchaseExponent` integer - `purchaseDate` string, date-time - `recurringExpiry` string, date-time - `recurringFrequency` integer - `transType` '01' | '03' | '10' | '11' | '28' - `merchant` MerchantData: Contains merchant information. - `whiteListStatus` 'Y' | 'N' - `broadInfo` string - `browserInformation` Browser: Contains browser information. - `browserAcceptHeader` string: Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser. This field is limited to maximum 2048 characters and if the total length exceeds the limit, the 3DS Server truncates the excess portion. This field is required for requests where deviceChannel=02 (BRW). - `browserIP` string: IP address of the browser as returned by the HTTP headers to the 3DS Requestor. The field is limited to maximum 45 characters and the accepted values are as following: - IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255 - IPv6 adress is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334 - `browserJavaEnabled` boolean: Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. - `browserLanguage` string: Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. Required when BrowserJavaScriptEnabled = true; otherwise Optional. - `browserColorDepth` '1' | '4' | '8' | '15' | '16' | '24' | '32' | '48': Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. The field is limited to 1-2 characters. For a list of possible values, refer to https://www.w3schools.com/jsref/prop_screen_colordepth.asp - `browserScreenHeight` integer: Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. The value is limited to 1-6 characters. Required when BrowserJavaScriptEnabled = true; otherwise Optional. - `browserScreenWidth` integer: Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. The value is limited to 1-6 characters. Required when BrowserJavaScriptEnabled = true; otherwise Optional. - `browserTZ` integer: Time zone offset in minutes between UTC and the Cardholder Browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Required when BrowserJavaScriptEnabled = true; otherwise Optional. - `browserUserAgent` string: Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion. - `challengeWindowSize` '01' | '02' | '03' | '04' | '05': Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width X height in pixels of the window displayed in the Cardholder browser window. This is used only to prepare the CReq request and it is not part of the AReq flow. If not present it will be omitted. Accepted values are: 01 -> 250 x 400 02 -> 390 x 400 03 -> 500 x 600 04 -> 600 x 400 05 -> Full screen - `browserJavascriptEnabled` boolean: Boolean that represents the ability of the cardholder browser to execute JavaScript. - `deviceId` string: Unique and immutable identifier linked to a device that is consistent across 3DS transactions for the specific user device, maximum length 64 characters. Available for supporting EMV 3DS 2.3.1 and later versions. - `returnResources` boolean: If `true`, JavaScript resources with Subresource Integrity (SRI) information are returned in the response. - `authentication` Authentication - `apply` boolean ## Response `201` Transaction successfully initialized - SecureFieldsInitResponse - `transactionId` string: The `transactionId` to be used when calling SecureFields.init(). If no further action happens with the `transactionId` after initialization, it will be invalidated after 30 minutes. - `resources` JavascriptResource[] - `uri` string: URI of the JavaScript resource - `integrity` string: Subresource Integrity hash (SHA-384) ## Other responses - `400`: Invalid request ## Changes - **2026-11-03** `78b27ccc5443`: 1 info - endpoint added [Operation history](https://skmtc.dev/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints/changes/v1/transactions/secureFields/post.md) --- [API](https://skmtc.dev/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints.md) - [All operations](https://skmtc.dev/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/pci-proxy/apis/pci-proxy-api-reference-datatrans-endpoints/revisions/78b27ccc5443?raw)