Transaction API v3.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Till Payments Gateway - Payment Platform

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

Full OpenApi 3.0 Specification: https://gateway.tillpayments.com/Schema/V3/OpenApiSpecification.yml

Request format

Requests to the Transaction API 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)

If required by your merchant configuration:

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

If required by your merchant configuration, 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

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.

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.

Transaction Request

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

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/debit', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

A Debit performs a complete customer-to-merchant payment

POST /transaction/{apiKey}/debit

Path parameters

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0001",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "surchargeAmount": "0.9",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "transactionToken": "ix::tRaNsAcT1OnToK3N",
  "description": "Example Product",
  "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"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Preauthorize

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/preauthorize', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0002",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "surchargeAmount": "0.9",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "description": "Example Product",
  "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"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Capture

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/capture', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0003",
  "referenceUuid": "bcdef23456bcdef23456",
  "amount": "9.99",
  "currency": "EUR"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Void

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
    print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/void', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

POST /transaction/{apiKey}/void

Path parameters

Request Body

Body parameter

{
  "merchantTransactionId": "2019-09-02-0004",
  "referenceUuid": "bcdef23456bcdef23456"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Register

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/register', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

POST /transaction/{apiKey}/register

Path parameters

Request Body Example

Example request body

{
  "merchantTransactionId": "2019-09-02-0005",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "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"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "description": "This is a register",
  "language": "en"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Deregister

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister', params={}, headers = headers)

print r.json()

package main

import (
 "bytes"
 "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/deregister', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

A Deregister deletes a previously registered payment instrument using Register.

POST /transaction/{apiKey}/deregister

Path parameters

Request body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0006",
  "merchantMetaData": "merchantRelevantData",
  "referenceUuid": "bcdef23456bcdef23456"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Refund

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0007",
  "referenceUuid": "bcdef23456bcdef23456",
  "amount": "9.99",
  "currency": "EUR",
  "callbackUrl": "https://example.com/callback",
  "description": "Refund money"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Payout

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/payout', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0008",
  "amount": "9.99",
  "currency": "EUR",
  "callbackUrl": "https://example.com/callback",
  "transactionToken": "ix::a1A2B3b4c5C6D7d",
  "description": "Payout"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Incremental Authorization

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorization", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/incrementalAuthorizationincrementalAuthorization', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

Request Body

Request Body Example

{
  "merchantTransactionId": "2019-09-02-0002",
  "referenceUuid": "bcdef23456bcdef23456",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "description": "Example Product",
  "language": "en"
}

Response

Example responses

finished

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

redirect

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "REDIRECT",
  "redirectUrl": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}

Transaction Response

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

Generally there are 4 possible results:

FINISHED

{
  "success": true,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
}

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",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ]
}

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": "http://redirectComesUrlHere.com",
  "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"
}

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

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

ibanData

Example

{
  "paymentData": {
    "ibanData": {
      "iban": "AT123456789012345678",
      "bic": "ABC",
      "mandateId": "1234",
      "mandateDate": "2019-09-29"
    }
  }
}

walletData

Example

{
  "paymentData": {
    "walletData": {
      "walletType": "paypal",
      "walletOwner": "John Doe",
      "walletReferenceId": "12345abcde"
    }
  }
}

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

ibanData

Example ibanData

{
  "_TYPE": "ibanData",
  "accountOwner": "John Doe",
  "iban": "AT123456789012345678",
  "bic": "ABC",
  "bankName": "ABC Bank",
  "country": "US"
}

phoneData

Example phoneData

{
  "_TYPE": "phoneData",
  "phoneNumber": "1234567890",
  "country": "US",
  "operator": "OperatorXy"
}

walletData

Example walletData

{
  "_TYPE": "walletData",
  "walletReferenceId": "1234567890",
  "walletOwner": "John Doe",
  "walletType": "someType",
  "walletOwnerFirstName": "Max",
  "walletOwnerLastName": "Mustermann",
  "walletOwnerCountryCode": "DE",
  "walletRegistrationId": "reg157ra710N1D"
}

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

Status Request

Retrieve the status of transactions

transactionStatusByUuid

Code samples

require 'vendor/autoload.php';

$headers = [
  'Accept' => 'application/json',
]

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('GET','https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid} \
  -X GET \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("GET", "https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const headers = {
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByUuid/{uuid}', {
  method: 'GET',
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Retrieve status of a transaction

GET /status/{apiKey}/getByUuid/{uuid}

Path parameters

Request Body

none

Response

Example responses

success

{
  "success": true,
  "transactionStatus": "SUCCESS",
  "uuid": "abcde12345abcde12345",
  "merchantTransactionId": "2019-09-02-0001",
  "purchaseId": "20190902-abcde12345abcde12345",
  "transactionType": "debit",
  "paymentMethod": "Creditcard",
  "amount": "9.99",
  "currency": "EUR",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "company": "ACME Corp.",
    "emailVerified": true
  },
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "returnData": {
    "creditcardData": {
      "type": "visa",
      "cardHolder": "John Doe",
      "expiryMonth": 12,
      "expiryYear": 2030,
      "binDigits": "12345678",
      "firstSixDigits": "123456",
      "lastFourDigits": "4321",
      "threeDSecure": "OFF",
      "binBrand": "VISA",
      "binBank": "SOME BIG BANK",
      "binCountry": "US"
    }
  }
}

success with transaction error

{
  "success": true,
  "transactionStatus": "ERROR",
  "uuid": "abcde12345abcde12345",
  "merchantTransactionId": "2019-09-02-0001",
  "purchaseId": "20190902-abcde12345abcde12345",
  "transactionType": "DEBIT",
  "paymentMethod": "Creditcard",
  "amount": "9.99",
  "currency": "EUR",
  "errors": [
    {
      "message": "Payment could not be processed.",
      "code": "1234",
      "adapterMessage": "Processing failed.",
      "adapterCode": "1000"
    }
  ]
}

error

{
  "success": false,
  "errorMessage": "Transaction not found",
  "errorCode": 8001
}

transactionStatusByMerchantTransactionId

Code samples

require 'vendor/autoload.php';

$headers = [
  'Accept' => 'application/json',
]

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('GET','https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId} \
  -X GET \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("GET", "https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const headers = {
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', {
  method: 'GET',
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Retrieve status of a transaction

GET /status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}

Request Body

Response

Example responses

success

{
  "success": true,
  "transactionStatus": "SUCCESS",
  "uuid": "abcde12345abcde12345",
  "merchantTransactionId": "2019-09-02-0001",
  "purchaseId": "20190902-abcde12345abcde12345",
  "transactionType": "debit",
  "paymentMethod": "Creditcard",
  "amount": "9.99",
  "currency": "EUR",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "company": "ACME Corp.",
    "emailVerified": true
  },
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "returnData": {
    "creditcardData": {
      "type": "visa",
      "cardHolder": "John Doe",
      "expiryMonth": 12,
      "expiryYear": 2030,
      "binDigits": "12345678",
      "firstSixDigits": "123456",
      "lastFourDigits": "4321",
      "threeDSecure": "OFF",
      "binBrand": "VISA",
      "binBank": "SOME BIG BANK",
      "binCountry": "US"
    }
  }
}

success with transaction error

{
  "success": true,
  "transactionStatus": "ERROR",
  "uuid": "abcde12345abcde12345",
  "merchantTransactionId": "2019-09-02-0001",
  "purchaseId": "20190902-abcde12345abcde12345",
  "transactionType": "DEBIT",
  "paymentMethod": "Creditcard",
  "amount": "9.99",
  "currency": "EUR",
  "errors": [
    {
      "message": "Payment could not be processed.",
      "code": "1234",
      "adapterMessage": "Processing failed.",
      "adapterCode": "1000"
    }
  ]
}

error

{
  "success": false,
  "errorMessage": "Transaction not found",
  "errorCode": 8001
}

Status Data

ChargebackData

ChargebackReversalData

Schedule Request

Set and manage transaction schedules

Find out more about the Scheduler API

startSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Start a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.

POST /schedule/{apiKey}/start

Path parameters

Request Body

Request Body Example

{
  "registrationUuid": "abcde12345abcde12345",
  "amount": "9.99",
  "currency": "EUR",
  "periodLength": 6,
  "periodUnit": "MONTH",
  "startDateTime": "2019-09-30T01:00:00+00:00",
  "merchantMetaData": "merchantRelevantData",
  "callbackUrl" : "https://link.to/your/notification-handler"
}

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "registrationUuid": "abcde12345abcde12345",
  "oldStatus": "NON-EXISTING",
  "newStatus": "ACTIVE",
  "scheduledAt": "2019-09-30T12:00:00+00:00"
}

error

{
  "success": false,
  "errorMessage": "The scheduleId is not valid or does not match to the connector",
  "errorCode": 7040
}

updateSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/start', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

To update an existing schedule, simply send the fields which you wish to update.

POST /schedule/{apiKey}/{scheduleId}/update

Path parameters

Request Body

Request Body Example

{
  "amount": "9.99",
  "periodUnit": "YEAR"
}

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "registrationUuid": "abcde12345abcde12345",
  "oldStatus": "ACTIVE",
  "newStatus": "ACTIVE",
  "scheduledAt": "2019-09-30T12:00:00+00:00"
}

error

{
  "success": false,
  "errorMessage": "The scheduleId is not valid or does not match to the connector",
  "errorCode": 7040
}

getSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Accept' => 'application/json',
]

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('GET','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get \
  -X GET \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("GET", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const headers = {
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/get', {
  method: 'GET',
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Retrieve a schedule. Requires the UUID of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.

GET /schedule/{apiKey}/{scheduleId}/get

Path parameters

Request Body

none

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "registrationUuid": "abcde12345abcde12345",
  "oldStatus": "ACTIVE",
  "newStatus": "ACTIVE",
  "scheduledAt": "2019-09-30T12:00:00+00:00"
}

error

{
  "success": false,
  "errorMessage": "The scheduleId is not valid or does not match to the connector",
  "errorCode": 7040
}

pauseSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/pause', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Pause a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.

POST /schedule/{apiKey}/{scheduleId}/pause

Path parameters

Request Body

none

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "oldStatus": "ACTIVE",
  "newStatus": "PAUSED"
}

error

{
  "success": false,
  "errorMessage": "The status of the schedule is not valid for the requested operation",
  "errorCode": 7070
}

continueSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/continue', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Continue a schedule which has been paused. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.

POST /schedule/{apiKey}/{scheduleId}/continue

Path parameters

Request Body

Request Body Example

{
  "continueDateTime": "2019-09-30T01:00:00+00:00"
}

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "oldStatus": "PAUSED",
  "newStatus": "ACTIVE",
  "scheduledAt": "2019-10-05T14:26:11+00:00"
}

error

{
  "success": false,
  "errorMessage": "The status of the schedule is not valid for the requested operation",
  "errorCode": 7070
}

cancelSchedule

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Cancel a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.

POST /schedule/{apiKey}/{scheduleId}/cancel

Path parameters

Request Body

none

Response

Example responses

success

{
  "success": true,
  "scheduleId": "SC-1234-1234-1234-1234-1234-1234",
  "oldStatus": "ACTIVE",
  "newStatus": "CANCELLED"
}

error

{
  "success": false,
  "errorMessage": "The status of the schedule is not valid for the requested operation",
  "errorCode": 7070
}

Options Request

Some adapters can provide additional information for your payment integration, for example a bank list for EPS transactions. This allows you to show the bank selection already on your shop checkout site.

See the adapter specific page for additional information about available Options request methods.

POST /options/{apiKey}/{optionsName}

Options Request

Path Parameters

Code samples

require 'vendor/autoload.php';

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
];

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = [];

try {
  $response = $client->request('POST','https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

# You can also use wget
curl https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName} \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

URL obj = new URL("https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();
System.out.println(response.toString());

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}', params: {}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}', params={}, headers = headers)

print r.json()

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
  }

  data := bytes.NewBuffer([]byte{jsonReq})
  req, err := http.NewRequest("POST", "https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}", data)
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
}

const inputBody = '{}';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

fetch('https://gateway.tillpayments.com/api/v3/options/{apiKey}/{optionsName}', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

Request body

Request Body Example

{
  "parameters": {
    "property1": "string",
    "property2": "string"
  }
}

Response

Example responses

success

{
  "success": true,
  "options": {
    "bank1": "Bank One",
    "bank2": "Bank Two",
    "bank3": "Bank Three",
    "bank4": "Bank Four"
  }
}

error

{
  "success": false,
  "errorMessage": "Given identifier 'someIdentifier' is invalid."
}

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