Preamble

This API enables PCI-compliant merchants to send transactions containing card data directly, without requiring them to use the payment.js tokenization or hosted payment page.

The API solely supports card transactions. For any other kind of payment method (e.g. PayPal, DirectDebit etc.) please refer to the Regular API.

If you are already familiar with the regular API, you will notice that the only change is the addition of the cardData element. Everything else behaves the same.

Getting started

Endpoint: https://secure.tillpayments.com/api/v3

Full OpenApi 3.0 Specification: https://secure.tillpayments.com/Schema/V3/OpenApiSpecificationDirectPCI.yml

Request format

Requests are sent via HTTPS containing a JSON body.

The server accepts TLS version >= 1.2 connections.
Content-Type must be application/json
Authentication credentials are sent via BASIC Auth (see below)
The request must contain a valid signature within the X-Signature header (see below)
The request must contain a valid Date header, because this value is used for signature verification (refer to RFC 7231)

To test the DirectPCI API in the Sandbox environment add following header to your request:
X-Environment: Sandbox

Headers Example:

Content-Type: application/json; charset=utf-8
Date: Mon, 01 Jan 2018 11:01:36 UTC
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
X-Signature: DH7MfiGq5QYQusTzWMpWiJpnPz+o1pZbcf7HCiT1+jjc+7UrnmDSpVuHzrRrZ6UxJUYYnOHJfG91zm0VimWXHg==

Authentication

The API username and password must be sent as BASIC Authentication in the Authorization header (refer to RFC 7617).

Username and password are concatenated by a : (colon) and the whole string is Base64 encoded.

Example:

Username is anyApiUser, password is myPassword
Concatenation is anyApiUser:myPassword
Base64 encoded: YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
The passed header will then look like this: Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==

Signature

Each request to the API must be signed with your shared secret.

The signature is generated via Hash HMAC using SHA2-512 as hashing algorithm. Afterwards the binary (not hexadecimal!) HMAC must be Base64 encoded.

The secret key for the HMAC is the shared secret of the Gateway's connector.

The message is the concatenation of the following data, separated by a single line-break without carriage-return character, i.e. \n

HTTP Method (i.e. POST)
SHA512 hash of the request's body (the JSON string) - Note: In previous versions this is MD5 instead.
Content-Type header value
Timestamp as sent in the Date header
Note: as a special case, we'd give the X-Date header precedence. Set this header in case your HTTP client doesn't allow you to override the Date header.
Request URI (e.g. /api/v3/transaction/<api-key>/debit)

Example:

API Key is: my-api-key
Shared Secret is: my-shared-secret
JSON Body is: {"merchantTransactionId":"2019-09-02-0004","amount":"9.99","currency":"EUR"}
Content-Type is: application/json; charset=utf-8
Timestamp is: Tue, 21 Jul 2020 13:15:03 UTC
Request URI is: /api/v3/transaction/my-api-key/debit

SHA512 Hash of body: efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
Concatenation result (=message):

POST
efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
application/json; charset=utf-8
Tue, 21 Jul 2020 13:15:03 UTC
/api/v3/transaction/my-api-key/debit

3. HMAC(sha512, my-shared-secret, message), Binary-mode (not HEX), Base64 encoded = nL+8FBKWx4/pahYScKs/dRYPBEWjiBalRaWKHGtxLpELmLrgJ/+dSWjt6dZNuu6oF18NyWEU8tXLEVm2mtEapg==

4. Header to be sent:

X-Signature: nL+8FBKWx4/pahYScKs/dRYPBEWjiBalRaWKHGtxLpELmLrgJ/+dSWjt6dZNuu6oF18NyWEU8tXLEVm2mtEapg==
Content-Type: application/json; charset=utf-8
Date: Tue, 21 Jul 2020 13:15:03 UTC

Signature testing tool:

Use this tool to verify the correctness of your signature generation.

Signature parameters
API-Key
Shared Secret
Method
Content
Content-Type
Timestamp (format)
Endpoint
Hashing Algorithm	SHA512 MD5 (deprecated)

Signature output
Expected -Hash of payload
Method
Content-Type
Timestamp
Request-URI
Hash HMAC Input (based on your request) Do note the line breaks!
Expected signature = data hashed using HMAC (SHA512), and the resulting binary encoded using Base64
Expected headers

TransactionWithCard - Request

Basic scheme

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "Your transaction ID",
    "customer": {
        "identification": "Customer ID",
        "billingCountry": "2-letter country code of your customer",
        "email": "email address of your customer",
        "ipAddress": "127.0.0.1"
    },
    "amount": "9.99",
    "currency": "EUR",
    "description": "Transaction Description",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "withRegister": false
}

The examples show the basic data most connector requires. Depending on the connector type more data could be necessary. Please refer to the Connector Types documentation for concrete requirements.

To see all available fields please refer to Transaction Data.

For some languages we already provide a ready-to-use client implementation on GitHub.

Debit

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "transaction-00001",
    "merchantMetaData": "my-category-1",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
    "withRegister": false,
    "transactionIndicator": "SINGLE",
    "customer": {
        "identification": "1111",
        "firstName": "John",
        "lastName": "Doe",
        "billingCountry": "AT",
        "email": "[email protected]",
        "ipAddress": "123.123.123.123"
    }
}

curl \
-d "PUT_JSON_HERE" \
-H "Authorization: Basic basicAuthHere" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Date: Tue, 21 Apr 2020 12:45:55 UTC" \
-H "X-Signature: SignatureHere" \

"https://secure.tillpayments.com/api/v3/transaction/API-KEY-HERE/debit"

A Debit performs a complete customer-to-merchant payment

The field merchantMetaData is optional and for your internal use only. It can be filled with any string you want, with a maximum length of 255 characters. The value has no influence on the transaction process at all and will be returned to you in any postback notification. It may also be included in data exports.

If you want to add different types of information, we recommend separating them by a character which would not occur in the data value itself, e.g. a pipe character "|"
Example: "anyValue1|anotherValue2"

POST /transaction/{apiKey}/debit

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Recurring Debits (and Preauthorizations)

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "transaction-00002",
    "referenceUuid": "abcde12345abcde12345",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
    "withRegister": false,
    "transactionIndicator": "RECURRING"
}

For recurring charges the initial transaction must either be a Register, or a Debit resp. Preauthorize with the withRegister flag set to true. You must store the returned referenceId and use for recurring transactions in the field referencedTransactionId

Preauthorize

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "transaction-00003",
    "merchantMetaData": "my-category-1",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
    "withRegister": false,
    "transactionIndicator": "SINGLE",
    "customer": {
        "identification": "1111",
        "firstName": "John",
        "lastName": "Doe",
        "billingCountry": "AT",
        "email": "[email protected]",
        "ipAddress": "123.123.123.123"
    }
}

A Preauthorize reserves the payment amount on the customer's payment instrument.

Depending on the payment method you have up to 7 days until you must Capture the transaction before the authorization expires.

POST /transaction/{apiKey}/preauthorize

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Capture

{
    "merchantTransactionId": "transaction-00004",
    "referenceUuid": "abcde12345abcde12345",
    "amount": "9.99",
    "currency": "EUR"
}

A Capture completes the payment which was previously authorized with the Preauthorize method.

Depending on the payment method you can even capture only a partial amount of the authorized amount.

POST /transaction/{apiKey}/capture

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Void

{
    "merchantTransactionId": "transaction-00005",
    "referenceUuid": "abcde12345abcde12345"
}

A Void cancels a previously performed authorization made with the Preauthorize method.

POST /transaction/{apiKey}/void

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Refund

{
    "merchantTransactionId": "transaction-00008",
    "referenceUuid": "abcde12345abcde12345",
    "amount": "5.99",
    "currency": "EUR"
}

A Refund reverses a payment which was previously performed with Debit or Capture.

Depending on the payment method you can even refund only a partial amount of the original transaction amount.

POST /transaction/{apiKey}/refund

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Payout

{
    "merchantTransactionId": "transaction-00009",
    "referenceUuid": "abcde12345abcde12345",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
    "customer": {
        "identification": "1111",
        "firstName": "John",
        "lastName": "Doe",
        "billingCountry": "AT",
        "email": "[email protected]",
        "ipAddress": "123.123.123.123"
    }
}

A Payout credits the customer's account with the given amount.

Depending on the connector, either referenceUuid or cardData will be required.

POST /transaction/{apiKey}/payout

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Register

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "transaction-00006",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
    "customer": {
        "identification": "1111",
        "firstName": "John",
        "lastName": "Doe",
        "billingCountry": "AT",
        "email": "[email protected]",
        "ipAddress": "123.123.123.123"
    }
}

Registers a customer's payment instrument for future charges (Debits or Preauthorizations)

POST /transaction/{apiKey}/register

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Deregister

{
    "merchantTransactionId": "transaction-00007",
    "referenceUuid": "abcde12345abcde12345"
}

A Deregister deletes a previously registered payment instrument using Register.

POST /transaction/{apiKey}/deregister

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Incremental Authorization

{
    "cardData": {
        "cardHolder": "John Doe",
        "pan": "4111111111111111",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2021"
    },
    "merchantTransactionId": "transaction-00003",
    "referenceUuid": "bcdef23456bcdef23456"
    "merchantMetaData": "my-category-1",
    "amount": "9.99",
    "currency": "EUR",
    "successUrl": "https://link.to/your/payment-successful-page",
    "cancelUrl": "https://link.to/your/payment-canceled-page",
    "errorUrl": "https://link.to/your/payment-failed-page",
    "callbackUrl": "https://link.to/your/notification-handler",
    "description": "Transaction Description",
}

An incremental authorization increases the authorized amount on the customer's payment instrument.

Currently the incremental authorization is only supported by a few adapters.

A following capture transaction may capture the full amount of the initial transaction and all its subsequent incremental authorizations.

Note: The capture transaction must refer to the initial preauthorize!

POST /transaction/{apiKey}/incrementalAuthorization

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Transaction Response

As response to the API call the gateway answers with a Result JSON with the status and further instructions.

Generally there are 4 possible results:

FINISHED

{
    "success": true,
    "uuid": "abcde12345abcde12345",
    "purchaseId": "20190927-abcde12345abcde12345",
    "returnType": "FINISHED",
    "paymentMethod": "Creditcard",
    "returnData": {
        "type": "visa",
        "cardHolder": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2021",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
        "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
        "_TYPE": "creditcardData"
    }
}

The transaction completed and was processed successfully. You can deliver the ordered goods.

Recurring Transaction
If you flagged the transaction as withRegister or if the transaction was a Register, you will use the uuid for recurring charges in the field referenceUuid.

ERROR

{
    "success": false,
    "uuid": "abcde12345abcde12345",
    "purchaseId": "20190927-abcde12345abcde12345",
    "returnType": "ERROR",
    "paymentMethod": "Creditcard",
    "returnData": {
        "type": "visa",
        "cardHolder": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2022",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
        "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
        "_TYPE": "creditcardData"
    },
    "errors": [
        {
            "errorMessage": "The transaction was declined",
            "errorCode": 2003,
            "adapterMessage": "Transaction declined",
            "adapterCode": "transaction_declined"
        }
    ]
}

The transaction failed or was declined. See the error code and message for further details.

You will find the native error message and code from the payment provider/acquiring bank in the fields adapterMessage and adapterCode.

Merchant Advice Code
When supported by an adapter implementation, a merchant advice code can be returned with the ReturnData. This code is piped through as received by the gateway.
If a merchant advice code indicating a hard "do not retry" is returned, the value "doNotResubmit": true will additionally be returned with the error response extra data.

REDIRECT

{
    "success": true,
    "uuid": "abcde12345abcde12345",
    "purchaseId": "20190927-abcde12345abcde12345",
    "returnType": "REDIRECT",
    "redirectUrl": "https://secure.tillpayments.com/redirect/12345678901234567890/ABCDEF01234567890ABCDEF01234567890=",
    "paymentMethod": "Creditcard"
}

You must redirect the user to the URL defined in redirectUrl to proceed with the transaction. Afterwards the user will be back redirected to your shop (one of the URLs you defined in the API call in successUrl, cancelUrl or errorUrl). In parallel the gateway sends a status notification to you callbackUrl with the final result.

PENDING

{
    "success": true,
    "uuid": "abcde12345abcde12345",
    "purchaseId": "20190927-abcde12345abcde12345",
    "returnType": "PENDING",
    "paymentMethod": "Creditcard",
    "returnData": {
        "type": "visa",
        "cardHolder": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2022",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "merchantFingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
        "globalFingerprint": "bSDn7SmA3Wr/o7Pzh4TaEw6RHc6rwqKxNFW8opklNbP7irUxv57avJPKveRO48fGhKY0oJYWUAfMcJq9+iSUmw",
        "_TYPE": "creditcardData"
    }
}

The transaction was accepted for processing, but is not yet completed. You will receive a status notification to the URL you defined in callbackUrl once it reaches a final state.

Depending on the payment method, this can take from seconds up to several days.

Transaction Data

cardData

The main difference between the regular Transaction API and the Direct PCI API is additional cardData element which has following fields:

Name	Type	Required	Description
cardHolder	string	yes	First- and last name
pan	string	yes	Credit card number
cvv	string	no	Credit card CVV/CVC
expirationMonth	string	yes	Credit card expiry month
expirationYear	string	yes	Credit card expiry year

Customer

{
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false, 
    "ipAddress": "127.0.0.1",   
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    }
  }
}

Name	Type	Required	Description
identification	string	false	max. 36 characters
firstName	string	false	max. 50 characters
lastName	string	false	max. 50 characters
birthDate	string	false	`YYYY-MM-DD`
gender	string	false	`M`, `F`
billingAddress1	string	false	max. 50 characters
billingAddress2	string	false	max. 50 characters
billingCity	string	false	max. 50 characters
billingPostcode	string	false	max. 16 characters
billingState	string	false	max. 30 characters
billingCountry	string	false	2-letter country code
billingPhone	string	false	max. 20 characters
shippingFirstName	string	false	max. 50 characters
shippingLastName	string	false	max. 50 characters
shippingCompany	string	false	max. 50 characters
shippingAddress1	string	false	max. 50 characters
shippingAddress2	string	false	max. 50 characters
shippingCity	string	false	max. 50 characters
shippingPostcode	string	false	max. 16 characters
shippingState	string	false	max. 30 characters
shippingCountry	string	false	2-letter country code
shippingPhone	string	false	max. 20 characters
company	string	false	max. 50 characters
email	string	false	valid e-mail
emailVerified	boolean	false
ipAddress	string	false
nationalId	string	false	max. 14 characters
extraData	object	false	object containing `key-value` pairs (string-to-string)
paymentData	object	false	one of PaymentData

CustomerProfileData

Name	Type	Required	Description
profileGuid	string	conditional
customerIdentification	string	conditional
markAsPreferred	boolean	false	mark payment instrument as preferred

Item

Name	Type	Required	Description
identification	string	false
name	string	false
description	string	false
quantity	number	false
price	number	false
currency	string	false	3 letter currency code
extraData	object	false	object containing `key-value` pairs (string-to-string)

PaymentData

ReturnData

cardData

{
  "_TYPE": "cardData",
  "type": "visa",
  "cardHolder": "John Doe",
  "expiryMonth": 12,
  "expiryYear": 2020,
  "binDigits": "12345678",
  "firstSixDigits": "123456",
  "lastFourDigits": "4321",
  "fingerprint": "s0mEF1n6eRpr1n7",
  "threeDSecure": "OFF",
  "binBrand": "VISA",
  "binBank": "SOME BANK",
  "binCountry": "US"
}

Name	Type	Description
_TYPE	string	will contain value `cardData`
type	string	type of credit card
firstName	string
lastName	string
country	string
cardHolder	string
expiryMonth	number	`MM`
expiryYear	number	`YYYY`
binDigits	string
firstSixDigits	string
lastFourDigits	string
fingerprint	string
binBrand	string
binBank	string
binType	string
binLevel	string
binCountry	string
threeDSecure	string
eci	string
merchantAdviceCode	string	pipes through the merchant advice code for failed transactions if supported by the adapter

RiskCheckData

Name	Type	Description
riskCheckResult	string	`APPROVED`, `DECLINED`, `REVIEW`
riskScore	number
threeDSecureRequired	boolean

Schedule

Name	Type	Required	Description
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
periodLength	number	true
periodUnit	string	true	`DAY`, `WEEK`, `MONTH`, `YEAR`
startDateTime	string	false	RFC8601 Date/Time `YYYY-MM-DD\THH:MM:SS+00:00`

ScheduleData

Name	Type	Description
scheduleId	string	ID of schedule which was started with the transaction
scheduleStatus	string	status of schedule
scheduledAt	string	scheduled date and time

TransactionError

Name	Type
message	string
code	number
adapterMessage	string
adapterCode	string

TransactionResponseError

Name	Type
errorMessage	string
errorCode	number
adapterMessage	string
adapterCode	string

3D-Secure 2.0 data

As explained in 3D Secure 2.0 Authentication you should provide as many data as you have to apply for the 3D Secure 2.0 frictionless flow.

ThreeDSecureData

{
  ...
  "threeDSecureData": {
    "3dsecure": "MANDATORY",
    "channel" => "01",
    "authenticationIndicator" => "01" ,
    "cardholderAuthenticationMethod" => "01" ,
    "cardholderAuthenticationDateTime" => "2020-01-01 12:00",
    ... 
  }
}

Name	Type	Required	Accepted values
`3dsecure` Triggers the 3D Secure authentication for this transaction	string	false	`OFF`, `OPTIONAL`, `MANDATORY`
`channel` Indicates the type of channel interface being used to initiate the transaction 01 -> App-based 02 -> Browser 03 -> 3DS Requestor Initiated	string	false	`01`, `02`, `03`
`schemeId` "Pin" the scheme ID in case of a co-branded card. Currently, there is only CB supported.	string	false	`CB`
`authenticationIndicator` 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. 01 -> Payment transaction 02 -> Recurring transaction 03 -> Installment transaction 04 -> Add card 05 -> Maintain card 06 -> Cardholder verification as part of EMV token ID&V	string	false	`01`, `02`, `03`
`cardholderAuthenticationMethod` Mechanism used by the Cardholder to authenticate to the 3DS Requestor. 01 -> No 3DS Requestor authentication occurred (i.e. cardholder "logged in" as guest) 02 -> Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials 03 -> Login to the cardholder account at the 3DS Requestor system using federated ID 04 -> Login to the cardholder account at the 3DS Requestor system using issuer credentials 05 -> Login to the cardholder account at the 3DS Requestor system using third-party authentication 06 -> Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator	string	false	`01`, `02`, `03`, `04`, `05`, `06`
`cardholderAuthenticationDateTime` Date and time in UTC of the cardholder authentication. Format: YYYY-MM-DD HH:mm Example: 2019-05-12 18:34	string	false	`YYYY-MM-DD HH:MM`
`cardHolderAuthenticationData` Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process.	string	false
`challengeIndicator` Indicates whether a challenge is requested for this transaction. For example: For 01-PA, a 3DS Requestor may have concerns about the transaction, and request a challenge. 01 -> No preference 02 -> No challenge requested 03 -> Challenge requested: 3DS Requestor Preference 04 -> Challenge requested: Mandate 05 -> No challenge requested (transactional risk analysis is already performed) 06 -> No challenge requested (Data share only) 07 -> No challenge requested (strong consumer authentication is already performed) 08 -> No challenge requested (utilise whitelist exemption if no challenge required) 09 -> Challenge requested (whitelist prompt requested if challenge required)	string	false	`01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`
`priorReference` This data element provides additional information to the ACS to determine the best approach for handling a request. The field is limited to 36 characters containing ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).	string	false
`priorAuthenticationMethod` Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. 01 -> Frictionless authentication occurred by ACS 02 -> Cardholder challenge occurred by ACS 03 -> AVS verified 04 -> Other issuer methods	string	false	`01`, `02`, `03`, `04`
`priorAuthenticationDateTime` Date and time in UTC of the prior authentication. Format: YYYY-MM-DD HH:mm Example: 2019-05-12 18:34	string	false	`YYYY-MM-DD HH:MM`
`priorAuthenticationData` Data that documents and supports a specfic authentication porcess. In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versionsof the application, these details are expected to be included. Field is limited to maximum 2048 characters.	string	false
`cardholderAccountType` Indicates the type of account. For example, for a multi-account card product. 01 -> Not applicable 02 -> Credit 03 -> Debit 04 -> JCB specific value for Prepaid	string	false	`01`, `02`, `03`, `04`
`cardholderAccountAgeIndicator` Length of time that the cardholder has had the account with the 3DS Requestor. 01 -> No account (guest check-out) 02 -> During this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days	string	false	`01`, `02`, `03`, `04`, `05`
`cardholderAccountDate` Date that the cardholder opened the account with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12	string	false	`YYYY-MM-DD`
`cardholderAccountChangeIndicator` Length of time since the cardholder’s account information with the 3DS Requestor waslast changed. Includes Billing or Shipping address, new payment account, or new user(s) added. 01 -> Changed during this transaction 02 -> Less than 30 days 03 -> 30 - 60 days 04 -> More than 60 days	string	false	`01`, `02`, `03`, `04`
`cardholderAccountLastChange` Date that the cardholder’s account with the 3DS Requestor was last changed. Including Billing or Shipping address, new payment account, or new user(s) added. Format: YYYY-MM-DD Example: 2019-05-12	string	false	`YYYY-MM-DD`
`cardholderAccountPasswordChangeIndicator` Length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. 01 -> No change 02 -> Changed during this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days	string	false	`01`, `02`, `03`, `04`, `05`
`cardholderAccountLastPasswordChange` Date that cardholder’s account with the 3DS Requestor had a password change or account reset. Format: YYYY-MM-DD Example: 2019-05-12	string	false	`YYYY-MM-DD`
`shippingAddressUsageIndicator` Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 01 -> This transaction 02 -> Less than 30 days 03 -> 30 - 60 days 04 -> More than 60 days.	string	false	`01`, `02`, `03`, `04`
`shippingAddressFirstUsage` Date when the shipping address used for this transaction was first used with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12	string	false	`YYYY-MM-DD`
`transactionActivityDay` Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.	number	false
`transactionActivityYear` Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.	number	false
`addCardAttemptsDay` Number of Add Card attempts in the last 24 hours.	number	false
`purchaseCountSixMonths` Number of purchases with this cardholder account during the previous six month	number	false
`suspiciousAccountActivityIndicator` Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. 01 -> No suspicious activity has been observed 02 -> Suspicious activity has been observed	string	false	`01`, `02`
`shippingNameEqualIndicator` Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 01 -> Account Name identical to shipping Name 02 -> Account Name different than shipping Name	string	false	`01`, `02`
`paymentAccountAgeIndicator` Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. 01 -> No account (guest check-out) 02 -> During this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days	string	false	`01`, `02`, `03`, `04`, `05`
`paymentAccountAgeDate` Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12	string	false	`YYYY-MM-DD`
`billingAddressLine3` Line 3 of customer's billing address	string	false
`shippingAddressLine3` Line 3 of customer's shipping address	string	false
`billingShippingAddressMatch` Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same. Y -> Shipping Address matches Billing Address N -> Shipping Address does not match Billing Address	string	false	`Y`, `N`
`homePhoneCountryPrefix` Country Code of the home phone, limited to 1-3 characters	string	false
`homePhoneNumber` subscriber section of the number, limited to maximum 15 characters.	string	false
`mobilePhoneCountryPrefix` Country Code of the mobile phone, limited to 1-3 characters	string	false
`mobilePhoneNumber` subscriber section of the number, limited to maximum 15 characters.	string	false
`workPhoneCountryPrefix` Country Code of the work phone, limited to 1-3 characters	string	false
`workPhoneNumber` subscriber section of the number, limited to maximum 15 characters.	string	false
`purchaseInstalData` Indicates the maximum number of authorisations permitted for instalment payments. The field is limited to maximum 3 characters and value shall be greater than 1. The fields is required if the Merchant and Cardholder have agreed to installment payments, i.e. if 3DS Requestor Authentication Indicator = 03. Omitted if not an installment payment authentication.	number	false
`shipIndicator` Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the code that describes the most expensive item. 01 -> Ship to cardholder's billing address 02 -> Ship to another verified address on file with merchant 03 -> Ship to address that is different than the cardholder's billing address 04 -> "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields) 05 -> Digital goods (includes online services, electronic gift cards and redemption codes) 06 -> Travel and Event tickets, not shipped 07 -> Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)	string	false	`01`, `02`, `03`, `04`, `05`, `06`, `07`
`deliveryTimeframe` Indicates the merchandise delivery timeframe. 01 -> Electronic Delivery 02 -> Same day shipping 03 -> Overnight shipping 04 -> Two-day or more shipping	string	false	`01`, `02`, `03`, `04`
`deliveryEmailAddress` For electronic delivery, the email address to which the merchandise was delivered.	string	false
`reorderItemsIndicator` Indicates whether the cardholder is reoreding previously purchased merchandise. 01 -> First time ordered 02 -> Reordered	string	false	`01`, `02`
`preOrderPurchaseIndicator` Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. 01 -> Merchandise available 02 -> Future availability	string	false	`01`, `02`
`preOrderDate` For a pre-ordered purchase, the expected date that the merchandise will be available. Format: YYYY-MM-DD	string	false	`YYYY-MM-DD`
`giftCardAmount` For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).	number	false
`giftCardCurrency` For prepaid or gift card purchase, the currency code of the card	string	false
`giftCardCount` For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. Field is limited to 2 characters.	number	false
`purchaseDate` Date and time of the purchase, expressed in UTC. Format: YYYY-MM-DD HH:mm:ss **Note: if omitted we put in today's date	string	false	`YYYY-MM-DD HH:MM`
`recurringExpiry` Date after which no further authorizations shall be performed. This field is required for 01-PA and for 02-NPA, if 3DS Requestor Authentication Indicator = 02 or 03. Format: YYYY-MM-DD	string	false	`YYYY-MM-DD`
`recurringFrequency` Indicates the minimum number of days between authorizations. The field is limited to maximum 4 characters. This field is required if 3DS Requestor Authentication Indicator = 02 or 03.	number	false
`transType` Identifies the type of transaction being authenticated. The values are derived from ISO 8583. 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan	string	false	`01`, `03`, `10`, `11`, `28`
`threeRIIndicator` Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handling a 3RI request. Possible values are: 01 -> Recurring transaction 02 -> Installment transaction 03 -> Add card 04 -> Maintain card information 05 -> Account verification. 06 -> Split/delayed shipment 07 -> Top-up 08 -> Mail order 09 -> Telephone order 10 -> Whitelist status check 11 -> Other payment 12 -> Billing agreement.	string	false	`01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`
`exemptionIndicator` Requests an SCA exemption for this transaction. Possible values are: 01 -> Low Value Transaction (amount under 30 EUR) 02 -> Low Risk Transaction 03 -> Whitelisted transaction, merchant is added as "Trusted Beneficiary" by cardholder 04 -> Secure Corporate Payment 05 -> Recurring or Merchant-initiated transaction 06 -> Mail or Telephone Order 07 -> Anonymous payment card	string	false	`01`, `02`, `03`, `04`, `05`, `06`, `07`

3D-Secure 2.0 device data

For 3DS v2, the device data below are mandatory. Transaction will not succeed if either all browser or all SDK parameters are provided.

Browser data

{
  ...
  "threeDSecureData": {
    ...
    "browserChallengeWindowSize" => "04"
    "browserAcceptHeader" => "*/*",
    "browserIpAddress" => "127.0.0.1",
    "browserJavaEnabled" => false,
    "browserLanguage" => "en-GB",
    "browserColorDepth" => "24",
    "browserScreenHeight" => 1080,
    "browserScreenWidth" => 1920,
    "browserTimezone" => -60,
    "browserUserAgent" => "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.21 Safari/537.12",
    ...
  }
}

The following fields are filled automatically by the Gateway if you are using hosted payment pages or payment.js integration. For any other integration flow you will need to provide them:

Name	Type	Accepted values
`browserChallengeWindowSize` 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. 01 -> 250 x 400 02 -> 390 x 400 03 -> 500 x 600 04 -> 600 x 400 05 -> Full screen	string	`01`, `02`, `03`, `04`, `05`
`browserAcceptHeader` Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser	string
`browserIpAddress` IP address of the browser as returned by the HTTP headers to the 3DS Requestor. - 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	string
`browserJavaEnabled` Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.	boolean
`browserLanguage` 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.	string
`browserColorDepth` 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. 1 -> 1 bit 4 -> 4 bits 8 -> 8 bits 15 -> 15 bits 16 -> 16 bits 24 -> 24 bits 32 -> 32 bits 48 -> 48 bits	string	`1`, `4`, `8`, `15`, `16`, `24`, `32`, `48`
`browserScreenHeight` Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.	number
`browserScreenWidth` Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.	number
`browserTimezone` Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method.	number
`browserUserAgent` Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters.	string

SDK data

Name	Type	Accepted values
`sdkInterface` Specifies all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values are: 01 -> Native 02 -> HTML 03 -> Both	string	`01`, `02`, `03`
`sdkUiType` Contains a comma-separated list of all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values for each UI type are: 01 -> Text 02 -> Single select 03 -> Multi select 04 -> OOB 05 -> Html Other (valid only for HTML UI) E.g. `01,02,05`	string	comma-separated list with values: `01`, `02`, `03`, `04`, `05`
`sdkAppID` Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Customer Device.	string
`sdkEncData` JWE Object as defined 3DS Specs Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt.	string
`sdkEphemPubKey` Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS The value should be a JSON string containing the keys `kty`, `crv`, `x`, `y`, e.g. `{"kty":"EC","crv":"P-256","x":"...","y":"..."}`	string
`sdkMaxTimeout` Indicates the maximum amount of time (in minutes) for all exchanges. The field shall have value greater than or equal to 05.	number
`sdkReferenceNumber` Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo whenthe 3DS SDK is approved. The field is limited to 32 characters.	string
`sdkTransID` Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.	string

Risk data

Forter External Risk Check additional extra data

Those extra data fields are mapped to the corresponding Forter Validation Request Parameters: https://portal.forter.com/app/developer/api/api/services-and-apis/validation-api#request

Customer Extra Data

{
  "customer": {
    "identification": "c0001",
    /*...*/
    "extraData": {
      "FORTER_CUSTOMER_LAST_LOGINIP": "203.12.55.12",
      "FORTER_CUSTOMER_BILLING_ADDRESS_TYPE": "HOME"
      /*...*/
    }
  }
}

Name	Type	Example values
`FORTER_CUSTOMER_PAST_ORDERS_COUNT`	optional integer	0
`FORTER_CUSTOMER_PAST_ORDERS_SUM_USD`	optional decmimal	0.00
`FORTER_CUSTOMER_LAST_LOGINIP`	string	203.12.55.12
`FORTER_CUSTOMER_REGISTRATION_IP`	string	203.12.55.12
`FORTER_CUSTOMER_BILLING_ADDRESS_TYPE` conditional Possible values are: "HOME", "BUSINESS", "OTHER"	string	HOME
`FORTER_CUSTOMER_BILLING_CREATION_TIME` conditional Time item was first entered by customer in seconds since unix epoch (UTC, Jan 1, 1970)	number	1448549922
`FORTER_CUSTOMER_BILLING_REMOVAL_TIME` conditional Time item was removed by customer in seconds since unix epoch (UTC, Jan 1, 1970)	number	1448895522
`FORTER_CUSTOMER_BILLING_SUGGESTED_CORRECT_ADDRESS` conditional True if customer selected a corrected address suggested by merchant (For example in cases where customer entered wrong zipcode)	boolean	0/1
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_TYPE` required ype of document (Passport, ID, Driving license) Maximum length is 35 characters.	string	Passport
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_SOURCE` required Source of document (e.g. uploaded file, captured by camera, typed in by customer, etc.) Possible values are: "CAMERA_CAPTURED", "UPLOADED_FILE", "TYPED", "OTHER"	string	UPLOADED_FILE
`FORTER_CUSTOMER_BILLING_VERIFICATION_NATIONALITY` conditional Document holder's nationality	string	US
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_ISSUING_STATE` conditional Document issuing state or region	string	NY
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_NUMBER` conditional Official document's number (e.g. passport number, driving license number, etc.)	string	20439190
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_FIRSTNAME` conditional First name as appears on the document	string	John
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_LASTNAME` conditional Last name as appears on the document	string	Smith
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_DATEOFBIRTH` conditional Date of birth as appears on the document. Use YYYY-MM-DD format.	string	1982-04-23
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_EXPIRATION` conditional Document's exipration date. Use YYYY-MM-DD format.	string	2025-04-23
`FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_PAYLOAD` conditional JSON Response payload received from 3rd party document verification	string JSON	{}
`FORTER_CUSTOMER_SHIPPING_ADDRESS_TYPE` conditional Possible values are: "HOME", "BUSINESS", "OTHER"	string	HOME
`FORTER_CUSTOMER_SHIPPING_CREATION_TIME` conditional Time item was first entered by customer in seconds since unix epoch (UTC, Jan 1, 1970)	number	1448549922
`FORTER_CUSTOMER_SHIPPING_REMOVAL_TIME` conditional Time item was removed by customer in seconds since unix epoch (UTC, Jan 1, 1970)	number	1448895522
`FORTER_CUSTOMER_SHIPPING_SUGGESTED_CORRECT_ADDRESS` conditional True if customer selected a corrected address suggested by merchant (For example in cases where customer entered wrong zipcode)	boolean	0/1
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_TYPE` required ype of document (Passport, ID, Driving license) Maximum length is 35 characters.	string	Passport
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_SOURCE` required Source of document (e.g. uploaded file, captured by camera, typed in by customer, etc.) Possible values are: "CAMERA_CAPTURED", "UPLOADED_FILE", "TYPED", "OTHER"	string	UPLOADED_FILE
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_NATIONALITY` conditional Document holder's nationality	string	US
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_ISSUING_STATE` conditional Document issuing state or region	string	NY
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_NUMBER` conditional Official document's number (e.g. passport number, driving license number, etc.)	string	20439190
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_FIRSTNAME` conditional First name as appears on the document	string	John
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_LASTNAME` conditional Last name as appears on the document	string	Smith
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_DATEOFBIRTH` conditional Date of birth as appears on the document. Use YYYY-MM-DD format.	string	1982-04-23
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_EXPIRATION` conditional Document's exipration date. Use YYYY-MM-DD format.	string	2025-04-23
`FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_PAYLOAD` conditional JSON Response payload received from 3rd party document verification	string JSON	{}

Transaction Extra Data

Name	Type	Example values
`FORTER_TYPE` optional, default WEB. Platform order was made through. Possible Values: "WEB", "PHONE", "MOBILE", "IOS", "ANDROID", "WAP", "STORE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "UNKNOWN"	string	WEB
`FORTER_TOKEN` conditional Forter token cookie from request headers. Maximum length is 128 characters.	string	2315688945984
`FORTER_USER_AGENT` required when PaymentJS is not used, Customer's User agent. Maximum length is 4096 characters.	string	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36
`FORTER_CHECKOUT_TIME` optional will use current timestamp if not provided. The time when the buyer completed the checkout process in the merchant website in SECONDS since unix epoch (Jan 1, 1970).	number	1415273168
`FORTER_MOBILE_UID` optional - mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API (for mobile transactions only) Maximum length is 128 characters.	string	6429751237891
`FORTER_MERCHANT_DEVICE_IDENTIFIER` conditional - A unique device identifier generated by merchant	string	HGJ7512345H3
`FORTER_MOBILE_APP_VERSION` conditional - The version of the merchant application which is running on the user's device	string	2.9
`FORTER_MOBILE_OS_TYPE` conditional - The operating system running on the user's device (relevant for native app only)	string	Android
`FORTER_MOBILE_DEVICE_BRAND` conditional - The user's device brand (relevant for native app only)	string	Samsung
`FORTER_MOBILE_DEVICE_MODEL` conditional - The model of the user's device (relevant for native app only)	string	Galaxy 3
`FORTER_FULL_HEADERS_JSON` conditional - A unique device identifier generated by merchant	string JSON	"{"method":"GET / HTTP/1.1", "Host": "forter.com", "Connection": "keep-alive", "Accept": ...}"
`FORTER_DELIVERY_DETAILS_DELIVERY_TYPE` optional default PHYSICAL - Type of delivery: PHYSICAL for any type of shipped goods. DIGITAL for non-shipped goods (services, gift cards etc.) Example: PHYSICAL Possible values are: "DIGITAL", "PHYSICAL", "HYBRID"	string	DIGITAL
`FORTER_DELIVERY_DETAILS_DELIVERY_METHOD` optional default POSTAL SERVICE - Delivery method chosen by customer such as postal service, email, in game transfer, etc. Example: USPS - Ground Mail	string	Galaxy
`FORTER_DELIVERY_DETAILS_DELAYED_DELIVERY_DATE` conditional - Use if customer chose to deliver the item at a later date (to arrive in time for a holiday, a birthday, etc.). Use YYYY-MM-DD format.	string	2018-10-12
`FORTER_DELIVERY_DETAILS_CARRIER` optional - The delivery carrier	string	DHL
`FORTER_DELIVERY_DETAILS_DELIVERY_PRICE_AMOUNT` conditional - same currency as transaction currency is assumed	string	5.00
`FORTER_DELIVERY_DETAILS_TRACKING_EXTRA_CHARGE_AMOUNT` conditional - same currency as transaction currency is assumed	string	1.00
`FORTER_DELIVERY_DETAILS_EXPECTED_DELIVERY_DATE` conditional - Date delivery is expected to arrive at destination. Use YYYY-MM-DD	string	2018-10-14
`FORTER_DELIVERY_DETAILS_LEAVE_OUTSIDE` optional - 1 if customer chose to allow shipment to be left outside or at a building lobby or reception area.	integer	1
`FORTER_DELIVERY_DETAILS_SMS_UPDATES` optional - 1 if customer asked to receive SMS updates regarding delivery.	integer	0
`FORTER_DELIVERY_DETAILS_WAIT_TO_SHIP_TOGETHER` conditional - 1 if customer asked to try and bundle shipments together to save costs.	integer	1
`FORTER_DELIVERY_DETAILS_DELIVERY_COMMENTS` conditional - Any comments or requests customer had for delivery	string	Please call before arriving, Thanks!
`FORTER_IS_MERCHANT_OF_RECORD` conditional - 1 if the Forter account owner is also the merchant of record	string	1
`FORTER_PAYMENT_METHOD_NICKNAME` conditional - Nickname assigned to this payment method by the user	string	My Work Card
`FORTER_PAYMENT_CREDIT_USED_AMOUNT` conditional - Store credit used to pay for purchase	string	1.00
`FORTER_IS_DEFAULT_PAYMENT_METHOD` conditional - 1 if this payment instrument is the default set by the customer.	integer	0
`FORTER_NUMBER_OF_INSTALLMENTS` conditional - Number of payments if customer chose to pay in several installments. integer	string	12
`FORTER_DELAYED_CHARGE` conditional - 1 if customer chose to pay at a later date. False if customer chose to pay in several installments as long as first payment is immediate.	integer	0
`FORTER_DELAYED_CHARGE_DATE` conditional - Date customer is due to pay. Use YYYY-MM-DD format.	string	2015-12-01
`FORTER_PAYMENT_GATEWAY_ID` conditional - Transaction identifier provided by the payment gateway	string	SDS34653246346
`FORTER_MERCHANT_ID` conditional - Merchant unique identifier	string	eh629dK9
`FORTER_MERCHANT_DOMAIN` conditional - Use if merchant operates several sites (such as a regular site and a related discount brand)	string	HandbagsExpressDiscounts.com
`FORTER_MERCHANT_NAME` conditional - Use if merchant operates several sites (such as a regular site and a related discount brand)	string	Handbags Express Discounts
`FORTER_SITE_LOCALIZATION_COUNTRY` conditional - Use if site has multiple localized versions	string	FR
`FORTER_SITE_LOCALIZATION_LANGUAGE` conditional - Site interface language chosen by customer, 2-letter ISO-639-1 language code	string	EN
`FORTER_SITE_LOCALIZATION_CURRENCY` conditional - Currency chosen by customer as default, 3-letter ISO-4217 format currency code	string	USD
`FORTER_ITEM_DEFAULT_QUANTITY` optional defaults to 1	integer	1
`FORTER_ITEM_DEFAULT_TYPE` optional default to TANGIBLE - Tangible if physical item, non-tangible if any other product Example: TANGIBLE Possible values are: "TANGIBLE", "NON_TANGIBLE"	string	NON_TANGIBLE
`FORTER_ITEM_DEFAULT_CREATED_TIME` conditional - Time item was added to cart by customer in seconds since unix epoch (UTC, Jan 1, 1970)	number	1415273168
`FORTER_ITEM_DEFAULT_SPECIFIC_DATA_JSON` conditional - JSON with the format described here: https://portal.forter.com/app/developer/api/api/data-objects/ItemSpecificData	string JSON	{"personalCustomization":false, ....}

Transaction Item Extra Data besides the standard item data

Name	Type	Example values
`FORTER_ITEM_TYPE` optional default to TANGIBLE - Tangible if physical item, non-tangible if any other product Example: TANGIBLE Possible values are: "TANGIBLE", "NON_TANGIBLE"	string	NON_TANGIBLE
`FORTER_ITEM_PRODUCTID` Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)	string	324234
`FORTER_ITEM_PRODUCTID_TYPE` optional - Type of product ID used (SKU/ISBN/UPC/etc.)	string	SKU
`FORTER_ITEM_CATEGORY` optional - The item category	string	Item Category
`FORTER_ITEM_COUPON_CODE_USED` optional - The coupon code used	string	FATHERSDAY2015
`FORTER_ITEM_DISCOUNT_TYPE` optional - Discount type	string	COUPON
`FORTER_ITEM_SPECIFIC_DATA_JSON` conditional - JSON with the format described here: https://portal.forter.com/app/developer/api/api/data-objects/ItemSpecificData	string JSON	{"personalCustomization":false, ....}
`FORTER_ITEM_CREATED_TIME` conditional - Time item was created in seconds since unix epoch (UTC, Jan 1, 1970)	string	1448549922

Asynchronous Status Notification

The Gateway sends you an asynchronous notification once a transaction reaches a final state. This notification should be your source of trust when dealing with asynchronous transactions involving a redirect of the customer.

Depending on the payment method this can either happen immediately or can take up to several days.

Also for any follow-up transactions, such as Chargebacks and Chargeback Reversals, you will receive a notification.

Success Notification

{
    "result": "OK",
    "uuid": "abcde12345abcde12345",
    "merchantTransactionId": "2019-09-02-0007",
    "purchaseId": "20190927-abcde12345abcde12345",
    "transactionType": "DEBIT",
    "paymentMethod": "DirectDebit",
    "amount": "9.99",
    "currency": "EUR",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "emailVerified": "false"
    },
    "returnData": {
        "_TYPE": "cardData",
        "type": "visa",
        "cardHolder": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2022",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "fingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
        "threeDSecure": "OFF",
        "binBrand": "VISA",
        "binBank": "JPMORGAN CHASE BANK N.A.",
        "binType": "",
        "binLevel": "",
        "binCountry": "US"
    }
}

When a transaction has reached the final state and is successful, the result field will contain the value OK. You may then assume that the transaction has been successfully processed.

Error Notification

{
    "result": "ERROR",
    "message": "STOLEN_CARD",
    "code": "2016",
    "adapterMessage": "Transaction was rejected",
    "adapterCode": "1234",
    "uuid": "abcde12345abcde12345",
    "merchantTransactionId": "2019-09-02-0008",
    "purchaseId": "20190927-abcde12345abcde12345",
    "transactionType": "DEBIT",
    "paymentMethod": "DirectDebit",
    "amount": "9.99",
    "currency": "EUR",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "emailVerified": "false"
    },
    "returnData": {
        "_TYPE": "cardData",
        "type": "visa",
        "cardHolder": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2022",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "fingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
        "threeDSecure": "OFF",
        "binBrand": "VISA",
        "binBank": "JPMORGAN CHASE BANK N.A.",
        "binType": "",
        "binLevel": "",
        "binCountry": "US"
    }
}

If a transaction fails, the result field will contain the value ERROR. Depending on the type of error, you may either find useful information in the message and code fields, or in adapterMessage and adapterCode fields which contain the errors returned by the respective adapter.

Chargeback Notification

{
    "result": "OK",
    "uuid": "abcde12345abcde12345",
    "merchantTransactionId": "auto-2019-09-02-0010",
    "purchaseId": "20190927-abcde12345abcde12345",
    "transactionType": "CHARGEBACK",
    "paymentMethod": "Creditcard",
    "amount": 9.99,
    "currency": "EUR",
    "chargebackData": {
        "originalUuid": "0r1gIN4luU1D",
        "originalMerchantTransactionId": "2019-09-02-0009",
        "amount": 9.99,
        "currency": "EUR",
        "reason": "Unauthorized payment",
        "chargebackDateTime": "2019-10-10T15:06:47Z"
    }
}

When a Chargeback comes in, you may find relevant chargeback information in ChargebackData

Chargeback Reversal Notification

{
    "result": "OK",
    "uuid": "abcde12345abcde12345",
    "merchantTransactionId": "auto-2019-09-02-0012",
    "purchaseId": "20191210-abcde12345abcde12345",
    "transactionType": "CHARGEBACK-REVERSAL",
    "paymentMethod": "Creditcard",
    "amount": "9.99",
    "currency": "EUR",
    "chargebackReversalData": {
        "originalUuid": "0r1gIN4luU1D",
        "originalMerchantTransactionId": "2019-09-02-0011",
        "chargebackUuid": "Ch4rG3baCkUu1D",
        "amount": "9.99",
        "currency": "EUR",
        "reason": "Chargeback reversed",
        "reversalDateTime": "2019-10-15T16:22:12Z"
    }
}

When a Chargeback Reversal comes in, you may find relevant chargeback reversal information in ChargebackReversalData

Account Updater Notification

{
    "result": "OK",
    "uuid": "abcde12345abcde12345",
    "merchantTransactionId": "2019-09-02-0012",
    "purchaseId": "20191210-abcde12345abcde12345",
    "transactionType": "REGISTER",
    "paymentMethod": "Creditcard",
    "extraData": {
        "lastCardUpdateDate": "2022-08-19",
        "lastCardUpdateResult": "updated"
    },
    "returnData": {
        "_TYPE": "cardData",
        "type": "mastercard",
        "cardHolder": "Firstname Lastname",
        "expiryMonth": "12",
        "expiryYear": "2050",
        "binDigits": "55555555",
        "firstSixDigits": "555555",
        "lastFourDigits": "4444",
        "fingerprint": "YQTgkfrQJYzExJYmomJBS0tWMF8D5J0jG/DAtes3X5oVElUNEbOld5lakWbgdUrW8VHKpNqFfJCMVakh+2LsoA",
        "binBrand": "MASTERCARD",
        "binBank": "SOME BANK",
        "binType": "CREDIT",
        "binLevel": "STANDARD",
        "binCountry": "US"
    }

}

If your merchant account has the Account Updater enabled, you will receive notifications in case a stored card of a customer gets updated. The update can have the following results:

Result	Description
`updated`	Card number and expiry date was updated
`closed`	Card is closed and not valid anymore
`new_expiry`	Card expiry date was updated
`contact`	Contact the cardholder for updated information

The results will be reported as extraData in the notification payload.

The returnData of type cardData already contains the updated information in that case.

No confirmed response

The first attempt would happen immediately. If no confirmation is received with a Status 200, content "OK" (as described above), we will try again in increasing intervals. First 1 minute, then 5, 15, 60, 120, 180, 720, and finally once every 24 hours for 7 days.

Data Verification

To prove the authenticity of the notification the Gateway signs every request with the same shared secret as used for signing your requests.

You should verify the signature by calculating it on your system and compare it to the given one.

The mechanism is the same as described in Signature, but instead of defining the various values (request URI, date, etc.), you must take them out of the HTTP request you received from us. You should also verify that the Date header is within a reasonable deviation of the current timestamp (e.g. 60 seconds)

Additional data

If you need additional information to process the notification for your shop order, you can use the optional field merchantMetaData or you can provide that data as GET parameters in the callbackUrl you define.

E.g. https://www.merchant.com/notification-url?someKey=someValue&anything=else

Callback data

Name	Type	Description
result	string	`OK`, `PENDING`, `ERROR`
uuid	string	UUID of the transaction
merchantTransactionId	string	your unique transaction ID
purchaseId	string	purchase ID
transactionType	string	`DEBIT`, `CAPTURE`, `DEREGISTER`, `PREAUTHORIZE`, `REFUND`, `REGISTER`, `VOID`, `CHARGEBACK`, `CHARGEBACK-REVERSAL`, `PAYOUT`
paymentMethod	string	payment method
amount	string	decimals separated by `.`, max. 3 decimals
currency	string	3 letter currency code
scheduleData	object	see ScheduleData
notificationSource	string	In case the transaction status, amount or currency has been changed after reconciliation the parameter can have the following value: `reconciliation`, `settlement`
originalAmount	string	In case the transaction amount has been changed after reconciliation the is parameter will contain the original amount. Decimals separated by `.`, max. 3 decimals
originalCurrency	string	In case the transaction currency has been changed after reconciliation the is parameter will contain the original currency. 3 letter currency code
chargebackData	object	see ChargebackData
chargebackReversalData	object	see ChargebackReversalData
extraData	object	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	merchant metadata
returnData	object	one of ReturnData
customer	object	see Customer
customerProfileData	object	see CustomerProfileData
message	string	error message in case of error transaction
code	number	error code in case of error transaction
adapterMessage	string	error message of adapter
adapterCode	string	error identifier of adapter