Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
934 Juno Hospitality Suite - Payment Platform
Endpoint: https://gateway.p934.io/api/v3
Full OpenApi 3.0 Specification: https://gateway.p934.io/Schema/V3/OpenApiSpecification.yml
Requests to the Transaction API are sent via HTTPS containing a JSON body.
application/json
If required by your merchant configuration:
X-Signature
header (see below)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==
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:
anyApiUser
, password is myPassword
anyApiUser:myPassword
YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
Authorization: Basic YW55QXBpVXNlcjpteVBhc3N3b3JkCg==
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
POST
)Date
header (Note: as a special case, we'd give the X-Date
header precedence. Set this header in case your HTTP client doesn't allow you to override the Date
header)/api/v3/transaction/{apiKey}/debit
)Example:
my-api-key
my-shared-secret
{ "merchantTransactionId": "2019-09-02-0004", "amount": "9.99", "currency": "EUR" }
application/json; charset=utf-8
Tue, 21 Jul 2020 13:15:03 UTC
Note: as a special case, we'd give the X-Date
header precedence. Set this header in case your HTTP client doesn't allow you to override the Date
header./api/v3/transaction/{apiKey}/debit
efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
POST
efe0b7cd39d6904dc90924b1a89629b14f11082ed2178cff562364ca0172318e1535bb8766fbe66e8cc44d311eba806349bfe185607eca12d9d0f377a03ee617
application/json; charset=utf-8
Tue, 21 Jul 2020 13:15:03 UTC
/api/v3/transaction/{apiKey}/debit
3. HMAC(sha512, my-shared-secret, message), Binary-mode (not HEX),
Base64 encoded = nL+8FBKWx4/pahYScKs/dRYPBEWjiBalRaWKHGtxLpELmLrgJ/+dSWjt6dZNuu6oF18NyWEU8tXLEVm2mtEapg==
4. Header to be sent:
X-Signature: nL+8FBKWx4/pahYScKs/dRYPBEWjiBalRaWKHGtxLpELmLrgJ/+dSWjt6dZNuu6oF18NyWEU8tXLEVm2mtEapg==
Content-Type: application/json; charset=utf-8
Date: Tue, 21 Jul 2020 13:15:03 UTC
Use this tool to verify the correctness of your signature generation.
The Payment Gateway may expand and enhance its API in an additive and backwards-compatible way. Below, we list the expectations that integrators shall adhere to in order to remain forward compatible with future enhancements.
We reserve the right to extend our API in an additive way.
We may add additional, optional fields to our API request.
We may add additional fields to our existing API responses and postbacks.
Fields with explicit ENUM declarations may be extended in the future. Integrators shall be capable to handle newly introduced ENUM values.
For instance, this may be additional error codes or names of card brands.
We reserve the right to change the length or format of opaque strings, such as error messages and human-readable strings.
Do not make assumptions about the length of strings. Many of these values are taken verbatim from underlying payment processors, and are therefore subject to their sizing constraints.
This includes adding or removing prefixes of IDs, generated by the API.
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.
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.
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/debit', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/debit \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/debit");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/debit");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/debit', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/debit', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/debit", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/debit', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Debit performs a complete customer-to-merchant payment
POST /transaction/{apiKey}/debit
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0001",
"additionalId1": "x0001",
"additionalId2": "y0001",
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"merchantMetaData": "merchantRelevantData",
"amount": "9.99",
"surchargeAmount": "0.9",
"currency": "EUR",
"successUrl": "https://example.com/success",
"cancelUrl": "https://example.com/cancel",
"errorUrl": "https://example.com/error",
"callbackUrl": "https://example.com/callback",
"transactionToken": "ix::tRaNsAcT1OnToK3N",
"description": "Example Product",
"customer": {
"identification": "c0001",
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-10-10",
"gender": "M",
"billingAddress1": "Maple Street 1",
"billingAddress2": "Syrup Street 2",
"billingCity": "Victoria",
"billingPostcode": "V8W",
"billingState": "British Columbia",
"billingCountry": "CA",
"billingPhone": "1234567890",
"shippingFirstName": "John",
"shippingLastName": "Doe",
"shippingCompany": "Big Company Inc.",
"shippingAddress1": "Yellow alley 3",
"shippingAddress2": "Yellow alley 4",
"shippingCity": "Victoria",
"shippingPostcode": "V8W",
"shippingState": "British Columbia",
"shippingCountry": "CA",
"shippingPhone": "1234567890",
"company": "John's Maple Syrup",
"email": "[email protected]",
"emailVerified": false,
"ipAddress": "127.0.0.1",
"nationalId": "123123",
"extraData": {
"someCustomerDataKey": "value",
"anotherKey": "anotherValue"
},
"paymentData": {
"ibanData": {
"iban": "AT123456789012345678",
"bic": "ABC",
"mandateId": "1234",
"mandateDate": "2019-09-29"
}
}
},
"threeDSecureData": {
"3dsecure": "MANDATORY"
},
"language": "en"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
amount | string | true | decimals separated by . , max. 3 decimals |
surchargeAmount | string | false | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
referenceUuid | string | false | UUID of an initial transaction |
successUrl | string | false | redirect to URL on success/pending |
cancelUrl | string | false | redirect to URL on cancel |
errorUrl | string | false | redirect to URL on error |
callbackUrl | string | false | endpoint to receive status notifications |
transactionToken | string | false | token generated via payment.js |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
withRegister | boolean | false | store customer's payment instrument for recurring transactions |
transactionIndicator | string | false | SINGLE , INITIAL , RECURRING , CARDONFILE , CARDONFILE-MERCHANT-INITIATED or MOTO |
customer | object | false | see Customer |
↳customer.paymentData | object | false | one of PaymentData |
schedule | object | false | see Schedule |
customerProfileData | object | false | see CustomerProfileData |
threeDSecureData | object | false | see ThreeDSecureData |
l2l3Data | object | false | see L2L3Data |
language | string | false | 2 characters (lowercase) |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/preauthorize', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Preauthorize reserves the payment amount on the customer's payment instrument.
Depending on the payment method you have up to 7 days until you must Capture the transaction before the authorization expires.
POST /transaction/{apiKey}/preauthorize
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0002",
"additionalId1": "x0001",
"additionalId2": "y0001",
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"merchantMetaData": "merchantRelevantData",
"amount": "9.99",
"surchargeAmount": "0.9",
"currency": "EUR",
"successUrl": "https://example.com/success",
"cancelUrl": "https://example.com/cancel",
"errorUrl": "https://example.com/error",
"callbackUrl": "https://example.com/callback",
"description": "Example Product",
"customer": {
"identification": "c0001",
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-10-10",
"gender": "M",
"billingAddress1": "Maple Street 1",
"billingAddress2": "Syrup Street 2",
"billingCity": "Victoria",
"billingPostcode": "V8W",
"billingState": "British Columbia",
"billingCountry": "CA",
"billingPhone": "1234567890",
"shippingFirstName": "John",
"shippingLastName": "Doe",
"shippingCompany": "Big Company Inc.",
"shippingAddress1": "Yellow alley 3",
"shippingAddress2": "Yellow alley 4",
"shippingCity": "Victoria",
"shippingPostcode": "V8W",
"shippingState": "British Columbia",
"shippingCountry": "CA",
"shippingPhone": "1234567890",
"company": "John's Maple Syrup",
"email": "[email protected]",
"emailVerified": false,
"ipAddress": "127.0.0.1",
"nationalId": "123123",
"extraData": {
"someCustomerDataKey": "value",
"anotherKey": "anotherValue"
},
"paymentData": {
"ibanData": {
"iban": "AT123456789012345678",
"bic": "ABC",
"mandateId": "1234",
"mandateDate": "2019-09-29"
}
}
},
"threeDSecureData": {
"3dsecure": "MANDATORY"
},
"language": "en"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
amount | string | true | decimals separated by . , max. 3 decimals |
surchargeAmount | string | false | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
captureInMinutes | string | false | full minutes without decimals |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
referenceUuid | string | false | UUID of an initial transaction |
successUrl | string | false | redirect to URL on success/pending |
cancelUrl | string | false | redirect to URL on cancel |
errorUrl | string | false | redirect to URL on error |
callbackUrl | string | false | endpoint to receive status notifications |
transactionToken | string | false | token generated via payment.js |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
withRegister | boolean | false | store customer's payment instrument for recurring transactions |
transactionIndicator | string | false | SINGLE , INITIAL , RECURRING , CARDONFILE , CARDONFILE-MERCHANT-INITIATED or MOTO |
customer | object | false | see Customer |
↳customer.paymentData | object | false | one of PaymentData |
schedule | object | false | see Schedule |
customerProfileData | object | false | see CustomerProfileData |
threeDSecureData | object | false | see ThreeDSecureData |
l2l3Data | object | false | see L2L3Data |
language | string | false | 2 characters (lowercase) |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/capture', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/capture \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/capture");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/capture");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/capture', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/capture', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/capture", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/capture', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Capture completes the payment which was previously authorized with the Preauthorize method.
Depending on the payment method you can even capture only a partial amount of the authorized amount.
POST /transaction/{apiKey}/capture
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0003",
"referenceUuid": "bcdef23456bcdef23456",
"amount": "9.99",
"currency": "EUR"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
amount | string | true | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
referenceUuid | string | true | UUID of a preauthorize |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
l2l3Data | object | false | see L2L3Data |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/void', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/void \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/void");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/void");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/void', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/void', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/void", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/void', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Void cancels a previously performed authorization made with the Preauthorize method.
POST /transaction/{apiKey}/void
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Body parameter
{
"merchantTransactionId": "2019-09-02-0004",
"referenceUuid": "bcdef23456bcdef23456"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
referenceUuid | string | true | UUID of a preauthorized transaction |
amount | string | false | if supported by the adapter this will execute a partial void, decimals separated by . |
currency | string | false | 3 letter currency code |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/register', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/register \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/register");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/register");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/register', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/register', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/register", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/register', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Registers a customer's payment instrument for future charges (Debits or Preauthorizations)
POST /transaction/{apiKey}/register
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Example request body
{
"merchantTransactionId": "2019-09-02-0005",
"additionalId1": "x0001",
"additionalId2": "y0001",
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"merchantMetaData": "merchantRelevantData",
"successUrl": "https://example.com/success",
"cancelUrl": "https://example.com/cancel",
"errorUrl": "https://example.com/error",
"callbackUrl": "https://example.com/callback",
"customer": {
"identification": "c0001",
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-10-10",
"gender": "M",
"billingAddress1": "Maple Street 1",
"billingAddress2": "Syrup Street 2",
"billingCity": "Victoria",
"billingPostcode": "V8W",
"billingState": "British Columbia",
"billingCountry": "CA",
"billingPhone": "1234567890",
"shippingFirstName": "John",
"shippingLastName": "Doe",
"shippingCompany": "Big Company Inc.",
"shippingAddress1": "Yellow alley 3",
"shippingAddress2": "Yellow alley 4",
"shippingCity": "Victoria",
"shippingPostcode": "V8W",
"shippingState": "British Columbia",
"shippingCountry": "CA",
"shippingPhone": "1234567890",
"company": "John's Maple Syrup",
"email": "[email protected]",
"emailVerified": false,
"ipAddress": "127.0.0.1",
"nationalId": "123123",
"extraData": {
"someCustomerDataKey": "value",
"anotherKey": "anotherValue"
},
"paymentData": {
"ibanData": {
"iban": "AT123456789012345678",
"bic": "ABC",
"mandateId": "1234",
"mandateDate": "2019-09-29"
}
}
},
"description": "This is a register",
"language": "en"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
successUrl | string | false | redirect to URL on success/pending |
cancelUrl | string | false | redirect to URL on cancel |
errorUrl | string | false | redirect to URL on error |
callbackUrl | string | false | endpoint to receive status notifications |
transactionToken | string | false | token generated via payment.js |
description | string | false | max. 255 characters |
customer | object | false | see Customer |
↳customer.paymentData | object | false | one of PaymentData |
schedule | object | false | see Schedule |
customerProfileData | object | false | see CustomerProfileData |
threeDSecureData | object | false | see ThreeDSecureData |
l2l3Data | object | false | see L2L3Data |
language | string | false | 2 characters (lowercase) |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/deregister', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Deregister deletes a previously registered payment instrument using Register.
POST /transaction/{apiKey}/deregister
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0006",
"merchantMetaData": "merchantRelevantData",
"referenceUuid": "bcdef23456bcdef23456"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
referenceUuid | string | true | UUID of a register, debit-with-register or preauthorize-with-register |
tokenType | string | false | ALL , PAN , NT Which token type should be deregistered. Default ALL |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/refund', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/refund \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/refund");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/refund");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/refund', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/refund', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/refund", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/refund', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Refund reverses a payment which was previously performed with Debit or Capture.
Depending on the payment method you can even refund only a partial amount of the original transaction amount.
POST /transaction/{apiKey}/refund
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0007",
"referenceUuid": "bcdef23456bcdef23456",
"amount": "9.99",
"currency": "EUR",
"callbackUrl": "https://example.com/callback",
"description": "Refund money"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
amount | string | true | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
referenceUuid | string | true | UUID of a debit or capture |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
callbackUrl | string | false | endpoint to receive status notifications |
transactionToken | string | false | token generated via payment.js |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/payout', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/payout \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/payout");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/payout");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/payout', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/payout', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/payout", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/payout', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
A Payout credits the customer's account with the given amount.
Depending on the connector, either referenceUuid
or cardData
will be required.
POST /transaction/{apiKey}/payout
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0008",
"amount": "9.99",
"currency": "EUR",
"callbackUrl": "https://example.com/callback",
"transactionToken": "ix::a1A2B3b4c5C6D7d",
"description": "Payout"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
amount | string | true | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
referenceUuid | string | conditional | UUID of an initial transaction |
transactionToken | string | conditional | token generated via payment.js |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
successUrl | string | false | redirect to URL on success/pending |
cancelUrl | string | false | redirect to URL on cancel |
errorUrl | string | false | redirect to URL on error |
callbackUrl | string | false | endpoint to receive status notifications |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
customer | object | false | see Customer |
↳customer.paymentData | object | false | one of PaymentData |
language | string | false | 2 characters (lowercase) |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorization", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/transaction/{apiKey}/incrementalAuthorizationincrementalAuthorization', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
An incremental authorization increases the authorized amount on the customer's payment instrument.
Currently, the incremental authorization is only supported by a few adapters.
A following capture
transaction may capture the full amount of the initial
transaction and all its subsequent incremental authorizations.
Note: The capture transaction must refer to the initial preauthorize!
POST /transaction/{apiKey}/incrementalAuthorization
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"merchantTransactionId": "2019-09-02-0002",
"referenceUuid": "bcdef23456bcdef23456",
"additionalId1": "x0001",
"additionalId2": "y0001",
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"merchantMetaData": "merchantRelevantData",
"amount": "9.99",
"currency": "EUR",
"successUrl": "https://example.com/success",
"cancelUrl": "https://example.com/cancel",
"errorUrl": "https://example.com/error",
"callbackUrl": "https://example.com/callback",
"description": "Example Product",
"language": "en"
}
Name | Type | Required | Description |
---|---|---|---|
merchantTransactionId | string | true | your unique transaction ID |
referenceUuid | string | true | UUID of the initial preauthorize |
amount | string | true | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
additionalId1 | string | false | any additional ID if required by adapter |
additionalId2 | string | false | any additional ID if required by adapter |
extraData | object | false | object containing key-value pairs (string-to-string) |
merchantMetaData | string | false | max. 255 characters |
successUrl | string | false | redirect to URL on success/pending |
cancelUrl | string | false | redirect to URL on cancel |
errorUrl | string | false | redirect to URL on error |
callbackUrl | string | false | endpoint to receive status notifications |
transactionToken | string | false | token generated via payment.js |
description | string | false | max. 255 characters |
items | object | false | object containing Items |
l2l3Data | object | false | see L2L3Data |
language | string | false | 2 characters (lowercase) |
Example responses
finished
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
redirect
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "REDIRECT",
"redirectUrl": "https://redirectComesUrlHere.com",
"paymentMethod": "Creditcard"
}
errors
{
"success": false,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "ERROR",
"paymentMethod": "Creditcard",
"errors": [
{
"errorMessage": "Request failed",
"errorCode": 1000,
"adapterMessage": "Invalid parameters given",
"adapterCode": "1234"
}
],
"extraData": [
{
"remainingAmount": "5"
}
]
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
uuid | string | UUID of the transaction |
purchaseId | string | purchase ID of the transaction |
returnType | string | FINISHED , REDIRECT , HTML , PENDING , ERROR |
redirectType | string | iframe , fullpage , 3ds |
redirectUrl | string | where the customer must be redirected to |
redirectQRCode | string | QR Code with redirectUrl base64 encoded |
htmlContent | string | |
paymentDescriptor | string | |
paymentMethod | string | payment method used (if already determined) |
returnData | object | containing one of ReturnData |
scheduleData | object | see ScheduleData |
customerProfileData | object | see CustomerProfileData |
riskCheckData | object | see RiskCheckData |
extraData | object | object containing key-value pairs (string-to-string) |
extraData.remainingAmount | object | remaining amount of capture/ refund |
errors | object | contains transaction errors, see TransactionResponseError |
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. (deprecated, please see PayByLinkData) |
payByLinkData | object | see PayByLinkData |
As response to the API call the gateway answers with a response containing the status and further instructions.
Generally there are 4 possible results:
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20190927-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "Creditcard"
}
The transaction completed and was processed successfully. You can deliver the ordered goods.
{
"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
.
{
"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.
{
"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.
Example
{
"customer": {
"identification": "c0001",
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-10-10",
"gender": "M",
"billingAddress1": "Maple Street 1",
"billingAddress2": "Syrup Street 2",
"billingCity": "Victoria",
"billingPostcode": "V8W",
"billingState": "British Columbia",
"billingCountry": "CA",
"billingPhone": "1234567890",
"shippingFirstName": "John",
"shippingLastName": "Doe",
"shippingCompany": "Big Company Inc.",
"shippingAddress1": "Yellow alley 3",
"shippingAddress2": "Yellow alley 4",
"shippingCity": "Victoria",
"shippingPostcode": "V8W",
"shippingState": "British Columbia",
"shippingCountry": "CA",
"shippingPhone": "1234567890",
"company": "John's Maple Syrup",
"email": "[email protected]",
"emailVerified": false,
"ipAddress": "127.0.0.1",
"nationalId": "123123",
"extraData": {
"someCustomerDataKey": "value",
"anotherKey": "anotherValue"
}
}
}
Name | Type | Required | Description |
---|---|---|---|
identification | string | false | max. 36 characters |
firstName | string | false | max. 50 characters |
lastName | string | false | max. 50 characters |
birthDate | string | false | YYYY-MM-DD |
gender | string | false | M , F |
billingAddress1 | string | false | max. 50 characters |
billingAddress2 | string | false | max. 50 characters |
billingCity | string | false | max. 50 characters |
billingPostcode | string | false | max. 16 characters |
billingState | string | false | max. 30 characters |
billingCountry | string | false | 2-letter country code |
billingPhone | string | false | max. 20 characters |
shippingFirstName | string | false | max. 50 characters |
shippingLastName | string | false | max. 50 characters |
shippingCompany | string | false | max. 50 characters |
shippingAddress1 | string | false | max. 50 characters |
shippingAddress2 | string | false | max. 50 characters |
shippingCity | string | false | max. 50 characters |
shippingPostcode | string | false | max. 16 characters |
shippingState | string | false | max. 30 characters |
shippingCountry | string | false | 2-letter country code |
shippingPhone | string | false | max. 20 characters |
company | string | false | max. 50 characters |
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 |
Name | Type | Required | Description |
---|---|---|---|
profileGuid | string | conditional | |
customerIdentification | string | conditional | |
markAsPreferred | boolean | false | mark payment instrument as preferred |
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) |
Name | Type | Required | Description |
---|---|---|---|
l2l3Data.taxAmount | float | false | |
l2l3Data.vatRegistrationNumber | string | false | |
l2l3Data.nationalTaxIncluded | string | false | |
l2l3Data.discountAmount | float | false | |
l2l3Data.commodityCode | string | false | |
l2l3Data.freightAmount | float | false | |
l2l3Data.freightTaxAmount | float | false | |
l2l3Data.dutyAmount | float | false | |
l2l3Data.taxDetails[].type | string | false | |
l2l3Data.taxDetails[].amount | float | false | |
l2l3Data.taxDetails[].rate | float | false | |
l2l3Data.taxDetails[].code | string | false | |
l2l3Data.taxDetails[].code | string | false | |
l2l3Data.taxDetails[].applied | string | false | |
l2l3Data.taxDetails[].exemptionCode | string | false |
Name | Type | Required | Description |
---|---|---|---|
items[].l2l3Data.type | string | false | |
items[].l2l3Data.commodityCode | string | false | |
items[].l2l3Data.unit | string | false | |
items[].l2l3Data.unitPrice | float | false | |
items[].l2l3Data.discount | float | false | |
items[].l2l3Data.shippingAmount | int | false | |
items[].l2l3Data.taxAmount | float | false | |
items[].l2l3Data.taxRate | float | false | |
items[].l2l3Data.taxRate | float | false | |
items[].l2l3Data.taxDetails[].type | string | false | |
items[].l2l3Data.taxDetails[].amount | float | false | |
items[].l2l3Data.taxDetails[].rate | float | false | |
items[].l2l3Data.taxDetails[].code | string | false | |
items[].l2l3Data.taxDetails[].code | string | false | |
items[].l2l3Data.taxDetails[].applied | string | false | |
items[].l2l3Data.taxDetails[].exemptionCode | string | false |
Name | Type | Required | Description |
---|---|---|---|
sendByEmail | boolean | true | Indicates whether a payment link should be sent to the customer. If false provided, it means the payment link will not be sent to the customer via email. |
expirationInMinute | number | false | Set an expiration time of the payment link in minutes. |
Example
{
"payByLink": {
"sendByEmail": false,
"expirationInMinute" : 5
}
}
Name | Type | Description |
---|---|---|
expiresAt | string | Indicates at what date time the pay-by-link transaction expires. |
cancelUrl | string | Endpoint to call to cancel a pay-by-link transaction. |
Example
{
"payByLinkData": {
"expiresAt": "2023-08-21 14:13:02 UTC",
"cancelUrl": "https://gateway.ixopay.com/api/v3/payByLink/6ba2b0e0d02ac342cc41/cancel"
}
}
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 |
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 |
Example cardData
{
"_TYPE": "cardData",
"type": "visa",
"cardHolder": "John Doe",
"expiryMonth": 12,
"expiryYear": 2020,
"binDigits": "12345678",
"firstSixDigits": "123456",
"lastFourDigits": "4321",
"fingerprint": "s0mEF1n6eRpr1n7",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "SOME BANK",
"binCountry": "US"
}
Name | Type | Description |
---|---|---|
_TYPE | string | will contain value cardData |
type | string | type of credit card |
firstName | string | |
lastName | string | |
country | string | |
cardHolder | string | |
expiryMonth | number | MM |
expiryYear | number | YYYY |
binDigits | string | |
firstSixDigits | string | |
lastFourDigits | string | |
fingerprint | string | |
binBrand | string | |
binBank | string | |
binType | string | |
binLevel | string | |
binCountry | string | |
threeDSecure | string | |
eci | string | |
merchantAdviceCode | string | pipes through the merchant advice code for failed transactions if supported by the adapter |
parsedMerchantAdviceCode | string | parsed merchant advice code for failed transactions if supported by the adapter |
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 |
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 |
Example walletData
{
"_TYPE": "walletData",
"walletReferenceId": "1234567890",
"walletOwner": "John Doe",
"walletType": "someType",
"walletOwnerFirstName": "Max",
"walletOwnerLastName": "Mustermann",
"walletOwnerCountryCode": "DE",
"walletRegistrationId": "reg157ra710N1D"
}
Name | Type | Description |
---|---|---|
_TYPE | string | will contain value walletData |
walletReferenceId | string | Reference ID |
walletOwner | string | Wallet Owner |
walletType | string | Wallet Type |
walletOwnerFirstName | string | Owner First Name |
walletOwnerLastName | string | Owner Last Name |
walletOwnerCountryCode | string | Owner Country Code |
walletRegistrationId | string | Registration ID |
Name | Type | Description |
---|---|---|
riskCheckResult | string | APPROVED , DECLINED , REVIEW |
riskScore | number | |
threeDSecureRequired | boolean |
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 |
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 |
Name | Type |
---|---|
message | string |
code | number |
adapterMessage | string |
adapterCode | string |
Name | Type |
---|---|
errorMessage | string |
errorCode | number |
adapterMessage | string |
adapterCode | string |
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": {
"3dsecure": "MANDATORY",
"channel": "01",
"authenticationIndicator": "01" ,
"cardholderAuthenticationMethod": "01" ,
"cardholderAuthenticationDateTime": "2020-01-01 12:00",
...
}
}
Name | Type | Required | Accepted values |
---|---|---|---|
3dsecure Triggers the 3D Secure authentication for this transaction |
string | false | OFF , OPTIONAL , MANDATORY |
schemeId "Pin" the scheme ID in case of a co-branded card. Currently, there is only CB supported. |
string | false | CB |
channel Indicates the type of channel interface being used to initiate the transaction 01 -> App-based 02 -> Browser 03 -> 3DS Requestor Initiated |
string | false | 01 , 02 , 03 |
authenticationIndicator Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request. 01 -> Payment transaction 02 -> Recurring transaction 03 -> Installment transaction 04 -> Add card 05 -> Maintain card 06 -> Cardholder verification as part of EMV token ID&V |
string | false | 01 , 02 , 03 |
cardholderAuthenticationMethod Mechanism used by the Cardholder to authenticate to the 3DS Requestor. 01 -> No 3DS Requestor authentication occurred (i.e. cardholder "logged in" as guest) 02 -> Login to the cardholder account at the 3DS Requestor system using 3DS Requestor's own credentials 03 -> Login to the cardholder account at the 3DS Requestor system using federated ID 04 -> Login to the cardholder account at the 3DS Requestor system using issuer credentials 05 -> Login to the cardholder account at the 3DS Requestor system using third-party authentication 06 -> Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator |
string | false | 01 , 02 , 03 , 04 , 05 , 06 |
cardholderAuthenticationDateTime Date and time in UTC of the cardholder authentication. Format: YYYY-MM-DD HH:mm Example: 2019-05-12 18:34 |
string | false | YYYY-MM-DD HH:MM |
cardHolderAuthenticationData Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. |
string | false | |
challengeIndicator Indicates whether a challenge is requested for this transaction. For example: For 01-PA, a 3DS Requestor may have concerns about the transaction, and request a challenge. 01 -> No preference 02 -> No challenge requested 03 -> Challenge requested: 3DS Requestor Preference 04 -> Challenge requested: Mandate 05 -> No challenge requested (transactional risk analysis is already performed) 06 -> No challenge requested (Data share only) 07 -> No challenge requested (strong consumer authentication is already performed) 08 -> No challenge requested (utilise whitelist exemption if no challenge required) 09 -> Challenge requested (whitelist prompt requested if challenge required) |
string | false | 01 , 02 , 03 , 04 , 05 , 06 , 07 , 08 , 09 |
priorReference This data element provides additional information to the ACS to determine the best approach for handling a request. The field is limited to 36 characters containing ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder). |
string | false | |
priorAuthenticationMethod Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. 01 -> Frictionless authentication occurred by ACS 02 -> Cardholder challenge occurred by ACS 03 -> AVS verified 04 -> Other issuer methods |
string | false | 01 , 02 , 03 , 04 |
priorAuthenticationDateTime Date and time in UTC of the prior authentication. Format: YYYY-MM-DD HH:mm Example: 2019-05-12 18:34 |
string | false | YYYY-MM-DD HH:MM |
priorAuthenticationData Data that documents and supports a specific authentication process. In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versions of the application, these details are expected to be included. Field is limited to maximum 2048 characters. |
string | false | |
cardholderAccountType Indicates the type of account. For example, for a multi-account card product. 01 -> Not applicable 02 -> Credit 03 -> Debit 04 -> JCB specific value for Prepaid |
string | false | 01 , 02 , 03 , 04 |
cardholderAccountAgeIndicator Length of time that the cardholder has had the account with the 3DS Requestor. 01 -> No account (guest check-out) 02 -> During this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days |
string | false | 01 , 02 , 03 , 04 , 05 |
cardholderAccountDate Date that the cardholder opened the account with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12 |
string | false | YYYY-MM-DD |
cardholderAccountChangeIndicator Length of time since the cardholder’s account information with the 3DS Requestor was last changed. Includes Billing or Shipping address, new payment account, or new user(s) added. 01 -> Changed during this transaction 02 -> Less than 30 days 03 -> 30 - 60 days 04 -> More than 60 days |
string | false | 01 , 02 , 03 , 04 |
cardholderAccountLastChange Date that the cardholder’s account with the 3DS Requestor was last changed. Including Billing or Shipping address, new payment account, or new user(s) added. Format: YYYY-MM-DD Example: 2019-05-12 |
string | false | YYYY-MM-DD |
cardholderAccountPasswordChangeIndicator Length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. 01 -> No change 02 -> Changed during this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days |
string | false | 01 , 02 , 03 , 04 , 05 |
cardholderAccountLastPasswordChange Date that cardholder’s account with the 3DS Requestor had a password change or account reset. Format: YYYY-MM-DD Example: 2019-05-12 |
string | false | YYYY-MM-DD |
shippingAddressUsageIndicator Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 01 -> This transaction 02 -> Less than 30 days 03 -> 30 - 60 days 04 -> More than 60 days. |
string | false | 01 , 02 , 03 , 04 |
shippingAddressFirstUsage Date when the shipping address used for this transaction was first used with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12 |
string | false | YYYY-MM-DD |
transactionActivityDay Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. |
number | false | |
transactionActivityYear Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. |
number | false | |
addCardAttemptsDay Number of Add Card attempts in the last 24 hours. |
number | false | |
purchaseCountSixMonths Number of purchases with this cardholder account during the previous six month |
number | false | |
suspiciousAccountActivityIndicator Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. 01 -> No suspicious activity has been observed 02 -> Suspicious activity has been observed |
string | false | 01 , 02 |
shippingNameEqualIndicator Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 01 -> Account Name identical to shipping Name 02 -> Account Name different than shipping Name |
string | false | 01 , 02 |
paymentAccountAgeIndicator Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. 01 -> No account (guest check-out) 02 -> During this transaction 03 -> Less than 30 days 04 -> 30 - 60 days 05 -> More than 60 days |
string | false | 01 , 02 , 03 , 04 , 05 |
paymentAccountAgeDate Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Format: YYYY-MM-DD Example: 2019-05-12 |
string | false | YYYY-MM-DD |
billingAddressLine3 Line 3 of customer's billing address |
string | false | |
shippingAddressLine3 Line 3 of customer's shipping address |
string | false | |
billingAddressState Customer's billing state (country subdivision code ISO 3166-2) max. 3 characters |
string | false | |
shippingAddressState Customer's shipping state (country subdivision code ISO 3166-2) max. 3 characters |
string | false | |
billingShippingAddressMatch Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same. Y -> Shipping Address matches Billing Address N -> Shipping Address does not match Billing Address |
string | false | Y , N |
homePhoneCountryPrefix Country Code of the home phone, limited to 1-3 characters |
string | false | |
homePhoneNumber subscriber section of the number, limited to maximum 15 characters. |
string | false | |
mobilePhoneCountryPrefix Country Code of the mobile phone, limited to 1-3 characters |
string | false | |
mobilePhoneNumber subscriber section of the number, limited to maximum 15 characters. |
string | false | |
workPhoneCountryPrefix Country Code of the work phone, limited to 1-3 characters |
string | false | |
workPhoneNumber subscriber section of the number, limited to maximum 15 characters. |
string | false | |
purchaseInstalData Indicates the maximum number of authorisations permitted for instalment payments. The field is limited to maximum 3 characters and value shall be greater than 1. The fields is required if the Merchant and Cardholder have agreed to installment payments, i.e. if 3DS Requestor Authentication Indicator = 03. Omitted if not an installment payment authentication. |
number | false | |
shipIndicator Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the code that describes the most expensive item. 01 -> Ship to cardholder's billing address 02 -> Ship to another verified address on file with merchant 03 -> Ship to address that is different than the cardholder's billing address 04 -> "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields) 05 -> Digital goods (includes online services, electronic gift cards and redemption codes) 06 -> Travel and Event tickets, not shipped 07 -> Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.) |
string | false | 01 , 02 , 03 , 04 , 05 , 06 , 07 |
deliveryTimeframe Indicates the merchandise delivery timeframe. 01 -> Electronic Delivery 02 -> Same day shipping 03 -> Overnight shipping 04 -> Two-day or more shipping |
string | false | 01 , 02 , 03 , 04 |
deliveryEmailAddress For electronic delivery, the email address to which the merchandise was delivered. |
string | false | |
reorderItemsIndicator Indicates whether the cardholder is reordering previously purchased merchandise. 01 -> First time ordered 02 -> Reordered |
string | false | 01 , 02 |
preOrderPurchaseIndicator Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. 01 -> Merchandise available 02 -> Future availability |
string | false | 01 , 02 |
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available. Format: YYYY-MM-DD |
string | false | YYYY-MM-DD |
giftCardAmount For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). |
number | false | |
giftCardCurrency For prepaid or gift card purchase, the currency code of the card |
string | false | |
giftCardCount For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. Field is limited to 2 characters. |
number | false | |
purchaseDate Date and time of the purchase, expressed in UTC. Format: YYYY-MM-DD HH:mm:ss **Note: if omitted we put in today's date |
string | false | YYYY-MM-DD HH:MM |
recurringExpiry Date after which no further authorizations shall be performed. This field is required for 01-PA and for 02-NPA, if 3DS Requestor Authentication Indicator = 02 or 03. Format: YYYY-MM-DD |
string | false | YYYY-MM-DD |
recurringFrequency Indicates the minimum number of days between authorizations. The field is limited to maximum 4 characters. This field is required if 3DS Requestor Authentication Indicator = 02 or 03. |
number | false | |
transType Identifies the type of transaction being authenticated. The values are derived from ISO 8583. 01 -> Goods / Service purchase 03 -> Check Acceptance 10 -> Account Funding 11 -> Quasi-Cash Transaction 28 -> Prepaid activation and Loan |
string | false | 01 , 03 , 10 , 11 , 28 |
threeRIIndicator Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handling a 3RI request. Possible values are: 01 -> Recurring transaction 02 -> Installment transaction 03 -> Add card 04 -> Maintain card information 05 -> Account verification. 06 -> Split/delayed shipment 07 -> Top-up 08 -> Mail order 09 -> Telephone order 10 -> Whitelist status check 11 -> Other payment 12 -> Billing agreement. |
string | false | 01 , 02 , 03 , 04 , 05 , 06 , 07 , 08 , 09 , 10 , 11 , 12 |
exemptionIndicator Requests an SCA exemption for this transaction. Possible values are: 01 -> Low Value Transaction (amount under 30 EUR) 02 -> Low Risk Transaction 03 -> Whitelisted transaction, merchant is added as "Trusted Beneficiary" by cardholder 04 -> Secure Corporate Payment 05 -> Recurring or Merchant-initiated transaction 06 -> Mail or Telephone Order 07 -> Anonymous payment card |
string | false | 01 , 02 , 03 , 04 , 05 , 06 , 07 |
For 3DS v2, the device data below are mandatory. Transaction will not succeed if either all browser or all SDK parameters are provided.
{
...
"threeDSecureData": {
"browserChallengeWindowSize": "04",
"browserAcceptHeader": "*/*",
"browserIpAddress": "127.0.0.1",
"browserJavaEnabled": false,
"browserLanguage": "en-GB",
"browserColorDepth": "24",
"browserScreenHeight": 1080,
"browserScreenWidth": 1920,
"browserTimezone": -60,
"browserUserAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.21 Safari/537.12",
...
}
}
The following fields are filled automatically by the Gateway if you are using hosted payment pages or payment.js integration. For any other integration flow you will need to provide them:
Name | Type | Accepted values |
---|---|---|
browserChallengeWindowSize Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. 01 -> 250 x 400 02 -> 390 x 400 03 -> 500 x 600 04 -> 600 x 400 05 -> Full screen |
string | 01 , 02 , 03 , 04 , 05 |
browserAcceptHeader Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder's browser |
string | |
browserIpAddress IP address of the browser as returned by the HTTP headers to the 3DS Requestor. - IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255 - IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334 |
string | |
browserJavaEnabled Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. |
boolean | |
browserLanguage Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters. Value is returned from navigator.language property. |
string | |
browserColorDepth Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. 1 -> 1 bit 4 -> 4 bits 8 -> 8 bits 15 -> 15 bits 16 -> 16 bits 24 -> 24 bits 32 -> 32 bits 48 -> 48 bits |
string | 1 , 4 , 8 , 15 , 16 , 24 , 32 , 48 |
browserScreenHeight Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property. |
number | |
browserScreenWidth Total width of the Cardholder's screen in pixels. Value is returned from the screen.width property. |
number | |
browserTimezone Time difference between UTC time and the Cardholder browser local time, in minutes. The field is limited to 1-5 characters where the value is returned from the getTimezoneOffset() method. |
number | |
browserUserAgent Exact content of the HTTP user-agent header. The field is limited to maximum 2048 characters. |
string |
Name | Type | Accepted values |
---|---|---|
sdkInterface Specifies all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values are: 01 -> Native 02 -> HTML 03 -> Both |
string | 01 , 02 , 03 |
sdkUiType Contains a comma-separated list of all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Accepted values for each UI type are: 01 -> Text 02 -> Single select 03 -> Multi select 04 -> OOB 05 -> Html Other (valid only for HTML UI) E.g. 01,02,05 |
string | comma-separated list with values: 01 , 02 , 03 , 04 , 05 |
sdkAppID Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Customer Device. |
string | |
sdkEncData JWE Object as defined 3DS Specs Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt. |
string | |
sdkEphemPubKey Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS The value should be a JSON string containing the keys kty , crv , x , y , e.g. {"kty":"EC","crv":"P-256","x":"...","y":"..."} |
string | |
sdkMaxTimeout Indicates the maximum amount of time (in minutes) for all exchanges. The field shall have value greater than or equal to 05. |
number | |
sdkReferenceNumber Identifies the vendor and version of the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved. The field is limited to 32 characters. |
string | |
sdkTransID Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. |
string |
Those extra data fields are mapped to the corresponding Forter Validation Request Parameters: https://portal.forter.com/app/developer/api/api/services-and-apis/validation-api#request
Example
{
"customer": {
"identification": "c0001",
"extraData": {
"FORTER_CUSTOMER_LAST_LOGINIP": "203.12.55.12",
"FORTER_CUSTOMER_BILLING_ADDRESS_TYPE": "HOME",
...
},
...
}
}
Name | Type | Example values |
---|---|---|
FORTER_CUSTOMER_PAST_ORDERS_COUNT |
optional integer | 0 |
FORTER_CUSTOMER_PAST_ORDERS_SUM_USD |
optional decmimal | 0.00 |
FORTER_CUSTOMER_LAST_LOGINIP |
string | 203.12.55.12 |
FORTER_CUSTOMER_REGISTRATION_IP |
string | 203.12.55.12 |
FORTER_CUSTOMER_BILLING_ADDRESS_TYPE conditional Possible values are: "HOME", "BUSINESS", "OTHER" |
string | HOME |
FORTER_CUSTOMER_BILLING_CREATION_TIME conditional Time item was first entered by customer in seconds since unix epoch (UTC, Jan 1, 1970) |
number | 1448549922 |
FORTER_CUSTOMER_BILLING_REMOVAL_TIME conditional Time item was removed by customer in seconds since unix epoch (UTC, Jan 1, 1970) |
number | 1448895522 |
FORTER_CUSTOMER_BILLING_SUGGESTED_CORRECT_ADDRESS conditional True if customer selected a corrected address suggested by merchant (For example in cases where customer entered wrong zipcode) |
boolean | 0/1 |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_TYPE required ype of document (Passport, ID, Driving license) Maximum length is 35 characters. |
string | Passport |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_SOURCE required Source of document (e.g. uploaded file, captured by camera, typed in by customer, etc.) Possible values are: "CAMERA_CAPTURED", "UPLOADED_FILE", "TYPED", "OTHER" |
string | UPLOADED_FILE |
FORTER_CUSTOMER_BILLING_VERIFICATION_NATIONALITY conditional Document holder's nationality |
string | US |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_ISSUING_STATE conditional Document issuing state or region |
string | NY |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_NUMBER conditional Official document's number (e.g. passport number, driving license number, etc.) |
string | 20439190 |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_FIRSTNAME conditional First name as appears on the document |
string | John |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_LASTNAME conditional Last name as appears on the document |
string | Smith |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_DATEOFBIRTH conditional Date of birth as appears on the document. Use YYYY-MM-DD format. |
string | 1982-04-23 |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_EXPIRATION conditional Document's expiration date. Use YYYY-MM-DD format. |
string | 2025-04-23 |
FORTER_CUSTOMER_BILLING_VERIFICATION_DOCUMENT_PAYLOAD conditional JSON Response payload received from 3rd party document verification |
string JSON | {} |
FORTER_CUSTOMER_SHIPPING_ADDRESS_TYPE conditional Possible values are: "HOME", "BUSINESS", "OTHER" |
string | HOME |
FORTER_CUSTOMER_SHIPPING_CREATION_TIME conditional Time item was first entered by customer in seconds since unix epoch (UTC, Jan 1, 1970) |
number | 1448549922 |
FORTER_CUSTOMER_SHIPPING_REMOVAL_TIME conditional Time item was removed by customer in seconds since unix epoch (UTC, Jan 1, 1970) |
number | 1448895522 |
FORTER_CUSTOMER_SHIPPING_SUGGESTED_CORRECT_ADDRESS conditional True if customer selected a corrected address suggested by merchant (For example in cases where customer entered wrong zipcode) |
boolean | 0/1 |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_TYPE required ype of document (Passport, ID, Driving license) Maximum length is 35 characters. |
string | Passport |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_SOURCE required Source of document (e.g. uploaded file, captured by camera, typed in by customer, etc.) Possible values are: "CAMERA_CAPTURED", "UPLOADED_FILE", "TYPED", "OTHER" |
string | UPLOADED_FILE |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_NATIONALITY conditional Document holder's nationality |
string | US |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_ISSUING_STATE conditional Document issuing state or region |
string | NY |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_NUMBER conditional Official document's number (e.g. passport number, driving license number, etc.) |
string | 20439190 |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_FIRSTNAME conditional First name as appears on the document |
string | John |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_LASTNAME conditional Last name as appears on the document |
string | Smith |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_DATEOFBIRTH conditional Date of birth as appears on the document. Use YYYY-MM-DD format. |
string | 1982-04-23 |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_EXPIRATION conditional Document's expiration date. Use YYYY-MM-DD format. |
string | 2025-04-23 |
FORTER_CUSTOMER_SHIPPING_VERIFICATION_DOCUMENT_PAYLOAD conditional JSON Response payload received from 3rd party document verification |
string JSON | {} |
Name | Type | Example values |
---|---|---|
FORTER_TYPE optional, default WEB. Platform order was made through. Possible Values: "WEB", "PHONE", "MOBILE", "IOS", "ANDROID", "WAP", "STORE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "UNKNOWN" |
string | WEB |
FORTER_TOKEN conditional Forter token cookie from request headers. Maximum length is 128 characters. |
string | 2315688945984 |
FORTER_USER_AGENT required when PaymentJS is not used, Customer's User agent. Maximum length is 4096 characters. |
string | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36 |
FORTER_CHECKOUT_TIME optional will use current timestamp if not provided. The time when the buyer completed the checkout process in the merchant website in SECONDS since unix epoch (Jan 1, 1970). |
number | 1415273168 |
FORTER_MOBILE_UID optional - mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API (for mobile transactions only) Maximum length is 128 characters. |
string | 6429751237891 |
FORTER_MERCHANT_DEVICE_IDENTIFIER conditional - A unique device identifier generated by merchant |
string | HGJ7512345H3 |
FORTER_MOBILE_APP_VERSION conditional - The version of the merchant application which is running on the user's device |
string | 2.9 |
FORTER_MOBILE_OS_TYPE conditional - The operating system running on the user's device (relevant for native app only) |
string | Android |
FORTER_MOBILE_DEVICE_BRAND conditional - The user's device brand (relevant for native app only) |
string | Samsung |
FORTER_MOBILE_DEVICE_MODEL conditional - The model of the user's device (relevant for native app only) |
string | Galaxy 3 |
FORTER_FULL_HEADERS_JSON conditional - A unique device identifier generated by merchant |
string JSON | "{"method":"GET / HTTP/1.1", "Host": "forter.com", "Connection": "keep-alive", "Accept": ...}" |
FORTER_DELIVERY_DETAILS_DELIVERY_TYPE optional default PHYSICAL - Type of delivery: PHYSICAL for any type of shipped goods. DIGITAL for non-shipped goods (services, gift cards etc.) Example: PHYSICAL Possible values are: "DIGITAL", "PHYSICAL", "HYBRID" |
string | DIGITAL |
FORTER_DELIVERY_DETAILS_DELIVERY_METHOD optional default POSTAL SERVICE - Delivery method chosen by customer such as postal service, email, in game transfer, etc. Example: USPS - Ground Mail |
string | Galaxy |
FORTER_DELIVERY_DETAILS_DELAYED_DELIVERY_DATE conditional - Use if customer chose to deliver the item at a later date (to arrive in time for a holiday, a birthday, etc.). Use YYYY-MM-DD format. |
string | 2018-10-12 |
FORTER_DELIVERY_DETAILS_CARRIER optional - The delivery carrier |
string | DHL |
FORTER_DELIVERY_DETAILS_DELIVERY_PRICE_AMOUNT conditional - same currency as transaction currency is assumed |
string | 5.00 |
FORTER_DELIVERY_DETAILS_TRACKING_EXTRA_CHARGE_AMOUNT conditional - same currency as transaction currency is assumed |
string | 1.00 |
FORTER_DELIVERY_DETAILS_EXPECTED_DELIVERY_DATE conditional - Date delivery is expected to arrive at destination. Use YYYY-MM-DD |
string | 2018-10-14 |
FORTER_DELIVERY_DETAILS_LEAVE_OUTSIDE optional - 1 if customer chose to allow shipment to be left outside or at a building lobby or reception area. |
integer | 1 |
FORTER_DELIVERY_DETAILS_SMS_UPDATES optional - 1 if customer asked to receive SMS updates regarding delivery. |
integer | 0 |
FORTER_DELIVERY_DETAILS_WAIT_TO_SHIP_TOGETHER conditional - 1 if customer asked to try and bundle shipments together to save costs. |
integer | 1 |
FORTER_DELIVERY_DETAILS_DELIVERY_COMMENTS conditional - Any comments or requests customer had for delivery |
string | Please call before arriving, Thanks! |
FORTER_IS_MERCHANT_OF_RECORD conditional - 1 if the Forter account owner is also the merchant of record |
string | 1 |
FORTER_PAYMENT_METHOD_NICKNAME conditional - Nickname assigned to this payment method by the user |
string | My Work Card |
FORTER_PAYMENT_CREDIT_USED_AMOUNT conditional - Store credit used to pay for purchase |
string | 1.00 |
FORTER_IS_DEFAULT_PAYMENT_METHOD conditional - 1 if this payment instrument is the default set by the customer. |
integer | 0 |
FORTER_NUMBER_OF_INSTALLMENTS conditional - Number of payments if customer chose to pay in several installments. integer |
string | 12 |
FORTER_DELAYED_CHARGE conditional - 1 if customer chose to pay at a later date. False if customer chose to pay in several installments as long as first payment is immediate. |
integer | 0 |
FORTER_DELAYED_CHARGE_DATE conditional - Date customer is due to pay. Use YYYY-MM-DD format. |
string | 2015-12-01 |
FORTER_PAYMENT_GATEWAY_ID conditional - Transaction identifier provided by the payment gateway |
string | SDS34653246346 |
FORTER_MERCHANT_ID conditional - Merchant unique identifier |
string | eh629dK9 |
FORTER_MERCHANT_DOMAIN conditional - Use if merchant operates several sites (such as a regular site and a related discount brand) |
string | HandbagsExpressDiscounts.com |
FORTER_MERCHANT_NAME conditional - Use if merchant operates several sites (such as a regular site and a related discount brand) |
string | Handbags Express Discounts |
FORTER_SITE_LOCALIZATION_COUNTRY conditional - Use if site has multiple localized versions |
string | FR |
FORTER_SITE_LOCALIZATION_LANGUAGE conditional - Site interface language chosen by customer, 2-letter ISO-639-1 language code |
string | EN |
FORTER_SITE_LOCALIZATION_CURRENCY conditional - Currency chosen by customer as default, 3-letter ISO-4217 format currency code |
string | USD |
FORTER_ITEM_DEFAULT_QUANTITY optional defaults to 1 |
integer | 1 |
FORTER_ITEM_DEFAULT_TYPE optional default to TANGIBLE - Tangible if physical item, non-tangible if any other product Example: TANGIBLE Possible values are: "TANGIBLE", "NON_TANGIBLE" |
string | NON_TANGIBLE |
FORTER_ITEM_DEFAULT_CREATED_TIME conditional - Time item was added to cart by customer in seconds since unix epoch (UTC, Jan 1, 1970) |
number | 1415273168 |
FORTER_ITEM_DEFAULT_SPECIFIC_DATA_JSON conditional - JSON with the format described here: https://portal.forter.com/app/developer/api/api/data-objects/ItemSpecificData |
string JSON | {"personalCustomization":false, ....} |
Name | Type | Example values |
---|---|---|
FORTER_ITEM_TYPE optional default to TANGIBLE - Tangible if physical item, non-tangible if any other product Example: TANGIBLE Possible values are: "TANGIBLE", "NON_TANGIBLE" |
string | NON_TANGIBLE |
FORTER_ITEM_PRODUCTID Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.) |
string | 324234 |
FORTER_ITEM_PRODUCTID_TYPE optional - Type of product ID used (SKU/ISBN/UPC/etc.) |
string | SKU |
FORTER_ITEM_CATEGORY optional - The item category |
string | Item Category |
FORTER_ITEM_COUPON_CODE_USED optional - The coupon code used |
string | FATHERSDAY2015 |
FORTER_ITEM_DISCOUNT_TYPE optional - Discount type |
string | COUPON |
FORTER_ITEM_SPECIFIC_DATA_JSON conditional - JSON with the format described here: https://portal.forter.com/app/developer/api/api/data-objects/ItemSpecificData |
string JSON | {"personalCustomization":false, ....} |
FORTER_ITEM_CREATED_TIME conditional - Time item was created in seconds since unix epoch (UTC, Jan 1, 1970) |
string | 1448549922 |
Retrieve the status of transactions
Code samples
require 'vendor/autoload.php';
$headers = [
'Accept' => 'application/json',
]
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('GET','https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid} \
-X GET \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json'
}
result = RestClient.get 'https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json'
}
r = requests.get('https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const headers = {
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/status/{apiKey}/getByUuid/{uuid}', {
method: 'GET',
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Retrieve status of a transaction
GET /status/{apiKey}/getByUuid/{uuid}
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
uuid | string | true | UUID of transaction |
none
Example responses
success
{
"success": true,
"transactionStatus": "SUCCESS",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0001",
"purchaseId": "20190902-abcde12345abcde12345",
"transactionType": "debit",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"customer": {
"firstName": "John",
"lastName": "Doe",
"company": "ACME Corp.",
"emailVerified": true
},
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"returnData": {
"creditcardData": {
"type": "visa",
"cardHolder": "John Doe",
"expiryMonth": 12,
"expiryYear": 2030,
"binDigits": "12345678",
"firstSixDigits": "123456",
"lastFourDigits": "4321",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "SOME BIG BANK",
"binCountry": "US"
}
}
}
success with transaction error
{
"success": true,
"transactionStatus": "ERROR",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0001",
"purchaseId": "20190902-abcde12345abcde12345",
"transactionType": "DEBIT",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"errors": [
{
"message": "Payment could not be processed.",
"code": "1234",
"adapterMessage": "Processing failed.",
"adapterCode": "1000"
}
]
}
error
{
"success": false,
"errorMessage": "Transaction not found",
"errorCode": 8001
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
transactionStatus | string | status of the transaction |
uuid | string | UUID of the transaction |
referenceUuid | string | UUID of the related transaction |
merchantTransactionId | string | your transaction ID |
purchaseId | string | purchase ID |
transactionType | string | transaction type |
paymentMethod | string | payment method |
amount | string | transaction amount |
currency | string | transaction currency |
schedules | object | an array containing attached schedules, see ScheduleData |
errors | object | an array containing transaction errors, see TransactionError |
chargebackData | object | see ChargebackData |
chargebackReversalData | object | see ChargebackReversalData |
extraData | object | object containing key-value pairs (string-to-string) |
merchantMetaData | string | merchant metadata |
returnData | object | one of ReturnData |
customer | object | see Customer |
customerProfileData | object | see CustomerProfileData |
errorMessage | string | description if request fails |
errorCode | number | error identifier |
Code samples
require 'vendor/autoload.php';
$headers = [
'Accept' => 'application/json',
]
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('GET','https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId} \
-X GET \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json'
}
result = RestClient.get 'https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json'
}
r = requests.get('https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const headers = {
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}', {
method: 'GET',
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Retrieve status of a transaction
GET /status/{apiKey}/getByMerchantTransactionId/{merchantTransactionId}
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
merchantTransactionId | string | true | ID of merchant transaction |
Example responses
success
{
"success": true,
"transactionStatus": "SUCCESS",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0001",
"purchaseId": "20190902-abcde12345abcde12345",
"transactionType": "debit",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"customer": {
"firstName": "John",
"lastName": "Doe",
"company": "ACME Corp.",
"emailVerified": true
},
"extraData": {
"someKey": "someValue",
"otherKey": "otherValue"
},
"returnData": {
"creditcardData": {
"type": "visa",
"cardHolder": "John Doe",
"expiryMonth": 12,
"expiryYear": 2030,
"binDigits": "12345678",
"firstSixDigits": "123456",
"lastFourDigits": "4321",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "SOME BIG BANK",
"binCountry": "US"
}
}
}
success with transaction error
{
"success": true,
"transactionStatus": "ERROR",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0001",
"purchaseId": "20190902-abcde12345abcde12345",
"transactionType": "DEBIT",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"errors": [
{
"message": "Payment could not be processed.",
"code": "1234",
"adapterMessage": "Processing failed.",
"adapterCode": "1000"
}
]
}
error
{
"success": false,
"errorMessage": "Transaction not found",
"errorCode": 8001
}
Name | Type | Description |
---|---|---|
success | boolean | returns true or false depending on whether the request was successful |
transactionStatus | string | status of the transaction |
uuid | string | UUID of the transaction |
referenceUuid | string | UUID of the related transaction |
merchantTransactionId | string | your transaction ID |
purchaseId | string | purchase ID |
transactionType | string | transaction type |
paymentMethod | string | payment method |
amount | string | transaction amount |
currency | string | transaction currency |
schedules | object | an array containing attached schedules, see ScheduleData |
errors | object | an array containing transaction errors, see TransactionError |
chargebackData | object | see ChargebackData |
chargebackReversalData | object | see ChargebackReversalData |
extraData | object | object containing key-value pairs (string-to-string) |
merchantMetaData | string | merchant metadata |
returnData | object | one of ReturnData |
customer | object | see Customer |
customerProfileData | object | see CustomerProfileData |
errorMessage | string | description if request fails |
errorCode | number | error identifier |
Name | Type |
---|---|
originalUuid | string |
originalMerchantTransactionId | string |
amount | string |
currency | string |
reason | string |
chargebackDateTime | string |
Name | Type |
---|---|
originalUuid | string |
originalMerchantTransactionId | string |
chargebackUuid | string |
amount | string |
currency | string |
reason | string |
reversalDateTime | string |
Set and manage transaction schedules
Find out more about the Scheduler API
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/start', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/start \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/start");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/start");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/schedule/{apiKey}/start', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/schedule/{apiKey}/start', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/schedule/{apiKey}/start", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/start', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Start a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.
POST /schedule/{apiKey}/start
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
Request Body Example
{
"registrationUuid": "abcde12345abcde12345",
"amount": "9.99",
"currency": "EUR",
"periodLength": 6,
"periodUnit": "MONTH",
"startDateTime": "2019-09-30T01:00:00+00:00",
"merchantMetaData": "merchantRelevantData",
"callbackUrl" : "https://link.to/your/notification-handler"
}
Name | Type | Required | Description |
---|---|---|---|
registrationUuid | string | true | UUID of an initial register, debit-with-register or preauthorize-with-register |
amount | string | true | decimals separated by . , max. 3 decimals |
currency | string | true | 3 letter currency code |
periodLength | number | true | |
periodUnit | string | true | DAY , WEEK , MONTH , YEAR |
startDateTime | string | true | RFC8601 Date/Time YYYY-MM-DDTHH:MM:SS+00:00 |
merchantMetaData | string | false | |
callbackUrl | string | false | Callback Url for sending the Postback notifications of transactions initiated by the schedule to this URL, instead of the URL from the Register transaction. |
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 |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/start', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/start \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/start");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/start");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/schedule/{apiKey}/start', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/schedule/{apiKey}/start', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/schedule/{apiKey}/start", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/start', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
To update an existing schedule, simply send the fields which you wish to update.
POST /schedule/{apiKey}/{scheduleId}/update
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
scheduleId | string | true | ID of the schedule |
Request Body Example
{
"amount": "9.99",
"periodUnit": "YEAR"
}
Name | Type | Required | Description |
---|---|---|---|
registrationUuid | string | false | UUID of an initial register, debit-with-register or preauthorize-with-register |
amount | string | false | decimals separated by . , max. 3 decimals |
currency | string | false | 3 letter currency code |
periodLength | number | false | |
periodUnit | string | false | DAY , WEEK , MONTH , YEAR |
startDateTime | string | false | RFC8601 Date/Time YYYY-MM-DD\THH:MM:SS+00:00 |
callbackUrl | string | false | Callback Url for sending the Postback notifications of transactions initiated by the schedule to this URL, instead of the URL from the Register transaction. |
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 |
Code samples
require 'vendor/autoload.php';
$headers = [
'Accept' => 'application/json',
]
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('GET','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get \
-X GET \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json'
}
result = RestClient.get 'https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json'
}
r = requests.get('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const headers = {
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/get', {
method: 'GET',
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Retrieve a schedule. Requires the UUID of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.
GET /schedule/{apiKey}/{scheduleId}/get
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
scheduleId | string | true | ID of the schedule |
none
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 |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/pause', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Pause a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.
POST /schedule/{apiKey}/{scheduleId}/pause
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
scheduleId | string | true | ID of the schedule |
none
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 |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/continue', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Continue a schedule which has been paused. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.
POST /schedule/{apiKey}/{scheduleId}/continue
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
scheduleId | string | true | ID of the schedule |
Request Body 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 |
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 |
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
} catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/schedule/{apiKey}/{scheduleId}/cancel', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Cancel a schedule. Requires the registrationId of an existing transaction of type Register / Debit-with-register / Preauthorize-with-register.
POST /schedule/{apiKey}/{scheduleId}/cancel
Path parameters
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
scheduleId | string | true | ID of the schedule |
none
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 |
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}
Code samples
require 'vendor/autoload.php';
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = [];
try {
$response = $client->request('POST','https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}', [
'headers' => $headers,
'json' => $request_body,
]);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
# You can also use wget
curl https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName} \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
var client = new RestClient("https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}");
var request = new RestRequest(Method.POST);
var data = "{}";
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", data, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
URL obj = new URL("https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json'
}
result = RestClient.post 'https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}', params: {}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}', params={}, headers = headers)
print r.json()
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
}
const inputBody = '{}';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
fetch('https://gateway.p934.io/api/v3/options/{apiKey}/{optionsName}', {
method: 'POST',
body: inputBody,
headers: headers
}).then(function (res) {
return res.json();
}).then(function (body) {
console.log(body);
});
Name | Type | Required | Description |
---|---|---|---|
apiKey | string | true | API Key of Connector |
optionsName | string | true | Options identifier of the appropriate adapter |
Request Body Example
{
"parameters": {
"property1": "string",
"property2": "string"
}
}
Name | Type | Required | Description |
---|---|---|---|
parameters | object | false | Parameters which may be required for certain adapters |
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 |
The Gateway sends you an asynchronous notification once a transaction reaches a final state. This notification should be your source of trust when dealing with asynchronous transactions involving a redirect of the customer.
Depending on the payment method this can either happen immediately or can take up to several days.
Also for any follow-up transactions, such as Chargebacks and Chargeback Reversals, you will receive a notification.
Example
{
"result": "OK",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0007",
"purchaseId": "20190927-abcde12345abcde12345",
"transactionType": "DEBIT",
"paymentMethod": "DirectDebit",
"amount": "9.99",
"currency": "EUR",
"customer": {
"firstName": "John",
"lastName": "Doe",
"emailVerified": "false"
},
"returnData": {
"_TYPE": "cardData",
"type": "visa",
"cardHolder": "John Doe",
"expiryMonth": "12",
"expiryYear": "2022",
"binDigits": "41111111",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"fingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "JPMORGAN CHASE BANK N.A.",
"binType": "",
"binLevel": "",
"binCountry": "US"
}
}
When a transaction has reached the final state and is successful, the result field
will contain the value OK
. You may then assume that the transaction has been
successfully processed.
Example
{
"result": "ERROR",
"message": "STOLEN_CARD",
"code": "2016",
"adapterMessage": "Transaction was rejected",
"adapterCode": "1234",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0008",
"purchaseId": "20190927-abcde12345abcde12345",
"transactionType": "DEBIT",
"paymentMethod": "DirectDebit",
"amount": "9.99",
"currency": "EUR",
"customer": {
"firstName": "John",
"lastName": "Doe",
"emailVerified": "false"
},
"returnData": {
"_TYPE": "cardData",
"type": "visa",
"cardHolder": "John Doe",
"expiryMonth": "12",
"expiryYear": "2022",
"binDigits": "41111111",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"fingerprint": "9s92FBBvMuw7nn8t7ChHDRuFXS6gZOnHymbGnO/BZBUw3j25LW6dcl50aHWTcdJtSFDvTqLPM4stZLbGb6EVpQ",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "JPMORGAN CHASE BANK N.A.",
"binType": "",
"binLevel": "",
"binCountry": "US"
}
}
If a transaction fails, the result field will contain the value ERROR
. Depending
on the type of error, you may either find useful information in the message
and code
fields, or in adapterMessage
and adapterCode
fields which
contain the errors returned by the respective adapter.
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
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
Example for Account Update Notification
{
"result": "OK",
"uuid": "abcde12345abcde12345",
"merchantTransactionId": "2019-09-02-0012",
"purchaseId": "20191210-abcde12345abcde12345",
"transactionType": "REGISTER",
"paymentMethod": "Creditcard",
"extraData": {
"lastCardUpdateDate": "2022-08-19",
"lastCardUpdateResult": "updated"
},
"returnData": {
"_TYPE": "cardData",
"type": "mastercard",
"cardHolder": "Firstname Lastname",
"expiryMonth": "12",
"expiryYear": "2050",
"binDigits": "55555555",
"firstSixDigits": "555555",
"lastFourDigits": "4444",
"fingerprint": "YQTgkfrQJYzExJYmomJBS0tWMF8D5J0jG/DAtes3X5oVElUNEbOld5lakWbgdUrW8VHKpNqFfJCMVakh+2LsoA",
"binBrand": "MASTERCARD",
"binBank": "SOME BANK",
"binType": "CREDIT",
"binLevel": "STANDARD",
"binCountry": "US"
}
}
If your merchant account has the Account Updater enabled, you will receive
notifications in case a stored card of a customer gets updated. The update
information will be reported in the extraData
of the notification payload.
Parameter | Description |
---|---|
extraData.lastCardUpdateDate | When the update was received |
extraData.lastCardUpdateResult | The result of the update |
The update result can have the following values:
Result | Description |
---|---|
updated |
Card number and expiry date was updated |
closed |
Card is closed and not valid anymore |
new_expiry |
Card expiry date was updated |
contact |
Contact the cardholder for updated information |
The returnData
of type cardData
will contain the updated information.
Example for Network Token Notification
{
"result": "OK",
"uuid": "7e59391c9a939c1be763",
"merchantTransactionId": "20230523141348",
"purchaseId": "20230523-7e59391c9a939c1be763",
"transactionType": "DEBIT",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"returnData": {
"_TYPE": "cardData",
"type": "visa",
"cardHolder": "john",
"expiryMonth": "02",
"expiryYear": "2025",
"binDigits": "41111111",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"fingerprint": "Gsw+vddi8/Jhzy2D1yVdU1b8QCAIA/4vHVfrVtOUGreoCak++m2Azwvj/2ASbyxLpb4dT9+9de2evu1G2ncvsg",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "JPMORGAN CHASE BANK N.A.",
"binType": "",
"binLevel": "CLASSIC",
"binCountry": "US"
},
"extraData": {
"networkTokenStatus": "active",
"networkTokenMetadata": [
{
"mimeType": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
"width": "150",
"height": "150"
},
{
"mimeType": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
"width": "",
"height": ""
}
]
}
}
{
"result": "OK",
"uuid": "7e59391c9a939c1be763",
"merchantTransactionId": "20230523141348",
"purchaseId": "20230523-7e59391c9a939c1be763",
"transactionType": "DEBIT",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"returnData": {
"_TYPE": "cardData",
"type": "visa",
"cardHolder": "john",
"expiryMonth": "02",
"expiryYear": "2025",
"binDigits": "41111111",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"fingerprint": "Gsw+vddi8/Jhzy2D1yVdU1b8QCAIA/4vHVfrVtOUGreoCak++m2Azwvj/2ASbyxLpb4dT9+9de2evu1G2ncvsg",
"threeDSecure": "OFF",
"binBrand": "VISA",
"binBank": "JPMORGAN CHASE BANK N.A.",
"binType": "",
"binLevel": "CLASSIC",
"binCountry": "US"
},
"extraData": {
"networkTokenStatus": "suspended"
}
}
When a network token has been created, you will receive notifications in case of updates regarding that token. In the case of asynchronous tokenization, you will also receive a notification when the tokenization process has been completed and the token has been created. In the case of synchronous tokenization, the token information will be available in the API response as well as in the notification.
The token status and any possible token meta data (such as card art)
will be reported in the extraData
of the notification payload.
Parameter | Description |
---|---|
extraData.networkTokenStatus | Status of the token |
extraData.networkTokenMetadata | Array with card metadata (if available) |
extraData.lastNetworkTokenUpdateDate | Update notification date |
extraData.lastNetworkTokenUpdateResult | Update notification result |
The networkTokenStatus
may have the following values:
Status | Description |
---|---|
active |
Token is active and can be used |
inactive |
The token is not yet active |
suspended |
The token has been suspended and cannot be used at the moment |
deactivated |
The token is disabled and cannot be used anymore |
pending |
Tokenization is in progress |
error |
Error occurred during tokenization |
If the status is inactive, suspended or deactivated, it is not recommended to use the network token for processing.
The networkTokenMetadata
may contain following values:
Parameter | Description |
---|---|
mimeType | MIME type |
data | Image data (may be encoded, e.b. base64) |
width | (conditional) Width |
height | (conditional) Height |
If the token has been updated, the lastNetworkTokenUpdateResult
may have following values:
lastNetworkTokenUpdateResult | Description |
---|---|
pan_changed |
PAN has changed |
pan_expiry_changed |
PAN expiry has changed |
token_expiry_changed |
Token expiry has changed |
active |
Token is active and can be used |
inactive |
The token is not yet active |
suspended |
The token has been suspended and cannot be used at the moment |
deactivated |
The token is disabled and cannot be used anymore |
error |
Error occurred during tokenization |
The first attempt would happen immediately. If no confirmation is received with
a Status 200, content OK
(as described above), we will try again in increasing intervals.
First 1 minute, then 5, 15, 60, 120, 180, 720, and finally once every 24 hours for 7 days.
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)
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
Name | Type | Description |
---|---|---|
result | string | OK , PENDING , ERROR |
uuid | string | UUID of the transaction |
merchantTransactionId | string | your unique transaction ID |
purchaseId | string | purchase ID |
transactionType | string | DEBIT , CAPTURE , DEREGISTER , PREAUTHORIZE , REFUND , REGISTER , VOID , CHARGEBACK , CHARGEBACK-REVERSAL , PAYOUT |
paymentMethod | string | payment method |
amount | string | decimals separated by . , max. 3 decimals |
currency | string | 3 letter currency code |
scheduleData | object | see ScheduleData |
notificationSource | string | In case the transaction status, amount or currency has been changed after reconciliation the parameter can have the following value: reconciliation , settlement |
originalAmount | string | In case the transaction amount has been changed after reconciliation the is parameter will contain the original amount. Decimals separated by . , max. 3 decimals |
originalCurrency | string | In case the transaction currency has been changed after reconciliation the is parameter will contain the original currency. 3 letter currency code |
chargebackData | object | see ChargebackData |
chargebackReversalData | object | see ChargebackReversalData |
extraData | object | object containing key-value pairs (string-to-string) |
merchantMetaData | string | merchant metadata |
returnData | object | one of ReturnData |
customer | object | see Customer |
customerProfileData | object | see CustomerProfileData |
message | string | error message in case of error transaction |
code | number | error code in case of error transaction |
adapterMessage | string | error message of adapter |
adapterCode | string | error identifier of adapter |