3D Secure

This function is used to process a request via the 3D Secure process without authorizing the payment. This will return the result of the 3D Secure process as well as the 3D Secure data that can then be used to process a payment via the Authorization or Sale/Purchase endpoint.

Integration Methods:

Host Direct

See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option.

Security

AccessToken

Headers

InterfaceVersionstring<= 11 charactersrequired

Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed: $ % : ^ - ~ < > , ? “ ” ‘ ’ { } [ ] \ + =

Example: 2.1

InterfaceNamestring<= 25 charactersrequired

Refers to the name of the program or application that is sending requests to Shift4. This should be the name of the program that you purchased or created. The following special characters are not allowed: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =

Example: ForwardPOS

CompanyNamestring<= 26 charactersrequired

Refers to the vendor or partner that designed and certified the interface. The information you use in this field should match what Shift4 has on file or what was agreed upon in your Integration Plan. The following special characters are not allowed: $ % : ^ - ~ ` < > , ? “ ” ‘ ’ { } [ ] \ + =

Example: PAWS

AccessTokenstring(uuid)<= 52 charactersrequired

A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an authToken and clientGuid.

Example: EA79FB05-3AA7-4500-AF9A-73F986FF2C1D

Bodyapplication/jsonrequired

One of:

dateTimestring(ISO 8601)required

The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm).

Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00

Example: "2022-05-04T09:18:23.283-07:00"

amountobjectrequired

Object containing information regarding the amount being requested. The total field within the object is required and specifies the amount being requested.

Note: For merchants that are configured to allow multiple currencies, the amount fields can specify up to three decimal places. However, the number of decimal places can not exceed the number allowed for the specified currency. See the Currency Codes section for details.

Example: {"total":160}

amount.totalnumber<= 14 charactersrequired

The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero.

Example: 160

transactionobjectrequired

Example: {"invoice":"730518","notes":"Transaction notes are added here"}

transaction.invoicestring<= 10 charactersrequired

10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway.

Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.

For processing outside of the US and Canada alpha characters are allowed.

Example: "730518"

transaction.notesstring<= 4096 characters

A free-form notes field that supports the use of HTML tags. This can be used for reference in Lighthouse Transaction Manager and is not sent to the authorization host. Escaped quotation marks should not be sent in the Notes field.

Example: "Transaction notes are added here"

transaction.vendorReferencestring<= 50 characters

Optional field for information that can be searched in the merchant portal.

transaction.s4RiskIdstring

Unique transaction identification number generated by Shift4 to identify a specific risk transaction and a field that can be searched in LTM.

Conditional: must be sent if Risk Assessment was completed prior to processing the transaction.

cardobjectrequired

Example: {"number":"4012000098765439","expirationDate":1225,"present":"N"}

card.numberstring<= 32 charactersrequired

The payment card number entered in an initial authorization/sale request. This field will always be masked when returned in a response.

Example: "4012000098765439"

card.expirationDateinteger(MMYY)[ 3 .. 4 ] charactersrequired

Conditional: Send only when card data is manually entered or when using a token. This field should not be specified when using an encrypted device.

Card expiration date in MMYY format. This value should only be populated in the initial sale/authorization request.

Example: 1225

card.presentstring

Conditional: Send in the initial authorization/sale request

Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent.

Note: Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include card.present in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include card.present.

Enum"Y""N"

Example: "N"

card.securityCodeobject

Conditional: Send when processing a 3D Secure transaction in the US. This object should be sent for initial card on file request but is not required for subsequent merchant initiated charges.

customerobjectrequired

Example: {"firstName":"John","lastName":"Smith","addressLine1":"65 Easy St","city":"Las Vegas","postalCode":"65144","emailAddress":"firstname.lastname@email.com","ipAddress":"63.57.84.101"}

customer.firstNamestring<= 30 charactersrequired

Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option USECARDNAME is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.

Example: "John"

customer.lastNamestring<= 30 charactersrequired

Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option USECARDNAME is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the customer object, the consumer's name will be returned in the customer object if the name is present in the card's EMV or track data.

Example: "Smith"

customer.emailAddressstring<= 80 charactersrequired

Customer email address.

Example: "firstname.lastname@email.com"

customer.ipAddressstring<= 20 charactersrequired

Public source IP Address where the request originates, not the IP Address of the web server.

Example: "63.57.84.101"

customer.phoneNumberstring<= 32 characters

Customer phone number

customer.phoneCountrystring[ 1 .. 3 ] characters

Country calling code of the phone number.

Required when sending customer.phoneNumber.

customer.addressLine1string<= 30 characters

Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.