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.

Forward Compatibility

The Payment Gateway may expand and enhance its API in an additive and backwards-compatible way. Below, we list the expectations that integrators shall adhere to in order to remain forward compatible with future enhancements.

• We reserve the right to extend our API in an additive way.

• We may add additional, optional fields to our API request.

• We may add additional fields to our existing API responses and postbacks.

• Fields with explicit ENUM declarations may be extended in the future. Integrators shall be capable to handle newly introduced ENUM values.

  For instance, this may be additional error codes or names of card brands.

• We reserve the right to change the length or format of opaque strings, such as error messages and human-readable strings.

  • Do not make assumptions about the length of strings. Many of these values are taken verbatim from underlying payment processors, and are therefore subject to their sizing constraints.

  • This includes adding or removing prefixes of IDs, generated by the 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.

• 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)

Headers Example:

Content-Type: application/json; charset=utf-8
Date: Mon, 01 Jan 2018 11:01:36 UTC
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3Jk
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: YW55QXBpVXNlcjpteVBhc3N3b3Jk
4. The passed header will then look like this: Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3Jk

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/{apiKey}/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 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 is: /api/v3/transaction/{apiKey}/debit

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/{apiKey}/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)
Generate signature

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

Error handling

Example

{
  "success": false,
  "errorMessage": "Signature invalid",
  "errorCode": 1004
}

General errors, such as authentication errors or validation errors will return an appropriate JSON response body containing an error message and error code.

For errors caused during the processing of requests, please refer to the corresponding request's respond section.

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 https://secure.tillpayments.com/api/v3/transaction/API-KEY-HERE/debit \
  -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"

A Debit performs a complete customer-to-merchant payment

POST /transaction/{apiKey}/debit

Path parameters

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

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

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

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

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

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

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

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

Continue Dcc

DCC is a direct currency conversion possibility which can be activated during a credit card payment, if activated in the connector. To do so you will first have to send a regular transaction request with an additional parameter to receive the current conversion rate.

If there is a possible conversion an additional request has to be sent to with the chosen currency to finalize the transaction.

DCC Request

To initiate a DCC Request, add the additional requestDcc parameter to the transaction request.

Initial Transaction Request Example

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0001",
  "amount": "155",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "cardData": {
    "cardHolder": "Max Mustermann",
    "pan": "4111111111111111",
    "cvv": "123",
    "expirationMonth": "12",
    "expirationYear": "2024"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false,
    "ipAddress": "127.0.0.1"
  },
  "language": "en",
  "requestDcc": true
}

Response body Example

{
  "success": true,
  "uuid": "12345678910",
  "purchaseId": "20211006-12345678910",
  "returnType": "PENDING_DCC",
  "dccData": {
    "uuid": "10987654321",
    "originalAmount": "155.00",
    "originalCurrency": "EUR",
    "convertedAmount": "200",
    "convertedCurrency": "USD",
    "conversionRate": "float",
    "disclaimer": "string",
    "markUp": "float"
  }
}

Choice of Rate Request Example

If a transaction is in the pending_dcc state it can be finalized with a request to the continue-dcc endpoint. The possible currencies are the original currency of the transaction and the converted currency from the transaction response.

POST /transaction/{apiKey}/continue-dcc

Request Body Example

{
  "continueDccUuid": "12345678910",
  "selectedDccCurrency": "USD"
}

Response body Example

{
  "success": true,
  "uuid": "12345678910",
  "purchaseId": "20211006-12345678910",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard",
  "returnData": {
    "type": "visa",
    "cardHolder": "Max Mustermann",
    "expiryMonth": "12",
    "expiryYear": "2022",
    "binDigits": "41111111",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111",
    "merchantFingerprint": "string",
    "globalFingerprint": "string",
    "_TYPE": "cardData"
  },
  "extraData": {
    "captureId": "12345678910"
  },
  "dccData": {
    "uuid": "12345678910",
    "originalAmount": "155.00",
    "originalCurrency": "EUR",
    "convertedAmount": "200",
    "convertedCurrencyCode": "USD",
    "conversionRate": 0.89994,
    "selectedCurrencyCodeForTransaction": "USD",
    "markUp": 0.06
  }
}

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 the following fields:

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

CustomerProfileData

Item

Level 2 & 3 Data

Item Level 2 & 3 Data

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",
  "binSegment": "Consumer",
  "binRawData": {
    "type": "12345-67890-abc-def",
    "data": {
      "binDigits": "123456",
      "brand": "VISA",
      "bank": "SOME BANK",
      "country2Iso": "US",
      "country3Iso": "840",
      "segment": "Consumer"
    }
  }
}

RiskCheckData

Schedule

ScheduleData

TransactionError

TransactionResponseError

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",
    ...
  }
}

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:

SDK Data

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",
      ...
    },
    ...
  }
}

Transaction Extra Data

Transaction Item Extra Data besides the Standard Item Data

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 information will be reported in the extraData of the notification payload.

The update result can have the following values:

The returnData of type cardData will contain the updated information.

Network Token Notification

Example for Network Token Notification

{
    "result": "OK",
    "uuid": "7e59391c9a939c1be763",
    "merchantTransactionId": "20230523141348",
    "purchaseId": "20230523-7e59391c9a939c1be763",
    "transactionType": "DEBIT",
    "paymentMethod": "Creditcard",
    "amount": "9.99",
    "currency": "EUR",
    "returnData": {
        "_TYPE": "cardData",
        "type": "visa",
        "cardHolder": "john",
        "expiryMonth": "02",
        "expiryYear": "2025",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "fingerprint": "Gsw+vddi8/Jhzy2D1yVdU1b8QCAIA/4vHVfrVtOUGreoCak++m2Azwvj/2ASbyxLpb4dT9+9de2evu1G2ncvsg",
        "threeDSecure": "OFF",
        "binBrand": "VISA",
        "binBank": "JPMORGAN CHASE BANK N.A.",
        "binType": "",
        "binLevel": "CLASSIC",
        "binCountry": "US"
    },
    "extraData": {
        "networkTokenStatus": "active",
        "networkTokenMetadata": [
            {
                "mimeType": "image/png",
                "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                "width": "150",
                "height": "150"
            },
            {
                "mimeType": "image/png",
                "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                "width": "",
                "height": ""
            }
        ]
    }
}

{
    "result": "OK",
    "uuid": "7e59391c9a939c1be763",
    "merchantTransactionId": "20230523141348",
    "purchaseId": "20230523-7e59391c9a939c1be763",
    "transactionType": "DEBIT",
    "paymentMethod": "Creditcard",
    "amount": "9.99",
    "currency": "EUR",
    "returnData": {
        "_TYPE": "cardData",
        "type": "visa",
        "cardHolder": "john",
        "expiryMonth": "02",
        "expiryYear": "2025",
        "binDigits": "41111111",
        "firstSixDigits": "411111",
        "lastFourDigits": "1111",
        "fingerprint": "Gsw+vddi8/Jhzy2D1yVdU1b8QCAIA/4vHVfrVtOUGreoCak++m2Azwvj/2ASbyxLpb4dT9+9de2evu1G2ncvsg",
        "threeDSecure": "OFF",
        "binBrand": "VISA",
        "binBank": "JPMORGAN CHASE BANK N.A.",
        "binType": "",
        "binLevel": "CLASSIC",
        "binCountry": "US"
    },
    "extraData": {
        "networkTokenStatus": "suspended"
    }
}

When a network token has been created, you will receive notifications in case of updates regarding that token. In the case of asynchronous tokenization, you will also receive a notification when the tokenization process has been completed and the token has been created. In the case of synchronous tokenization, the token information will be available in the API response as well as in the notification.

The token status and any possible token meta data (such as card art) will be reported in the extraData of the notification payload.

The networkTokenStatus may have the following values:

If the status is inactive, suspended or deactivated, it is not recommended to use the network token for processing.

The networkTokenMetadata may contain following values:

If the token has been updated, the lastNetworkTokenUpdateResult may have following values:

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