NAV
json php cUrl
  • Preamble
  • Getting started
  • TransactionWithCard - Request
  • Transaction Response
  • Transaction Data
  • Asynchronous Status Notification
  • 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.

    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.

    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:

    1. Username is anyApiUser, password is myPassword
    2. Concatenation is anyApiUser:myPassword
    3. Base64 encoded: YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
    4. 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

    Example:

    1. SHA512 Hash of body: efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
    2. 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
     

     

    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

    Request body example

    {
        "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

    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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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

    Request body example

    {
        "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.

    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.

    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

    Example

    {
      "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

    Example 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

    Example

    {
      "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

    Example

    {
        "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

    Example

    {
        "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

    Example

    {
        "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

    Example

    {
        "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

    Example for Account Update 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