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.

IXOPAY Gateway - Payment Platform

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

Full OpenApi 3.0 Specification: https://gateway.ixopay.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 YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
X-Signature: DH7MfiGq5QYQusTzWMpWiJpnPz+o1pZbcf7HCiT1+jjc+7UrnmDSpVuHzrRrZ6UxJUYYnOHJfG91zm0VimWXHg==

Authentication

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

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

Example:

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

Signature

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
Request URI (e.g. /api/v3/transaction/<api-key>/debit)

Example:

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

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

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

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

4. Header to be sent:

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

Signature testing tool:

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

Signature parameters
API-Key
Shared Secret
Method
Content
Content-Type
Timestamp (format)
Endpoint

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

Error handling

Example

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

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

Name	type
success	boolean
errorMessage	string
errorCode	int

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

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/debit', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/debit \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

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

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

POST /transaction/{apiKey}/debit

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

{
  "merchantTransactionId": "2019-09-02-0001",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://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"
}

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
referenceUuid	string	false	UUID of an initial transaction
successUrl	string	false	redirect to URL on success
cancelUrl	string	false	redirect to URL on cancel
errorUrl	string	false	redirect to URL on error
callbackUrl	string	false	endpoint to receive status notifications
transactionToken	string	false	token generated via payment.js
description	string	false	max. 255 characters
items	object	false	object containing Items
withRegister	boolean	false	store customer's payment instrument for recurring transactions
transactionIndicator	string	false	`SINGLE`, `INITIAL`, `RECURRING`, `CARDONFILE`, `CARDONFILE-MERCHANT-INITIATED` or `MOTO`
customer	object	false	see Customer
↳customer.paymentData	object	false	one of PaymentData
schedule	object	false	see Schedule
customerProfileData	object	false	see CustomerProfileData
threeDSecureData	object	false	see ThreeDSecureData
language	string	false	2 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Preauthorize

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/preauthorize', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/preauthorize \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

{
  "merchantTransactionId": "2019-09-02-0002",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://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"
}

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
referenceUuid	string	false	UUID of an initial transaction
successUrl	string	false	redirect to URL on success
cancelUrl	string	false	redirect to URL on cancel
errorUrl	string	false	redirect to URL on error
callbackUrl	string	false	endpoint to receive status notifications
transactionToken	string	false	token generated via payment.js
description	string	false	max. 255 characters
items	object	false	object containing Items
withRegister	boolean	false	store customer's payment instrument for recurring transactions
transactionIndicator	string	false	`SINGLE`, `INITIAL`, `RECURRING`, `CARDONFILE`, `CARDONFILE-MERCHANT-INITIATED` or `MOTO`
customer	object	false	see Customer
↳customer.paymentData	object	false	one of PaymentData
schedule	object	false	see Schedule
customerProfileData	object	false	see CustomerProfileData
threeDSecureData	object	false	see ThreeDSecureData
language	string	false	2 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Capture

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/capture', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/capture \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
referenceUuid	string	true	UUID of a preauthorize
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
items	object	false	object containing Items

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Void

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/void', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/void \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Body parameter

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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
referenceUuid	string	true	UUID of a preauthorized transaction
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Register

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/register', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/register \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body example

Example request body

{
  "merchantTransactionId": "2019-09-02-0005",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://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"
}

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
successUrl	string	false	redirect to URL on success
cancelUrl	string	false	redirect to URL on cancel
errorUrl	string	false	redirect to URL on error
callbackUrl	string	false	endpoint to receive status notifications
transactionToken	string	false	token generated via payment.js
description	string	false	max. 255 characters
customer	object	false	see Customer
↳customer.paymentData	object	false	one of PaymentData
schedule	object	false	see Schedule
customerProfileData	object	false	see CustomerProfileData
threeDSecureData	object	false	see ThreeDSecureData
language	string	false	2 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Deregister

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/deregister', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/deregister \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
referenceUuid	string	true	UUID of a register, debit-with-register or preauthorize-with-register
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Refund

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/refund', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/refund \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
referenceUuid	string	true	UUID of a debit or capture
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
callbackUrl	string	false	endpoint to receive status notifications
transactionToken	string	false	token generated via payment.js
description	string	false	max. 255 characters
items	object	false	object containing Items

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Payout

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/payout', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/payout \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
referenceUuid	string	conditional	UUID of an initial transaction
transactionToken	string	conditional	token generated via payment.js
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
successUrl	string	false	redirect to URL on success
cancelUrl	string	false	redirect to URL on cancel
errorUrl	string	false	redirect to URL on error
callbackUrl	string	false	endpoint to receive status notifications
description	string	false	max. 255 characters
items	object	false	object containing Items
customer	object	false	see Customer
↳customer.paymentData	object	false	one of PaymentData
language	string	false	2 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

Incremental Authorization

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/transaction/{apiKey}/incrementalAuthorization', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/transaction/{apiKey}/incrementalAuthorization \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

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": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://example.com/callback",
  "description": "Example Product",
  "language": "en"
}

Name	Type	Required	Description
merchantTransactionId	string	true	your unique transaction ID
referenceUuid	string	true	UUID of the initial preauthorize
amount	string	true	decimals separated by `.`, max. 3 decimals
currency	string	true	3 letter currency code
additionalId1	string	false	any additional ID if required by adapter
additionalId2	string	false	any additional ID if required by adapter
extraData	object	false	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	false	max. 255 characters
successUrl	string	false	redirect to URL on success
cancelUrl	string	false	redirect to URL on cancel
errorUrl	string	false	redirect to URL on error
callbackUrl	string	false	endpoint to receive status notifications
transactionToken	string	false	token generated via payment.js
description	string	false	max. 255 characters
items	object	false	object containing Items
language	string	false	2 characters

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": "http://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"
    }
  ]
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
uuid	string	UUID of the transaction
purchaseId	string	purchase ID of the transaction
returnType	string	`FINISHED`, `REDIRECT`, `HTML`, `PENDING`, `ERROR`
redirectType	string	`iframe`, `fullpage`, `3ds`
redirectUrl	string	where the customer must be redirected to
htmlContent	string
paymentDescriptor	string
paymentMethod	string	payment method used (if already determined)
returnData	object	containing one of ReturnData
scheduleData	object	see ScheduleData
customerProfileData	object	see CustomerProfileData
riskCheckData	object	see RiskCheckData
extraData	object	object containing `key-value` pairs (string-to-string)
errors	object	contains transaction errors, see TransactionResponseError

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.

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

ERROR

{
  "success": false,
  "uuid": "abcde12345abcde12345"
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "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"
    }
  }
}

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

CustomerProfileData

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

Item

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

Pay-By-Link

Name	Type	Required	Description
sendByEmail	boolean	true	Indicates whether a payment link should be sent to the customer. If false provided, it means the payment link will not be sent to the customer via email.
expirationInMinute	number	false	The expiration in minute that the payment link expires.

Example

{
  "payByLink": {
    "sendByEmail": false,
    "expirationInMinute" : 5
  }
}

PaymentData

ibanData

Example

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

Name	Type	Required	Description
iban	string	false
bic	string	false
mandateId	string	false
mandateDate	string	false	`YYYY-MM-DD`

walletData

Example

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

Name	Type	Required	Description
walletType	string	false	Type of wallet
walletOwner	string	false	Owner
walletReferenceId	string	false	Reference ID

ReturnData

cardData

Example cardData

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

Name	Type	Description
_TYPE	string	will contain value `cardData`
type	string	type of credit card
firstName	string
lastName	string
country	string
cardHolder	string
expiryMonth	number	`MM`
expiryYear	number	`YYYY`
firstSixDigits	string
lastFourDigits	string
fingerprint	string
binBrand	string
binBank	string
binType	string
binLevel	string
binCountry	string
threeDSecure	string
eci	string

ibanData

Example ibanData

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

Name	Type	Description
_TYPE	string	will contain value `ibanData`
accountOwner	string
iban	string
bic	string
bankName	string
country	string

phoneData

Example phoneData

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

Name	Type	Description
_TYPE	string	will contain value `phoneData`
phoneNumber	string
country	string
operator	string

walletData

Example walletData

{
  "_TYPE": "walletData",
  "walletReferenceId": "1234567890",
  "walletOwner": "John Doe",
  "walletType": "someType"
}

Name	Type	Description
_TYPE	string	will contain value `walletData`
walletReferenceId	string
walletOwner	string
walletType	string

RiskCheckData

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

Schedule

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

ScheduleData

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

TransactionError

Name	Type
message	string
code	number
adapterMessage	string
adapterCode	string

TransactionResponseError

Name	Type
errorMessage	string
errorCode	number
adapterMessage	string
adapterCode	string

3D-Secure 2.0 data

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

ThreeDSecureData

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

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

3D-Secure 2.0 device data

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

Browser data

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

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

Name	Type	Accepted values
`browserChallengeWindowSize` Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. 01 -> 250 x 400 02 -> 390 x 400 03 -> 500 x 600 04 -> 600 x 400 05 -> Full screen	string	`01`, `02`, `03`, `04`, `05`
`browserAcceptHeader` Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser	string
`browserIpAddress` IP address of the browser as returned by the HTTP headers to the 3DS Requestor. - IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255 - IPv6 adress is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334	string
`browserJavaEnabled` Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.	boolean
`browserLanguage` Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property.	string
`browserColorDepth` Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. 1 -> 1 bit 4 -> 4 bits 8 -> 8 bits 15 -> 15 bits 16 -> 16 bits 24 -> 24 bits 32 -> 32 bits 48 -> 48 bits	string	`1`, `4`, `8`, `15`, `16`, `24`, `32`, `48`
`browserScreenHeight` Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.	number
`browserScreenWidth` Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.	number
`browserTimezone` Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method.	number
`browserUserAgent` Exact content of the HTTP user-agent header. The field is limited to maximum 2048 caracters.	string

SDK data

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

Risk data

Forter External Risk Check additional extra data

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

Customer Extra Data

Example

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

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

Transaction Extra Data

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

Transaction Item Extra Data besides the standard item data

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

Status Request

Retrieve the status of transactions

transactionStatusByUuid

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://gateway.ixopay.com/api/v3/status/{apiKey}/getByUuid/{uuid}', array(
        '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 -X GET https://gateway.ixopay.com/api/v3/status/{apiKey}/getByUuid/{uuid} \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
uuid	string	true	UUID of transaction

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

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
transactionStatus	string	status of the transaction
uuid	string	UUID of the transaction
referenceUuid	string	UUID of the related transaction
merchantTransactionId	string	your transaction ID
purchaseId	string	purchase ID
transactionType	string	transaction type
paymentMethod	string	payment method
amount	string	transaction amount
currency	string	transaction currency
schedules	object	an array containing attached schedules, see ScheduleData
errors	object	an array containing transaction errors, see TransactionError
chargebackData	object	see ChargebackData
chargebackReversalData	object	see ChargebackReversalData
extraData	object	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	merchant metadata
returnData	object	one of ReturnData
customer	object	see Customer
customerProfileData	object	see CustomerProfileData
errorMessage	string	description if request fails
errorCode	number	error identifier

transactionStatusByMerchantTransactionId

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://gateway.ixopay.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', array(
        '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 -X GET https://gateway.ixopay.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId} \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
merchantTransactionId	string	true	ID of merchant transaction

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

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
transactionStatus	string	status of the transaction
uuid	string	UUID of the transaction
referenceUuid	string	UUID of the related transaction
merchantTransactionId	string	your transaction ID
purchaseId	string	purchase ID
transactionType	string	transaction type
paymentMethod	string	payment method
amount	string	transaction amount
currency	string	transaction currency
schedules	object	an array containing attached schedules, see ScheduleData
errors	object	an array containing transaction errors, see TransactionError
chargebackData	object	see ChargebackData
chargebackReversalData	object	see ChargebackReversalData
extraData	object	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	merchant metadata
returnData	object	one of ReturnData
customer	object	see Customer
customerProfileData	object	see CustomerProfileData
errorMessage	string	description if request fails
errorCode	number	error identifier

Status Data

ChargebackData

Name	Type
originalUuid	string
originalMerchantTransactionId	string
amount	string
currency	string
reason	string
chargebackDateTime	string

ChargebackReversalData

Name	Type
originalUuid	string
originalMerchantTransactionId	string
chargebackUuid	string
amount	string
currency	string
reason	string
reversalDateTime	string

Schedule Request

Set and manage transaction schedules

Find out more about the Scheduler API

startSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/start', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/schedule/{apiKey}/start \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

{
  "registrationUuid": "abcde12345abcde12345",
  "amount": "9.99",
  "currency": "EUR",
  "periodLength": 6,
  "periodUnit": "MONTH",
  "startDateTime": "2019-09-30T01:00:00+00:00"
}

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

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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

updateSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/start', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/schedule/{apiKey}/start \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
scheduleId	string	true	ID of the schedule

Request body

Request body example

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

Name	Type	Required	Description
registrationUuid	string	false	UUID of an initial register, debit-with-register or preauthorize-with-register
amount	string	false	decimals separated by `.`, max. 3 decimals
currency	string	false	3 letter currency code
periodLength	number	false
periodUnit	string	false	`DAY`, `WEEK`, `MONTH`, `YEAR`
startDateTime	string	false	RFC8601 Date/Time `YYYY-MM-DD\THH:MM:SS+00:00`

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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

getSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/get', array(
        '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 -X GET https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/get \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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 / Preuathorize-with-register

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

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
scheduleId	string	true	ID of the schedule

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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

pauseSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/pause', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/pause \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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 / Preuathorize-with-register

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

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
scheduleId	string	true	ID of the schedule

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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

continueSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/continue', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/continue \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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 / Preuathorize-with-register

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

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
scheduleId	string	true	ID of the schedule

Request body

Request body example

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

Name	Type	Required	Description
continueDateTime	string	true	RFC8601 Date/Time `YYYY-MM-DD\THH:MM:SS+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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

cancelSchedule

Code samples

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/cancel \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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 / Preuathorize-with-register

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

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
scheduleId	string	true	ID of the schedule

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
}

Name	Type	Description
success	boolean	returns `true` or `false` depending on whether the request was successful
scheduleId	string	ID of the schedule
registrationUuid	string	UUID of the transaction the schedule was attached to
oldStatus	string	status before the request
newStatus	string	status after the request
scheduledAt	string	scheduled date
errorMessage	string	description if request fails
errorCode	number	error identifier

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

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://gateway.ixopay.com/api/v3/options/{apiKey}/{optionsName}', array(
        '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 -X POST https://gateway.ixopay.com/api/v3/options/{apiKey}/{optionsName} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.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.ixopay.com/api/v3/options/{apiKey}/{optionsName}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Name	Type	Required	Description
apiKey	string	true	API Key of Connector
optionsName	string	true	Options identifier of the appropriate adapter

Request body

Request body example

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

Name	Type	Required	Description
parameters	object	false	Parameters which may be required for certain adapters

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

Name	Description
success	returns `true` or `false` depending on whether the request was successful
options	on success, returns an array containing key-value pairs
errorMessage	string

Asynchronous Status Notification

The Gateway sends you a 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",
        "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",
        "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

Data Verification

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

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

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

Additional data

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

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

Callback data

Name	Type	Description
result	string	`OK`, `PENDING`, `ERROR`
uuid	string	UUID of the transaction
merchantTransactionId	string	your unique transaction ID
purchaseId	string	purchase ID
transactionType	string	`DEBIT`, `CAPTURE`, `DEREGISTER`, `PREAUTHORIZE`, `REFUND`, `REGISTER`, `VOID`, `CHARGEBACK`, `CHARGEBACK-REVERSAL`, `PAYOUT`
paymentMethod	string	payment method
amount	string	decimals separated by `.`, max. 3 decimals
currency	string	3 letter currency code
scheduleData	object	see ScheduleData
chargebackData	object	see ChargebackData
chargebackReversalData	object	see ChargebackReversalData
extraData	object	object containing `key-value` pairs (string-to-string)
merchantMetaData	string	merchant metadata
returnData	object	one of ReturnData
customer	object	see Customer
customerProfileData	object	see CustomerProfileData
message	string	error message in case of error transaction
code	number	error code in case of error transaction
adapterMessage	string	error message of adapter
adapterCode	string	error identifier of adapter