v.v24.19

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.

934 Juno Hospitality Suite - Payment Platform

Endpoint: https://gateway.p934.io/api/v3

Full OpenApi 3.0 Specification: https://gateway.p934.io/Schema/V3/OpenApiSpecification.yml

Request format

Requests to the Transaction API are sent via HTTPS containing a JSON body.

If required by your merchant configuration:

Headers Example:

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

Authentication

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

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

Example:

  1. Username is anyApiUser, password is myPassword
  2. Concatenation is anyApiUser:myPassword
  3. Base64 encoded: YW55QXBpVXNlcjpteVBhc3N3b3Jk
  4. The passed header will then look like this: Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3Jk

Signature

If required by your merchant configuration, each request to the API must be signed with your shared secret.

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

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

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

Example:

  1. SHA512 Hash of body: efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
  2. Concatenation result (=message):
POST
efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
application/json; charset=utf-8
Tue, 21 Jul 2020 13:15:03 UTC
/api/v3/transaction/{apiKey}/debit

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

 4. Header to be sent:

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

Signature Testing Tool

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

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

Forward Compatibility

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

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/debit', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/debit \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/api/v3/transaction/{apiKey}/debit', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

A Debit performs a complete customer-to-merchant payment

POST /transaction/{apiKey}/debit

Path parameters

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",
  "surchargeAmount": "0.9",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "transactionToken": "ix::tRaNsAcT1OnToK3N",
  "description": "Example Product",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false,
    "ipAddress": "127.0.0.1",
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}
Name Type Required Description
merchantTransactionId string true your unique transaction ID
amount string true decimals separated by ., max. 3 decimals
surchargeAmount string false 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/pending
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
l2l3Data object false see L2L3Data
language string false 2 characters (lowercase)

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Preauthorize

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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",
  "surchargeAmount": "0.9",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "description": "Example Product",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false,
    "ipAddress": "127.0.0.1",
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}
Name Type Required Description
merchantTransactionId string true your unique transaction ID
amount string true decimals separated by ., max. 3 decimals
surchargeAmount string false decimals separated by ., max. 3 decimals
currency string true 3 letter currency code
captureInMinutes string false full minutes without decimals
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/pending
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
l2l3Data object false see L2L3Data
language string false 2 characters (lowercase)

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Capture

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/capture', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/capture \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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
description string false max. 255 characters
items object false object containing Items
l2l3Data object false see L2L3Data

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Void

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/void', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
    print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/void \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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
amount string false if supported by the adapter this will execute a partial void, decimals separated by .
currency string false 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

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Register

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/register', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/register \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://example.com/callback",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false,
    "ipAddress": "127.0.0.1",
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "description": "This is a register",
  "language": "en"
}
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/pending
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
l2l3Data object false see L2L3Data
language string false 2 characters (lowercase)

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Deregister

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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
tokenType string false ALL, PAN, NT Which token type should be deregistered. Default ALL
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": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Refund

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/refund', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/refund \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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": "https://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": "https://redirectComesUrlHere.com",
  "paymentMethod": "Creditcard"
}

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Payout

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/payout', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/payout \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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": "https://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/pending
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 (lowercase)

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Incremental Authorization

Code samples

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "errorUrl": "https://example.com/error",
  "callbackUrl": "https://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/pending
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
l2l3Data object false see L2L3Data
language string false 2 characters (lowercase)

Response

Example responses

finished

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

redirect

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

errors

{
  "success": false,
  "uuid": "abcde12345abcde12345",
  "purchaseId": "20190927-abcde12345abcde12345",
  "returnType": "ERROR",
  "paymentMethod": "Creditcard",
  "errors": [
    {
      "errorMessage": "Request failed",
      "errorCode": 1000,
      "adapterMessage": "Invalid parameters given",
      "adapterCode": "1234"
    }
  ],
  "extraData": [
    {
      "remainingAmount": "5"
    }
  ]
}
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
redirectQRCode string QR Code with redirectUrl base64 encoded
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)
extraData.remainingAmount object remaining amount of capture/ refund
errors object contains transaction errors, see TransactionResponseError
expiresAt string Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData)
payByLinkData object see PayByLinkData

Transaction Response

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

Generally there are 4 possible results:

FINISHED

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

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

ERROR

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

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

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

REDIRECT

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

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

PENDING

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

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

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

Transaction Data

Customer

Example

{
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false,
    "ipAddress": "127.0.0.1",
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    }
  }
}
Name Type Required Description
identification string false max. 36 characters
firstName string false max. 50 characters
lastName string false max. 50 characters
birthDate string false YYYY-MM-DD
gender string false M, F
billingAddress1 string false max. 50 characters
billingAddress2 string false max. 50 characters
billingCity string false max. 50 characters
billingPostcode string false max. 16 characters
billingState string false max. 30 characters
billingCountry string false 2-letter country code
billingPhone string false max. 20 characters
shippingFirstName string false max. 50 characters
shippingLastName string false max. 50 characters
shippingCompany string false max. 50 characters
shippingAddress1 string false max. 50 characters
shippingAddress2 string false max. 50 characters
shippingCity string false max. 50 characters
shippingPostcode string false max. 16 characters
shippingState string false max. 30 characters
shippingCountry string false 2-letter country code
shippingPhone string false max. 20 characters
company string false max. 50 characters
email string false valid e-mail
emailVerified boolean false
ipAddress string false
nationalId string false max. 14 characters
extraData object false object containing key-value pairs (string-to-string)
paymentData object false one of PaymentData

CustomerProfileData

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

Item

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

Level 2 & 3 Data

Name Type Required Description
l2l3Data.taxAmount float false
l2l3Data.vatRegistrationNumber string false
l2l3Data.nationalTaxIncluded string false
l2l3Data.discountAmount float false
l2l3Data.commodityCode string false
l2l3Data.freightAmount float false
l2l3Data.freightTaxAmount float false
l2l3Data.dutyAmount float false
l2l3Data.taxDetails[].type string false
l2l3Data.taxDetails[].amount float false
l2l3Data.taxDetails[].rate float false
l2l3Data.taxDetails[].code string false
l2l3Data.taxDetails[].code string false
l2l3Data.taxDetails[].applied string false
l2l3Data.taxDetails[].exemptionCode string false

Item Level 2 & 3 Data

Name Type Required Description
items[].l2l3Data.type string false
items[].l2l3Data.commodityCode string false
items[].l2l3Data.unit string false
items[].l2l3Data.unitPrice float false
items[].l2l3Data.discount float false
items[].l2l3Data.shippingAmount int false
items[].l2l3Data.taxAmount float false
items[].l2l3Data.taxRate float false
items[].l2l3Data.taxRate float false
items[].l2l3Data.taxDetails[].type string false
items[].l2l3Data.taxDetails[].amount float false
items[].l2l3Data.taxDetails[].rate float false
items[].l2l3Data.taxDetails[].code string false
items[].l2l3Data.taxDetails[].code string false
items[].l2l3Data.taxDetails[].applied string false
items[].l2l3Data.taxDetails[].exemptionCode string false
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 Set an expiration time of the payment link in minutes.

Example

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

PayByLinkData

Name Type Description
expiresAt string Indicates at what date time the pay-by-link transaction expires.
cancelUrl string Endpoint to call to cancel a pay-by-link transaction.

Example

{
  "payByLinkData": {
    "expiresAt": "2023-08-21 14:13:02 UTC",
    "cancelUrl": "https://gateway.ixopay.com/api/v3/payByLink/6ba2b0e0d02ac342cc41/cancel"
  }
}

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,
  "binDigits": "12345678",
  "firstSixDigits": "123456",
  "lastFourDigits": "4321",
  "fingerprint": "s0mEF1n6eRpr1n7",
  "threeDSecure": "OFF",
  "binBrand": "VISA",
  "binBank": "SOME BANK",
  "binCountry": "US"
}
Name Type Description
_TYPE string will contain value cardData
type string type of credit card
firstName string
lastName string
country string
cardHolder string
expiryMonth number MM
expiryYear number YYYY
binDigits string
firstSixDigits string
lastFourDigits string
fingerprint string
binBrand string
binBank string
binType string
binLevel string
binCountry string
threeDSecure string
eci string
merchantAdviceCode string pipes through the merchant advice code for failed transactions if supported by the adapter
parsedMerchantAdviceCode string parsed merchant advice code for failed transactions if supported by the adapter

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",
  "walletOwnerFirstName": "Max",
  "walletOwnerLastName": "Mustermann",
  "walletOwnerCountryCode": "DE",
  "walletRegistrationId": "reg157ra710N1D"
}
Name Type Description
_TYPE string will contain value walletData
walletReferenceId string Reference ID
walletOwner string Wallet Owner
walletType string Wallet Type
walletOwnerFirstName string Owner First Name
walletOwnerLastName string Owner Last Name
walletOwnerCountryCode string Owner Country Code
walletRegistrationId string Registration ID

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
schemeId

"Pin" the scheme ID in case of a co-branded card. Currently, there is only CB supported.		 string false CB
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 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. In future versions of 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 was last 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
billingAddressState

Customer's billing state (country subdivision code ISO 3166-2) max. 3 characters		 string false
shippingAddressState

Customer's shipping state (country subdivision code ISO 3166-2) max. 3 characters		 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 reordering previously purchased merchandise.
01 -> First time ordered
02 -> Reordered		 string false 01, 02
preOrderPurchaseIndicator

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 -> Merchandise available
02 -> Future availability		 string false 01, 02
preOrderDate

For a pre-ordered purchase, the expected date that the merchandise will be available.
Format: YYYY-MM-DD		 string false YYYY-MM-DD
giftCardAmount

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).		 number false
giftCardCurrency

For prepaid or gift card purchase, the currency code of the card		 string false
giftCardCount

For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. Field is limited to 2 characters.		 number false
purchaseDate

Date and time of the purchase, expressed in UTC. Format: YYYY-MM-DD HH:mm:ss
**Note: if omitted we put in today's date		 string false YYYY-MM-DD HH:MM
recurringExpiry

Date after which no further authorizations shall be performed. This field is required for 01-PA and for 02-NPA, if 3DS Requestor Authentication Indicator = 02 or 03.
Format: YYYY-MM-DD		 string false YYYY-MM-DD
recurringFrequency

Indicates the minimum number of days between authorizations. The field is limited to maximum 4 characters. This field is required if 3DS Requestor Authentication Indicator = 02 or 03.		 number false
transType

Identifies the type of transaction being authenticated. The values are derived from ISO 8583.
01 -> Goods / Service purchase
03 -> Check Acceptance
10 -> Account Funding
11 -> Quasi-Cash Transaction
28 -> Prepaid activation and Loan		 string false 01, 03, 10, 11, 28
threeRIIndicator

Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handling a 3RI request. Possible values are:
01 -> Recurring transaction
02 -> Installment transaction
03 -> Add card
04 -> Maintain card information
05 -> Account verification.
06 -> Split/delayed shipment
07 -> Top-up
08 -> Mail order
09 -> Telephone order
10 -> Whitelist status check
11 -> Other payment
12 -> Billing agreement.
 string false 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12
exemptionIndicator

Requests an SCA exemption for this transaction. Possible values are:
01 -> Low Value Transaction (amount under 30 EUR)
02 -> Low Risk Transaction
03 -> Whitelisted transaction, merchant is added as "Trusted Beneficiary" by cardholder
04 -> Secure Corporate Payment
05 -> Recurring or Merchant-initiated transaction
06 -> Mail or Telephone Order
07 -> Anonymous payment card		 string false 01, 02, 03, 04, 05, 06, 07

3D-Secure 2.0 Device Data

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

Browser Data

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

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

Name Type Accepted values
browserChallengeWindowSize

Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience.
01 -> 250 x 400
02 -> 390 x 400
03 -> 500 x 600
04 -> 600 x 400
05 -> Full screen		 string 01, 02, 03, 04, 05
browserAcceptHeader

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser		 string
browserIpAddress

IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
- IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255
- IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334		 string
browserJavaEnabled

Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.		 boolean
browserLanguage

Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property.		 string
browserColorDepth

Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
1 -> 1 bit
4 -> 4 bits
8 -> 8 bits
15 -> 15 bits
16 -> 16 bits
24 -> 24 bits
32 -> 32 bits
48 -> 48 bits		 string 1, 4, 8, 15, 16, 24, 32, 48
browserScreenHeight

Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.		 number
browserScreenWidth

Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property.		 number
browserTimezone

Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method.		 number
browserUserAgent

Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters.		 string

SDK Data

Name Type Accepted values
sdkInterface

Specifies all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values are:
01 -> Native
02 -> HTML
03 -> Both		 string 01, 02, 03
sdkUiType

Contains a comma-separated list of all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values for each UI type are:
01 -> Text
02 -> Single select
03 -> Multi select
04 -> OOB
05 -> Html Other (valid only for HTML UI)
E.g. 01,02,05		 string comma-separated list with values:
01, 02, 03, 04, 05
sdkAppID

Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Customer Device.		 string
sdkEncData

JWE Object as defined 3DS Specs Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt.		 string
sdkEphemPubKey

Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS
The value should be a JSON string containing the keys kty, crv, x, y, e.g. {"kty":"EC","crv":"P-256","x":"...","y":"..."}		 string
sdkMaxTimeout

Indicates the maximum amount of time (in minutes) for all exchanges. The field shall have value greater than or equal to 05.		 number
sdkReferenceNumber

Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 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 expiration 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 expiration 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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('GET','https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid} \
  -X GET \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', params: {}, headers: headers

p JSON.parse(result)
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.p934.io/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.p934.io/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.p934.io/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,
      "binDigits": "12345678",
      "firstSixDigits": "123456",
      "lastFourDigits": "4321",
      "threeDSecure": "OFF",
      "binBrand": "VISA",
      "binBank": "SOME BIG BANK",
      "binCountry": "US"
    }
  }
}

success with transaction error

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

error

{
  "success": false,
  "errorMessage": "Transaction not found",
  "errorCode": 8001
}
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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('GET','https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId} \
  -X GET \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', params: {}, headers: headers

p JSON.parse(result)
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.p934.io/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.p934.io/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.p934.io/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,
      "binDigits": "12345678",
      "firstSixDigits": "123456",
      "lastFourDigits": "4321",
      "threeDSecure": "OFF",
      "binBrand": "VISA",
      "binBank": "SOME BIG BANK",
      "binCountry": "US"
    }
  }
}

success with transaction error

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

error

{
  "success": false,
  "errorMessage": "Transaction not found",
  "errorCode": 8001
}
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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/start', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/start \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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",
  "merchantMetaData": "merchantRelevantData",
  "callbackUrl" : "https://link.to/your/notification-handler"
}
Name Type Required Description
registrationUuid string true UUID of an initial register, debit-with-register or preauthorize-with-register
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 true RFC8601 Date/Time YYYY-MM-DDTHH:MM:SS+00:00
merchantMetaData string false
callbackUrl string false Callback Url for sending the Postback notifications of transactions initiated by the schedule to this URL, instead of the URL from the Register transaction.

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/start', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/start \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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
callbackUrl string false Callback Url for sending the Postback notifications of transactions initiated by the schedule to this URL, instead of the URL from the Register transaction.

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('GET','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get \
  -X GET \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', params: {}, headers: headers

p JSON.parse(result)
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://gateway.p934.io/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.p934.io/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.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', {
  method: 'GET',
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

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

Path parameters

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

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

Path parameters

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

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

Path parameters

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', {
  method: 'POST',
  body: inputBody,
  headers: headers
}).then(function (res) {
  return res.json();
}).then(function (body) {
  console.log(body);
});

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

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

Path parameters

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

require 'vendor/autoload.php';

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

$client = new \GuzzleHttp\Client();

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

try {
  $response = $client->request('POST','https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}', [
    'headers' => $headers,
    'json' => $request_body,
  ]);
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName} \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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.p934.io/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 an asynchronous notification once a transaction reaches a final state. This notification should be your source of trust when dealing with asynchronous transactions involving a redirect of the customer.

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

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

Success Notification

Example

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

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

Error Notification

Example

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

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

Chargeback Notification

Example

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

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

Chargeback Reversal Notification

Example

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

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

Account Updater Notification

Example for Account Update Notification

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

If your merchant account has the Account Updater enabled, you will receive notifications in case a stored card of a customer gets updated. The update information will be reported in the extraData of the notification payload.

Parameter Description
extraData.lastCardUpdateDate When the update was received
extraData.lastCardUpdateResult The result of the update

The update result can have the following values:

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

The returnData of type cardData will contain the updated information.

Network Token Notification

Example for Network Token Notification

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

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

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

Parameter Description
extraData.networkTokenStatus Status of the token
extraData.networkTokenMetadata Array with card metadata (if available)
extraData.lastNetworkTokenUpdateDate Update notification date
extraData.lastNetworkTokenUpdateResult Update notification result

The networkTokenStatus may have the following values:

Status Description
active Token is active and can be used
inactive The token is not yet active
suspended The token has been suspended and cannot be used at the moment
deactivated The token is disabled and cannot be used anymore
pending Tokenization is in progress
error Error occurred during tokenization

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

The networkTokenMetadata may contain following values:

Parameter Description
mimeType MIME type
data Image data (may be encoded, e.b. base64)
width (conditional) Width
height (conditional) Height

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

lastNetworkTokenUpdateResult Description
pan_changed PAN has changed
pan_expiry_changed PAN expiry has changed
token_expiry_changed Token expiry has changed
active Token is active and can be used
inactive The token is not yet active
suspended The token has been suspended and cannot be used at the moment
deactivated The token is disabled and cannot be used anymore
error Error occurred during tokenization

No Confirmed Response

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

Data Verification

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

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

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

Additional data

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

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

Callback Data

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