Transaction API v3.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
IXOPAY Gateway - Payment Platform
Endpoint: https://gateway.ixopay.com/api/v3
Full OpenApi 3.0 Specification: https://gateway.ixopay.com/Schema/V3/OpenApiSpecification.yml
Request format
Requests to the Transaction API are sent via HTTPS containing a JSON body.
- The server accepts TLS version >= 1.2 connections.
- Content-Type must be
application/json
- Authentication credentials are sent via BASIC Auth (see below)
If required by your merchant configuration:
- The request must contain a valid signature within the
X-Signature
header (see below) - The request must contain a valid
Date
header, because this value is used for signature verification (refer to RFC 7231)
Headers Example:
Content-Type: application/json; charset=utf-8
Date: Mon, 01 Jan 2018 11:01:36 GMT
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
X-Signature: DH7MfiGq5QYQusTzWMpWiJpnPz+o1pZbcf7HCiT1+jjc+7UrnmDSpVuHzrRrZ6UxJUYYnOHJfG91zm0VimWXHg==
Authentication
The API username and password must be sent as BASIC Authentication in the Authorization
header (refer to RFC 7617).
Username and password are concatenated by a :
(colon) and the whole string is Base64 encoded.
Example:
- Username is
anyApiUser
, password ismyPassword
- Concatenation is
anyApiUser:myPassword
- Base64 encoded:
YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
- The passed header will then look like this:
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
Signature
If required by your merchant configuration, each request to the API must be signed with your shared secret.
The signature is generated via Hash HMAC using SHA2-512 as hashing algorithm. Afterwards the binary (not hexadecimal!) HMAC must be Base64 encoded.
The secret key for the HMAC is the shared secret of the Gateway's connector.
The message is the concatenation of the following data, separated by a single line-break without carriage-return character, i.e. \n
- HTTP Method (i.e.
POST
) - 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
- MD5 Hash of body:
307d8f0242742c6c429ce0f9eb0dbe08
- 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 |
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 |