Transaction API v3.0

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

IXOPAY Gateway - Payment Platform

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

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

Request format

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

• The server accepts TLS version >= 1.2 connections.
• Content-Type must be application/json
• Authentication credentials are sent via BASIC Auth (see below)

If required by your merchant configuration:

• The request must contain a valid signature within the X-Signature header (see below)
• The request must contain a valid Date header, because this value is used for signature verification (refer to RFC 7231)

Headers Example:

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

Authentication

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

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

Example:

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

Signature

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

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

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

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

• HTTP Method (i.e. POST)
• MD5 hash of the request's body (the JSON string)
• Content-Type header value
• Timestamp as sent in the Date header
• Request URI (e.g. /api/v3/transaction/<api-key>/debit)

Example:

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

1. MD5 Hash of body: 307d8f0242742c6c429ce0f9eb0dbe08
2. Concatenation result (=message):

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

 3. HMAC(sha512, my-shared-secret, message), Base64 encoded = K66S1pPHfmfHwkVs+uUBaHgXUfKSvfGBtj+znPLp6LSjyzYM8pPGem4EO9X9YYkEIrGHSEe2QqUUllIWgyO40Q==

 4. Header to be sent:

X-Signature: K66S1pPHfmfHwkVs+uUBaHgXUfKSvfGBtj+znPLp6LSjyzYM8pPGem4EO9X9YYkEIrGHSEe2QqUUllIWgyO40Q==
Content-Type: application/json; charset=utf-8
Date: Tue, 21 Jul 2020 13:15:03 UTC

Signature testing tool:

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

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

 

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

 

Error handling

Example

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

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

Name	type
success	boolean
errorMessage	string
errorCode	int

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

Transaction Request

The examples show the basic data most connector requires. Depending on the connector type more data could be necessary. Please refer to the Connector Types documentation for concrete requirements.

To see all available fields please refer to Transaction Data.

For some languages we already provide a ready-to-use client implementation on GitHub.

Debit

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Debit performs a complete customer-to-merchant payment

POST /transaction/{apiKey}/debit

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

{
  "merchantTransactionId": "2019-09-02-0001",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://example.com/callback",
  "transactionToken": "ix::tRaNsAcT1OnToK3N",
  "description": "Example Product",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false, 
    "ipAddress": "127.0.0.1",   
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Preauthorize

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Preauthorize reserves the payment amount on the customer's payment instrument.

Depending on the payment method you have up to 7 days until you must Capture the transaction before the authorization expires.

POST /transaction/{apiKey}/preauthorize

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

{
  "merchantTransactionId": "2019-09-02-0002",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://example.com/callback",
  "description": "Example Product",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false, 
    "ipAddress": "127.0.0.1",   
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "threeDSecureData": {
    "3dsecure": "MANDATORY"
  },
  "language": "en"
}

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Capture

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Capture completes the payment which was previously authorized with the Preauthorize method.

Depending on the payment method you can even capture only a partial amount of the authorized amount.

POST /transaction/{apiKey}/capture

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Void

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

POST /transaction/{apiKey}/void

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Body parameter

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

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Register

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

POST /transaction/{apiKey}/register

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body example

Example request body

{
  "merchantTransactionId": "2019-09-02-0005",
  "additionalId1": "x0001",
  "additionalId2": "y0001",
  "extraData": {
    "someKey": "someValue",
    "otherKey": "otherValue"
  },
  "merchantMetaData": "merchantRelevantData",
  "successUrl": "http://example.com/success",
  "cancelUrl": "http://example.com/cancel",
  "errorUrl": "http://example.com/error",
  "callbackUrl": "http://example.com/callback",
  "customer": {
    "identification": "c0001",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-10-10",
    "gender": "M",
    "billingAddress1": "Maple Street 1",
    "billingAddress2": "Syrup Street 2",
    "billingCity": "Victoria",
    "billingPostcode": "V8W",
    "billingState": "British Columbia",
    "billingCountry": "CA",
    "billingPhone": "1234567890",
    "shippingFirstName": "John",
    "shippingLastName": "Doe",
    "shippingCompany": "Big Company Inc.",
    "shippingAddress1": "Yellow alley 3",
    "shippingAddress2": "Yellow alley 4",
    "shippingCity": "Victoria",
    "shippingPostcode": "V8W",
    "shippingState": "British Columbia",
    "shippingCountry": "CA",
    "shippingPhone": "1234567890",
    "company": "John's Maple Syrup",
    "email": "[email protected]",
    "emailVerified": false, 
    "ipAddress": "127.0.0.1",   
    "nationalId": "123123",
    "extraData": {
      "someCustomerDataKey": "value",
      "anotherKey": "anotherValue"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  },
  "description": "This is a register",
  "language": "en"
}

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Deregister

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Deregister deletes a previously registered payment instrument using Register.

POST /transaction/{apiKey}/deregister

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Refund

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Refund reverses a payment which was previously performed with Debit or Capture.

Depending on the payment method you can even refund only a partial amount of the original transaction amount.

POST /transaction/{apiKey}/refund

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

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

Response

Example responses

finished

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

redirect

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

errors

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

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

Payout

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

A Payout credits the customer's account with the given amount.

Depending on the connector, either referenceUuid or cardData will be required.

POST /transaction/{apiKey}/payout

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

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

Response

Example responses

finished

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

redirect

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

errors

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

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

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"
    },
    "paymentData": {
      "ibanData": {
        "iban": "AT123456789012345678",
        "bic": "ABC",
        "mandateId": "1234",
        "mandateDate": "2019-09-29"
      }
    }
  }
}

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

CustomerProfileData

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

Item

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

PaymentData

ibanData

Example

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

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

walletData

Example

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

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

ReturnData

cardData

Example cardData

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

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

ibanData

Example ibanData

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

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

phoneData

Example phoneData

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

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

walletData

Example walletData

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

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

RiskCheckData

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

Schedule

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

ScheduleData

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

TransactionError

Name	Type
message	string
code	number
adapterMessage	string
adapterCode	string

TransactionResponseError

Name	Type
errorMessage	string
errorCode	number
adapterMessage	string
adapterCode	string

3D-Secure 2.0 data

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

ThreeDSecureData

For a more detailed overview, please refer to 3D-Secure 2.0

Name	Type	Required	Accepted values
3dsecure	string	false	OFF, OPTIONAL, MANDATORY
channel	string	false	01, 02, 03
authenticationIndicator	string	false	01, 02, 03, 04, 05, 06
cardholderAuthenticationMethod	string	false	01, 02, 03, 04, 05, 06
cardholderAuthenticationDateTime	string	false	YYYY-MM-DD HH:MM
cardHolderAuthenticationData	string	false
challengeIndicator	string	false	01, 02, 03, 04
priorReference	string	false
priorAuthenticationMethod	string	false	01, 02, 03, 04
priorAuthenticationDateTime	string	false	YYYY-MM-DD HH:MM
priorAuthenticationData	string	false
cardholderAccountType	string	false	01, 02, 03, 04
cardholderAccountDate	string	false	YYYY-MM-DD
cardholderAccountChangeIndicator	string	false	01, 02, 03, 04
cardholderAccountLastChange	string	false	YYYY-MM-DD
cardholderAccountPasswordChangeIndicator	string	false	01, 02, 03, 04, 05
cardholderAccountLastPasswordChange	string	false	YYYY-MM-DD
shippingAddressUsageIndicator	string	false	01, 02, 03, 04
shippingAddressFirstUsage	string	false	YYYY-MM-DD
transactionActivityDay	number	false
transactionActivityYear	number	false
addCardAttemptsDay	number	false
purchaseCountSixMonths	number	false
suspiciousAccountActivityIndicator	string	false	01, 02
shippingNameEqualIndicator	string	false	01, 02
paymentAccountAgeIndicator	string	false	01, 02, 03, 04, 05
paymentAccountAgeDate	string	false	YYYY-MM-DD
billingAddressLine3	string	false
shippingAddressLine3	string	false
billingShippingAddressMatch	string	false	Y, N
homePhoneCountryPrefix	string	false
homePhoneNumber	string	false
mobilePhoneCountryPrefix	string	false
mobilePhoneNumber	string	false
workPhoneCountryPrefix	string	false
workPhoneNumber	string	false
purchaseInstalData	number	false
shipIndicator	string	false	01, 02, 03, 04, 05, 06, 07
deliveryTimeframe	string	false	01, 02, 03, 04
deliveryEmailAddress	string	false
reorderItemsIndicator	string	false	01, 02
preOrderPurchaseIndicator	string	false	01, 02
preOrderDate	string	false	YYYY-MM-DD
giftCardAmount	number	false
giftCardCurrency	string	false
giftCardCount	number	false
purchaseDate	string	false	YYYY-MM-DD HH:MM
recurringExpiry	string	false	YYYY-MM-DD
recurringFrequency	number	false
transType	string	false	01, 03, 10, 11, 28
exemptionIndicator	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

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	string	01, 02, 03, 04, 05
browserAcceptHeader	string
browserIpAddress	string
browserJavaEnabled	boolean
browserLanguage	string
browserColorDepth	string	1, 4, 8, 15, 16, 24, 32, 48
browserScreenHeight	number
browserScreenWidth	number
browserTimezone	number
browserUserAgent	string

SDK data

Name	Type	Accepted values
sdkInterface	string	01, 02, 03
sdkUiType	string	comma-separated list with values: 01, 02, 03, 04, 05
sdkAppID	string
sdkEncData	string
sdkEphemPubKey	string
sdkMaxTimeout	number
sdkReferenceNumber	string
sdkTransID	string

Status Request

Retrieve the status of transactions

transactionStatusByUuid

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

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

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

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

};

fetch('https://gateway.ixopay.com/api/v3/status/{apiKey}/getByUuid/{uuid}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Retrieve status of a transaction

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

Path parameters

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

Request body

none

Response

Example responses

success

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

success with transaction error

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

error

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

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

transactionStatusByMerchantTransactionId

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

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

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

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

};

fetch('https://gateway.ixopay.com/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Retrieve status of a transaction

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

Request body

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

Response

Example responses

success

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

success with transaction error

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

error

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

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

Status Data

ChargebackData

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

ChargebackReversalData

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

Schedule Request

Set and manage transaction schedules

Find out more about the Scheduler API

startSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

POST /schedule/{apiKey}/start

Path parameters

Name	Type	Required	Description
apiKey	string	true	API Key of Connector

Request body

Request body example

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

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

Response

Example responses

success

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

error

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

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

updateSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

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

Path parameters

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

Request body

Request body example

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

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

Response

Example responses

success

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

error

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

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

getSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

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

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

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

};

fetch('https://gateway.ixopay.com/api/v3/schedule/{apiKey}/{scheduleId}/get',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

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

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

Path parameters

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

Request body

none

Response

Example responses

success

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

error

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

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

pauseSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

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

Path parameters

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

Request body

none

Response

Example responses

success

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

error

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

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

continueSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

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

Path parameters

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

Request body

Request body example

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

Name	Type	Required	Description
continueDateTime	string	true	RFC8601 Date/Time YYYY-MM-DD\THH:MM:SS+00:00

Response

Example responses

success

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

error

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

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

cancelSchedule

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

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

Path parameters

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

Request body

none

Response

Example responses

success

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

error

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

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

Options Request

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

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

POST /options/{apiKey}/{optionsName}

Options Request

Path parameters

Code samples

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

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

 // ...

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

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

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

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

}, headers = headers)

print r.json()

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

    }

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

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

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

};

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

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

Request body

Request body example

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

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

Response

Example responses

success

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

error

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

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

Asynchronous Status Notification

The Gateway sends you a asynchronous notification once a transaction reaches a final state. This notification should be your source of trust when dealing with asynchronous transactions involving a redirect of the customer.

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

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

Success Notification

Example

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

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

Error Notification

Example

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

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

Chargeback Notification

Example

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

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

Chargeback Reversal Notification

Example

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

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

Data Verification

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

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

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

Additional data

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

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

Callback data

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