API Methods

The SysPay REST API is a simple programmatic interface that allows the merchant, to access or process data on the SysPay platform. You can find a list of all available API methods below.

All webservice requests should be sent over a secured HTTPS connection to the base URL https://app.syspay.com. For each webservice the URL path and the required parameter formats are defined below. The latest version of the API is “v2”.

All request arguments should be sent in the POST body, formatted as a JSON document. The API assumes that all data in requests is UTF-8 encoded. As an security measure, SysPay will only allow requests to be performed from specific authorized IP-addresses.

The webservice always responds with a UTF-8 encoded JSON message and a specific HTTP status code. The status code indicates that the request was successfully processed (2xx) or not ([45]xx). If there was an error, the response will contain a section with error information. For further details, check out the full list of all possible errors. If there was no error, the response will contain the information you requested.

Authentication

If you are a partner and sending a request to our API on behalf of a merchant, then your request must include an X-Wsse header that matches the following pattern:

X-Wsse: AuthToken MerchantAPILogin="{merchantLogin}", PasswordDigest="{digest}", Nonce="{b64nonce}", Created="{timestamp}", PartnerLogin="{partnerLogin}", PartnerDigest="{partnerDigest}"

Where:

• merchantLogin The Merchant API login, provided by SysPay, along with a shared passphrase
• b64nonce is a base64-encoded random token (nonce) generated for each request
• timestamp is the current unix timestamp
• digest is a string generated from the nonce, the timestamp and the passphrase with the following algorithm:

BASE64(BINARY_SHA1(NONCE + TIMESTAMP + PASSPHRASE))

• partnerLogin is Partner API login, provided by SysPay, along with a shared partnerPassphrase
• partnerDigest is a string generated from the nonce, the timestamp and the partnerPassphrase with the following algorithm:

BASE64(BINARY_SHA1(NONCE + TIMESTAMP + PARTNER_PASSPHRASE))

This header can only be used once and must be re-generated on each request.

Example code (PHP)

<?php

function generateHeaders($merchantLogin, $passphrase, $partnerLogin, $partnerPassphrase, $nonce = null, $timestamp = null) {

  $nonce = null === $nonce ? md5(rand(), true) : $nonce;
  $timestamp = null === $timestamp ? time() : $timestamp;

  $digest = base64_encode(sha1($nonce . $timestamp . $passphrase, true));
  $partnerDigest = base64_encode(sha1($nonce . $timestamp . $partnerPassphrase, true));
  $b64nonce = base64_encode($nonce);

  $header = sprintf('X-Wsse: AuthToken MerchantAPILogin="%s", PasswordDigest="%s", Nonce="%s", Created="%d", PartnerLogin="%s", PartnerDigest="%s"',
                      $merchantLogin, $digest, $b64nonce, $timestamp, $partnerLogin, $partnerDigest);

  return $header;

}

If called with the following parameters:

<?php

generateHeaders("merchantLogin", "merchantPassphrase", "myPartnerLogin", "myPartnerPassphrase", "my random nonce", 1400000000)

You would expect the following output::

X-Wsse: AuthToken MerchantAPILogin="merchantLogin", PasswordDigest="l34fbiN8TnMcOuMrNa+j5k7YSqQ=", Nonce="bXkgcmFuZG9tIG5vbmNl", Created="1400000000", PartnerLogin="myPartnerLogin", PartnerDigest="yxag0yx38DPpCDx1Pl8UZnmXANE="

Errors

When a request is not valid or is not successfully processed, the API returns a list of errors which occured together with and HTTP error code.

Response parameters

Name	Type	Mandatory	Description
error_code	string	Y	The HTTP status code. see http codes
errors	array	Y	An array of error objects. see error codes

Example response

{
  "error_code": 400,
  "errors": [
    {
      "class": "error",
      "property": "source",
      "message": "Source not found",
      "code": 20006,
      "data": "60"
    },
    {
      "class": "error",
      "property": "expirationDate",
      "message": "Invalid end_date parameter",
      "code": 20004,
      "data": "string"
    }
  ]
}

Hosted token request

This method allows the merchant to initiate a token request. The response includes a redirect URL, to which the customer has to be redirected in order to provide the payment method details. This method provides you the option of sending directly the action_url to the customer email.

When the process is complete, the user will be sent back to your return_url which the final result will be appended to. In order to verify that these parameters have not been tampered with, see the post process redirection documentation.

Note: By default, a token cannot be de-tokenized by anyone unless explicitely specified by giving a list of authorized detokenizers in the authorized_detokenizers parameter. This parameter can only accept up to two ids. If two are provided, one must be your own partner id, (to allow yourself to de-tokenize) the other one is a partner you allow to view the token details.

URL syntax:/api/{version}/merchant/token Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	BUYER	Y	The flow of the request call. BUYER: The customer which is in front of the screen and will provide his/her the payment details.
source	int		N	The property reference for which this token request is.
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	Y	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	Y	The check_in date of the booking.
booking_details.check_out_date	string	YYYY-mm-dd	Y	The check_out date of the booking. If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		Y	The total booking fee amount in cents (500 XXX = 5.00 XXX).
booking_details.booking_currency	string	[A-Z]{3}	Y	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform.
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
accept_until	unix timestamp		N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay Hosted Token page.
return_url	string		N	This parameter overrides the default return_url configuration set in the user backend.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.
notify	string	EMAIL	N	The notification method for the BUYER flow to be used within this API request.
allowed_retries	int		N	The number of attempts a user has to try to enter the valid payment method details. This parameter can only be accepted if configured on your API. Please contact customer service if you require this functionality.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note above)
mandate	boolean	true|false	N	This parameter will determine if the token or payment can be used to make future payments/rebills. (Defaults to false).
mandate_currency	string	[A-Z]{3}	N*	The currency that will be used to make future payments. (ISO-4217). {*Required if mandate is set to true.}
customer.firstname	string	max length 100	N	The customer’s first name
customer.lastname	string	max length 100	N	The customer’s last name
customer.email	string	valid email address	N*	The customer email address.(*Required if notify is set to EMAIL.)
customer.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The customer’s reference
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
customer.address_country	string	ISO 3166-1 alpha-2 country code	N	The customer’s address’ country. This parameter will be phased out when 3DS2 becomes mandatory
customer.login	string	max length 150	N	The customer’s login
customer.password_hash	string	max length 64	N	The customer’s password hash
customer.billing_address	object	billing address	N*	The customer’s billing address. This parameter will be required to be able to utilize the 3DS protocol once 3DS2 becomes mandatory

Example request (hosted page)

{
  "flow": "BUYER",
  "source": 16,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": 1420464268,
  "accept_until": 1420275883,
  "description": "Hotel XYZ",
  "return_url": "http://www.mysite.com/return.php",
  "ems_url": "http://www.mysite.com/ems.php",
  "notify": "EMAIL",
  "mandate": true,
  "mandate_currency": "EUR",
  "authorized_detokenizers": [42, 9000],
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "reference": "ref-1234",
    "language": "en",
    "address_country": "FR",
    "login": "username",
    "password_hash": "p@55w0rd_#",
    "billing_address": {
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  }
}

Response parameters

Depending on the service level (STORAGE/VERIFICATION/PROCESSING), the token creation could include the automatic creation of a mandate. In this case, the response will contain an extra mandate object containing the mandate status and its details.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response (without mandate creation)

{
  "class": "token",
  "id": "8",
  "status": "REDIRECT",
  "action_url": "http://www.syspay.com/redirect/hosted/token/28",
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1421426737",
  "accept_until": 1420275883,
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address":
    {
      "class": "billing_address",
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "address3": null,
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": null
}

Example response (with automatic mandate creation)

{
  "class": "token",
  "id": "8",
  "status": "REDIRECT",
  "action_url": "http://www.syspay.com/redirect/hosted/token/28",
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1421426737",
  "accept_until": 1420275883,
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address":
    {
      "class": "billing_address",
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "address3": null,
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": null,
  "mandate": {
    "class": "mandate",
    "status": "PENDING",
    "end_reason": null,
    "start_date": null,
    "end_date": null
  }
}

Hosted token request with initial payment

This method allows the merchant to initiate a token request with an initial payment. The response includes a redirect URL, to which the customer has to be redirected in order to provide the payment method details. This method provides you the option of sending directly the action_url to the customer email.

When the process is complete, the user will be sent back to your return_url which the final result will be appended to. In order to verify that these parameters have not been tampered with, see the post process redirection documentation.

Note: By default, a token cannot be de-tokenized by anyone unless explicitly specified by giving a list of authorized detokenizers in the authorized_detokenizers parameter. This parameter can only accept up to two ids. If two are provided, one must be your own partner id, (to allow yourself to de-tokenize) the other one is a partner you allow to view the token details.

URL syntax:/api/{version}/merchant/token Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	BUYER	Y	The flow of the request call. BUYER: The customer which is in front of the screen and will provide his/her the payment details.
source	int		N	The property reference for which this token request is.
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	Y	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	Y	The check_in date of the booking.
booking_details.check_out_date	string	YYYY-mm-dd	Y	The check_out date of the booking. If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		Y	The total booking fee amount in cents (500 XXX = 5.00 XXX).
booking_details.booking_currency	string	[A-Z]{3}	Y	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform.
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
accept_until	unix timestamp		N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
return_url	string		N	This parameter overrides the default return_url configuration set in the user backend.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.
notify	string	EMAIL	N	The notification method for the BUYER flow to be used within this API request.
allowed_retries	int		N	The number of attempts a user has to try to enter the valid payment method details. This parameter can only be accepted if configured on your API. Please contact customer service if you require this functionality.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note above)
customer.firstname	string	max length 100	N	The customer’s first name
customer.lastname	string	max length 100	N	The customer’s last name
customer.email	string	valid email address	N*	The customer email address.(*Required if notify is set to EMAIL.)
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
customer.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The customer’s reference
customer.address_country	string	ISO 3166-1 alpha-2 country code	N	The customer’s address’ country. This parameter will be phased out when 3DS2 becomes mandatory
customer.login	string	max length 150	N	The customer’s login
customer.password_hash	string	max length 64	N	The customer’s password hash
customer.billing_address	object	billing address	N*	The customer’s billing address. This parameter will be required to be able to utilize the 3DS protocol once 3DS2 becomes mandatory
payment.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	Y	The merchant payment identifier for the request. This must be unique for each request.
payment.amount	int		Y	The payment amount in cents (500 XXX = 5.00 XXX). Please check the allowed amount from the currency settings found in the user backend.
payment.currency	string	[A-Z]{3}	Y	The currency in which the payment should be processed. The passed currency should follow the (ISO-4217) standard. The list of currencies you are allowed to process can be checked from the settings page in the user backend.
payment.preauth	boolean	true|false	N	This parameter determines whether the payment request should be fully processed or only authorized. If set to true the payment is only authorized and it will need to be {captured see Capture a pre-authorization} or {voided see Void a pre-authorization} later. (Defaults to false). In case of a hosted request and it is set to true, only payment methods supporting preauthorizations will be displayed.
payment.capture_date	int	unix timestamp	N	This parameter determines when a preauthorization will be automatically captured
payment_method_options	array	payment method options	N	Extra parameters to override payment method options

Example request (hosted page)

{
  "flow": "BUYER",
  "source": 16,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": 1420464268,
  "accept_until": 1420275883,
  "description": "Shopping basket payment",
  "return_url": "http:\/\/www.mysite.com\/return.php",
  "ems_url": "http:\/\/www.mysite.com\/ems.php",
  "notify": "EMAIL",
  "authorized_detokenizers": [42, 9000],
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "reference": "ref-1234",
    "language": "en",
    "address_country": "FR",
    "login": "username",
    "password_hash": "p@55w0rd_#",
    "billing_address": {
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment": {
    "reference": "Unique-123213",
    "amount": 5000,
    "currency": "EUR"
  },
  "payment_method_options": [
    {
        "type" : "CREDITCARD",
        "three_ds" : "MUST"
    }
  ]
}

Response parameters

When requesting a payment together with the token creation, a mandate will automatically created.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response

{
  "class": "token",
  "id": "8",
  "status": "REDIRECT",
  "action_url": "https:\/\/app.syspay.com\/redirect\/payment\/80\/eea8ed0769d0984eb52b6f6e035642fca0e60a61\/HOSTED?_locale=fr",
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1421426737",
  "accept_until": 1420275883,
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address":
    {
      "class": "billing_address",
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "address3": null,
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": null,
  "mandate": {
    "class": "mandate",
    "status": "PENDING",
    "end_reason": null,
    "start_date": null,
    "end_date": null
  },
 "payment":
 {
    "class":"payment",
    "id":80,
    "reference":"Unique-111312",
    "amount":5000,
    "currency":"EUR",
    "status":"OPEN",
    "action_url":"https:\/\/app.syspay.com\/redirect\/payment\/80\/eea8ed0769d0984eb52b6f6e035642fca0e60a61\/HOSTED?_locale=fr",
    "flow":"BUYER",
    "processing_time":null,
    "source":11,
    "contract":null,
    "descriptor":null,
    "extra":null,
    "description":"description",
    "account_id":66,
    "merchant_id":65,
    "merchant_login":"66001",
    "settlement_date":null,
    "failure_category":null,
    "chip_and_pin_status":null,
    "token":
    {
       "class":"reference",
       "id":26,
       "type":"token",
       "link":"https:\/\/app.syspay.com\/api\/v2\/merchant\/token\/26"
    },
    "processor_reference":"ref1234"
}

Server-to-server token request

This method allows the merchant to create a token directly by providing the payment method details within the request.

Note: By default, a token cannot be de-tokenized by anyone unless explicitly specified by giving a list of authorized detokenizers in the authorized_detokenizers parameter. This parameter can only accept up to two ids. If two are provided, one must be your own partner id, (to allow yourself to de-tokenize) the other one is a partner you allow to view the token details.

URL syntax:/api/{version}/merchant/token Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	API	Y	The flow of the request call. API: refers to the action where the customer details will be sent directly with the API call.
source	int		N	The property reference for which this token request is.
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	Y	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	Y	The check_in date of the booking.
booking_details.check_out_date	string	YYYY-mm-dd	Y	The check_out date of the booking. If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		Y	The total booking fee amount in cents (500 XXX = 5.00 XXX).
booking_details.booking_currency	string	[A-Z]{3}	Y	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform.
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
interactive	boolean	1|0	Y	This parameter specifies if the request is made by the merchant or a in the name of a 3rd party merchant.
return_url	string		N	This parameter overrides the default return_url configuration set in the user backend.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note above)
mandate	boolean	true|false	N	This parameter will determine if the token or payment can be used to make future payments/rebills. (Defaults to false).
mandate_currency	string	[A-Z]{3}	N*	The currency that will be used to make future payments. (ISO-4217). {*Required if mandate is set to true.}
customer.firstname	string	max length 100	N	The customer’s first name
customer.lastname	string	max length 100	N	The customer’s last name
customer.ip	string		N*	The customer public ip address. (*Required if the interactive flag is set to true.)
customer.email	string	valid email address	N*	The customer email address. (*Required if notify is set to EMAIL.)
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
customer.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The customer’s reference
customer.address_country	string	ISO 3166-1 alpha-2 country code	N	The customer’s address’ country. This parameter will be phased out when 3DS2 becomes mandatory
customer.login	string	max length 150	N	The customer’s login
customer.password_hash	string	max length 64	N	The customer’s password hash
customer.billing_address	object	billing address	N*	The customer’s billing address. This parameter will be required to be able to utilize the 3DS protocol once 3DS2 becomes mandatory
payment_method.type	string	CREDITCARD	N*	The type of payment object to be passed in the api call. * Required if no payment_method.token_key is provided.
payment_method.token_key	string		N*	The token value provided by the JS tokenizer service. (*Required if no payment_method.type is provided.) This is only allowed if interactive flag is set to true. See the client-side tokenization documentation.

Method-specific parameters

Method: CREDITCARD

Name	Type	Details	Mandatory	Description
payment_method.cardholder	string	max length 100	Y	Cardholder name. Please note that non-alphabetic characters other than @ . - _ ‘ will be stripped out. Names containing digits will be rejected by validation.
payment_method.number	string	[0-9]{12,19}	Y	Valid credit card number, only digits.
payment_method.exp_month	string	[0-9]{2}	Y	Credit card expire month (ex: 05).
payment_method.exp_year	string	[0-9]{4}	Y	Credit card expire year (ex: 2015).
payment_method.cvc	int	[0-9]{3,4}	N	Credit card verification code. The CVC is always required if interactive is true or if interactive is false and your API settings do not allow you to process payments or create mandates without providing it.

Example request

{
  "flow": "API",
  "source": 1,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": 1420464268,
  "interactive": "0",
  "return_url": "http://www.mysite.com/return.php",
  "ems_url": "http://www.mysite.com/ems.php",
  "authorized_detokenizers": [
    42,
    9000
  ],
  "mandate": true,
  "mandate_currency": "EUR",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "reference": "ref-1234",
    "language": "en",
    "address_country": "FR",
    "login": "username",
    "password_hash": "p@55w0rd_#",
    "billing_address": {
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": {
    "type": "CREDITCARD",
    "number": 4111111111111111,
    "cardholder": "Card Holder Name",
    "exp_month": "01",
    "exp_year": "2015",
    "cvc": "123"
  }
}

Response parameters

Depending on the service level (STORAGE/VERIFICATION/PROCESSING), the token creation could include the automatic creation of a mandate. In this case, the response will contain an extra mandate object containing the mandate status and its details.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response (without mandate creation)

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_details": {
     "type": "HOTEL",
     "booking_id": "test-ref",
     "check_in_date": "2016-01-25",
     "check_out_date": "2016-01-30",
     "total_booking_amount": 500,
     "booking_currency": "EUR"
   },
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address":
      {
        "class": "billing_address",
        "address1": "3B, SysPay",
        "address2": "Wied Ghomor Street",
        "address3": null,
        "city": "St. Julians",
        "country": "MT",
        "postal_code": "STJ2041"
      }
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2015"
      }
   },
   "risk":{
     "class":"risk",
     "level":"HIGH",
     "reason":"INSUFFICIENT_FUNDS"
   }
}

Example response (with automatic mandate creation)

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": null,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1520464268",
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address":
    {
      "class": "billing_address",
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "address3": null,
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "display": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null,
    "details": {
      "class":"payment_method_details",
      "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2015"
    }
  },
  "mandate": {
    "class": "mandate",
    "status": "ACTIVE",
    "end_reason": null,
    "start_date": 1423753881,
    "end_date": null
  },
  "risk":{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
  }
}

Server-to-server token request with initial payment

This method allows the merchant to create a token directly with an initial payment by providing the payment method and payment details within the request.

Note: By default, a token cannot be de-tokenized by anyone unless explicitly specified by giving a list of authorized detokenizers in the authorized_detokenizers parameter. This parameter can only accept up to two ids. If two are provided, one must be your own partner id, (to allow yourself to de-tokenize) the other one is a partner you allow to view the token details.

URL syntax:/api/{version}/merchant/token Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	API	Y	The flow of the token request call. API: refers to the action where the customer details will be sent directly with the API call.
source	int		N	he website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	Y	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	Y	The check_in date of the booking.
booking_details.check_out_date	string	YYYY-mm-dd	Y	The check_out date of the booking. If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		Y	The total booking fee amount in cents (500 XXX = 5.00 XXX).
booking_details.booking_currency	string	[A-Z]{3}	Y	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform.
expiration_date	unix timestamp		N	The token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
interactive	boolean	1|0	Y	This parameter specifies if the request is made in the name of the merchant himself or if its a 3rd party merchant.
return_url	string		N	This parameter overrides the default return_url configuration set in the user backend.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.
description	string	max length 300	N	The product/service description.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note above)
customer.firstname	string	max length 100	N	The customer’s first name
customer.lastname	string	max length 100	N	The customer’s last name
customer.ip	string		N*	The customer public ip address. (*Required if the interactive flag is set to true.)
customer.email	string	valid email address	N	The customer email address.
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
customer.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The customer’s reference
customer.address_country	string	ISO 3166-1 alpha-2 country code	N	The customer’s address’ country. This parameter will be phased out when 3DS2 becomes mandatory
customer.login	string	max length 150	N	The customer’s login
customer.password_hash	string	max length 64	N	The customer’s password hash
customer.billing_address	object	billing address	N*	The customer’s billing address. This parameter will be required to be able to utilize the 3DS protocol once 3DS2 becomes mandatory
payment_method.type	string	CREDITCARD | IDEAL | SOFORT_BANKING	N*	The type of payment object to be passed in the api call. (* Required if no payment_method.token_key is provided.)
payment_method.token_key	string		N*	The token value provided by the JS tokenizer service. (*Required if no payment_method.type is provided.) This is only allowed if interactive flag is set to true. See the client-side tokenization documentation.
payment.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	Y	The merchant payment identifier for the request. This must be unique for each request.
payment.amount	int		Y	The payment amount in cents (500 XXX = 5.00 XXX). Please check your allowed amount limits from the currency settings found in the user backend.
payment.currency	string	[A-Z]{3}	Y	The currency type in which the payment should be processed. (The list of allowed currencies can be checked from the settings page of the merchant backend.) The passed currency should follow the (ISO-4217) standard.
payment.preauth	boolean	true|false	N	This parameter determines whether the payment request should be fully processed or only authorized. If set to true the payment is only authorized and it will need to be captured (see Capture a pre-authorization) or voided (see Void a pre-authorization) later. (Defaults to false).
payment.capture_date	int	unix timestamp	N	This parameter determines when a preauthorization will be automatically captured
payment_method_options	array	payment method options	N	Extra parameters to override payment method options
device	object	device	N*	Extra parameters for improved 3D Secure Assessment (* Required if you’re not using our client-side tokenization solution and therefore not providing a payment_method.token_key and if interactive = 1)

Method-specific parameters

Method: CREDITCARD

Name	Type	Details	Mandatory	Description
payment_method.cardholder	string	max length 100	Y	Cardholder name. Please note that non-alphabetic characters other than @ . - _ ‘ will be stripped out. Names containing digits will be rejected by validation.
payment_method.number	string	[0-9]{12,19}	Y	Valid credit card number, only digits.
payment_method.exp_month	string	[0-9]{2}	Y	Credit card expire month (ex: 05).
payment_method.exp_year	string	[0-9]{4}	Y	Credit card expire year (ex: 2015).
payment_method.cvc	int	[0-9]{3,4}	N	Credit card verification code. The CVC is always required if interactive is true or if interactive is false and your API settings do not allow you to process payments or create mandates without providing it.

Method: IDEAL

Name	Type	Details	Mandatory	Description
ideal.bank_id	int		Y	The iDeal bank id (see Get a list of iDeal banks)

Example request

{
  "flow": "API",
  "source": 1,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": 1520464268,
  "interactive": "0",
  "return_url": "http://www.mysite.com/return.php",
  "ems_url": "http://www.mysite.com/ems.php",
  "description": "Shopping basket payment",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "reference": "ref-1234",
    "language": "en",
    "address_country": "FR",
    "login": "username",
    "password_hash": "p@55w0rd_#",
    "billing_address": {
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "authorized_detokenizers": [
    42,
    9000
  ],
  "payment_method": {
    "type": "CREDITCARD",
    "number": 4111111111111111,
    "cardholder": "Card Holder Name",
    "exp_month": "01",
    "exp_year": "2016",
    "cvc": "123"
  },
  "payment": {
    "reference": "Unique-111111",
    "amount": 5000,
    "currency": "EUR"
  },
  "payment_method_options": [
    {
        "type" : "CREDITCARD",
        "three_ds" : "MUST"
    }
  ],
  "device": {
    "type": "browser",
    "browser_width": "1024",
    "browser_height": "768",
    "browser_time_zone_offset": "-120",
    "browser_color_depth": "48",
    "browser_java_enabled": "1",
    "browser_language": "en",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent_header": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
  }
}

Response parameters

When requesting a payment together with the token creation, a mandate will automatically created.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": null,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1520464268",
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address":
    {
      "class": "billing_address",
      "address1": "3B, SysPay",
      "address2": "Wied Ghomor Street",
      "address3": null,
      "city": "St. Julians",
      "country": "MT",
      "postal_code": "STJ2041"
    }
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "display": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null,
    "details": {
      "class":"payment_method_details",
      "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2016"
    }
  },
  "payment": {
    "class": "payment",
    "id": 16,
    "reference": "Unique-111111",
    "amount": 5000,
    "currency": "EUR",
    "status": "SUCCESS",
    "preauth_expiration_date":null,
    "flow": "API",
    "processing_time": 1423501843,
    "source": 1,
    "contract": "Contract",
    "descriptor": "Contract",
    "extra": null,
    "description": "Shopping basket payment",
    "account_id": 123,
    "merchant_id": 123,
    "merchant_login": "login",
    "settlement_date": 1424711442,
    "failure_category": null,
    "chip_and_pin_status": null,
    "token": {
      "class": "reference",
      "id": 7,
      "type": "token",
      "link": "https://www.syspay.com/api/v2/merchant/token/1"
    },
    "customer": {
      "class": "customer",
      "email": "test@domain.com",
      "language": "en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address":
      {
        "class": "billing_address",
        "address1": "3B, SysPay",
        "address2": "Wied Ghomor Street",
        "address3": null,
        "city": "St. Julians",
        "country": "MT",
        "postal_code": "STJ2041"
      }
    },
    "payment_method": {
      "class": "payment_method",
      "type": "CREDITCARD",
      "display": "4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details": {
        "class":"payment_method_details",
        "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
        "holder":"Card Holder Name",
        "scheme": "VISA",
        "exp_month":"01",
        "exp_year":"2016"
      }
    },
    "processor_reference":"ref1234"
  },
  "mandate": {
    "class": "mandate",
    "status": "ACTIVE",
    "end_reason": null,
    "start_date": 1423753881,
    "end_date": null
  },
  "risk":{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
  }
}

Server-to-server debit request on a token

This method allows the merchant to take a payment on an existing token with an active mandate or without mandate. In order to do so, a payment on a specific token_id has to be requested.

URL syntax:/api/{version}/merchant/payment Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	API	Y	Always use ‘API’ for rebills.
token_id	int		Y	The token reference.
reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	Y	The merchant payment identifier for the request. This must be unique for each request.
amount	int		Y	The payment amount in cents (500 XXX = 5.00 XXX). Please check the allowed amount from the currency settings found in the user backend.
currency	string	[A-Z]{3}	Y	The currency in which the payment should be processed. The passed currency should follow the (ISO-4217) standard and must match the one that the mandate is in.
preauth	boolean	true|false	N	This parameter determines whether the payment request should be fully processed or only authorized. If set to true the payment is only authorized and it will need to be {captured see Capture a pre-authorization} or {voided see Void a pre-authorization} later. (Defaults to false).
capture_date	int	unix timestamp	N	This parameter determines when a preauthorization will be automatically captured
description	string	max length 300	N	The product/service description.
extra	string	max lenght 300	N	Extra parameter that is passed back to the merchant when sending the event message.
return_url	string		N	This parameter overrides the default return_url configuration set in the user backend.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.

Example request

 {
    "flow": "API",
    "token_id": 12,
    "extra": "extra",
    "reference": "Unique-11111",
    "description": "Some description",
    "amount": 5000,
    "currency": "EUR",
    "return_url": "http:\/\/www.mysite.com\/return.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
}

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment.
id	int	Y	The SysPay reference of the returned payment.
reference	string	Y	The merchant payment identifier which was passed in the request.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The payment status see status.
preauth_expiration_date	unix timestamp	Y	The preauth expiration date specifies until when a a preauth can be captured or voided. The transaction will be voided automatically once the preauth expires.
capture_date	unix timestamp	Y	The date after which the preauth may be automatically captured.
action_url	string	N	The url where the customer should be redirected to in order to provide further details required to complete the payment.
flow	string	Y	The flow used to process the payment.
processing_time	unix timestamp	Y	When the payment has been processed, null if the transaction is still not complete.
source	int	N	The id of the website the payment has been made for.
contract	string	N	The name of the payment processor.
descriptor	string	N	The payment description which will be shown on the card payment bank statement.
extra	string	N	The extra parameter which was sent on in the request call.
description	string	N	The merchant payment description.
account_id	int	Y	The SysPay account reference that the API access is linked to.
merchant_id	int	Y	The SysPay API access merchant reference.
merchant_login	string	Y	The SysPay API merchant login which proccessed the payment.
settlement_date	unix timestamp	N	A timestamp indicating when this payment will be settled.
failure_category	string	N	When a payment fails, this parameter will include extra information about the error (reference).
chip_and_pin_status	string	N	This field will be present on Chip&Pin transactions. When the payment has been made using the bluetooth device, the actual payment status will be kept OPEN until the transaction is really captured (which can take 1 business day). In order to let your web shop or native application know about the transaction results synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only.
token	object	N	The token details. see token.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method.
processor_reference	string	N	The reference of the transaction for the processor, in case of supergateway processing.

Example response

{
  "class": "payment",
  "id": 123,
  "reference": "Unique-11111",
  "amount": 5000,
  "currency": "EUR",
  "status": "SUCCESS",
  "action_url": null,
  "flow": "API",
  "processing_time": 1423737892,
  "source": null,
  "contract": "Syspay",
  "descriptor": "@SYSPAY*mysite.com",
  "extra": "extra",
  "description": "Some description",
  "account_id": 42,
  "merchant_id": 65,
  "merchant_login": "42001",
  "settlement_date": 1423737892,
  "failure_category": null,
  "chip_and_pin_status": null,
  "token": {
    "class": "token",
    "id": "44",
    "status": "ACTIVE",
    "action_url": null,
    "booking_details": {
      "type": "HOTEL",
      "booking_id": "test-ref",
      "check_in_date": "2016-01-25",
      "check_out_date": "2016-01-30",
      "total_booking_amount": 500,
      "booking_currency": "EUR"
    },
    "expiration_date": 1523737892,
    "description": "description",
    "customer": {
      "class": "customer",
      "email": "test@domain.com",
      "language": "en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address": null
    },
    "payment_method": {
      "class": "payment_method",
      "type": "CREDITCARD",
      "display": "4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details": {
        "class":"payment_method_details",
        "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
        "holder":"Card Holder Name",
        "scheme": "VISA",
        "exp_month":"01",
        "exp_year":"2016"
      }
    },
    "processor_reference":"ref1234",
    "risk":{
      "class":"risk",
      "level":"HIGH",
      "reason":"INSUFFICIENT_FUNDS"
    }
  },
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address": null
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "display": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null,
    "details": {
      "class":"payment_method_details",
      "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2016"
    }
  }
}

Get token information

This method allows the merchant to get information regarding a particular token.

URL syntax:/api/{version}/merchant/token/{token_id} Method:GET

URL parameters

Name	Type	Details	Mandatory	Description
token_id	int		Y	The reference id of the token to be retrieved.

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_details": {
     "type": "HOTEL",
     "booking_id": "test-ref",
     "check_in_date": "2016-01-25",
     "check_out_date": "2016-01-30",
     "total_booking_amount": 500,
     "booking_currency": "EUR"
   },
   "creation_date":"1492681635",
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address":
      {
        "class": "billing_address",
        "address1": "3B, SysPay",
        "address2": "Wied Ghomor Street",
        "address3": null,
        "city": "St. Julians",
        "country": "MT",
        "postal_code": "STJ2041"
      }
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details":{
        "class":"payment_method_details",
        "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
        "holder":"Card Holder Name",
        "scheme": "VISA",
        "exp_month":"01",
        "exp_year":"2016"
      }
   },
   "risk":{
      "class":"risk",
      "level":"HIGH",
      "reason":"INSUFFICIENT_FUNDS"
   }
}

Get a list of tokens

This method allows the merchant to get a list of tokens and their corresponding information.

URL syntax:/api/{version}/merchant/tokens Method:GET

URL parameters

Name	Type	Details	Mandatory	Description
status	string		N	The token status. see status
expiration_date_start	int	unix timestamp	N	The expiration start date from where you want to get the tokens in UTC.
expiration_date_end	int	unix timestamp	N	The expiration end date until where you want to get the tokens in UTC.
creation_date_start	int	unix timestamp	N	The creation start date from where you want to get the tokens in UTC.
creation_date_end	int	unix timestamp	N	The creation end date until where you want to get the tokens in UTC.
moto_instance_id	string		N	The phone booking instance id related to the token (see phone booking API for more information)
customer.email	string		N	The customer email.
payment_method.type	string		N	The payment method type. see payment method types
payment_method.validation_status	string		N	The payment method validation status. see validation status
page	int		N	The results page number requested.

Example requests

/api/v2/merchant/tokens?status=PENDING
/api/v2/merchant/tokens?expiration_date_start=1364957978
/api/v2/merchant/tokens?customer.email=test@test.com&payment_method.validation_status=VALID

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be list.
items_class	string	Y	The type of objects which are being returned in the data field as an array. In this case it will be token.
total_count	int	Y	The total number of search results.
pages	int	Y	The number of pages to hold all results.
page	int	Y	Current page being returned.
limit	int	Y	Number of results returned per page.
next_page	string|null	Y	A url which must be called to get the next page of tokens. Null if we’re already at the last page.
previous_page	string|null	Y	A url which must be called to get the previous page of tokens. Null if we’re already in the first page.
data	array	Y	The results corresponding to the current page. An array of token objects. see token

Example response

{
   "class": "list",
   "items_class": "token",
   "total_count": 1000,
   "pages": 10,
   "page": 2,
   "limit": 100,
   "next_page": "https:\/\/www.syspay.com\/api\/v2\/merchant\/tokens?status=ACTIVE&expiration_date_start=1424097095&page=3",
   "previous_page": "https:\/\/www.syspay.com\/api\/v2\/merchant\/tokens?status=ACTIVE&expiration_date_start=1424097095&page=1",
   "data":
     [
         { },
         { },
     ]
}

Get payment information

This method allows the merchant to get the payment status and information.

URL syntax:/api/{version}/merchant/payment/{payment_id} Method:GET

URL parameters

Name	Type	Details	Mandatory	Description
payment_id	int		Y	The reference id of the payment to be retrieved.

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment.
id	int	Y	The SysPay reference of the returned payment.
reference	string	Y	The merchant payment identifier which was passed in the request.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The payment status see status.
preauth_expiration_date	unix timestamp	Y	The preauth expiration date specifies until when a a preauth can be captured or voided. The transaction will be voided automatically once the preauth expires.
capture_date	unix timestamp	Y	The date after which the preauth may be automatically captured.
action_url	string	N	The url where the customer should be redirected to in order to provide further details required to complete the payment.
flow	string	Y	The flow used to process the payment.
processing_time	unix timestamp	Y	When the payment has been processed, null if the transaction is still not complete.
source	int	N	The id of the website the payment has been made for.
contract	string	N	The name of the payment processor.
descriptor	string	N	The payment description which will be shown on the card payment bank statement.
extra	string	N	The extra parameter which was sent on in the request call.
description	string	N	The merchant payment description.
account_id	int	Y	The SysPay account reference that the API access is linked to.
merchant_id	int	Y	The SysPay API access merchant reference.
merchant_login	string	Y	The SysPay API merchant login which proccessed the payment.
settlement_date	unix timestamp	N	A timestamp indicating when this payment will be settled.
failure_category	string	N	When a payment fails, this parameter will include extra information about the error (reference).
chip_and_pin_status	string	N	This field will be present on Chip&Pin transactions. When the payment has been made using the bluetooth device, the actual payment status will be kept OPEN until the transaction is really captured (which can take 1 business day). In order to let your web shop or native application know about the transaction results synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only.
token	object	N	The token details. see token.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method.
processor_reference	string	N	The reference of the transaction for the processor, in case of supergateway processing.

Example response

{
   "class":"payment",
   "id":123,
   "reference":"99967779",
   "amount":5000,
   "currency":"EUR",
   "status":"SUCCESS",
   "flow":"API",
   "processing_time":1423651917,
   "source":1,
   "contract":"SysPay",
   "descriptor":"Test Contract",
   "extra":null,
   "description":null,
   "account_id":1,
   "merchant_id":1,
   "merchant_login":"login1",
   "settlement_date":1424688717,
   "failure_category":null,
   "chip_and_pin_status":null,
   "token":null,
   "customer":
      {
         "class":"customer",
         "email":"test@domain.com",
         "language":"en",
         "firstname": "John",
         "lastname": "Doe",
         "billing_address":
         {
              "class": "billing_address",
              "address1": "3B, SysPay",
              "address2": "Wied Ghomor Street",
              "address3": null,
              "city": "St. Julians",
              "country": "MT",
              "postal_code": "STJ2041"
         }
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
               "holder":"Card Holder Name",
               "scheme": "VISA",
               "exp_month":"01",
               "exp_year":"2016"
            }
      },
   "processor_reference":"ref1234"
}

Get a list of payments

This method allows the merchant to get a list of payments and their corresponding information.

URL syntax:/api/{version}/merchant/payments Method:GET

URL parameters

Name	Type	Details	Mandatory	Description
amount	int		N	The amount of the payment
currency	string	[A-Z]{3}	N	The currency of the payment (ISO-4217)
request_time_start	int	unix timestamp	N	The request start date from where you want to get the payments in UTC
request_time_end	int	unix timestamp	N	The request end date until where you want to get the payments in UTC
processing_time_start	int	unix timestamp	N	The processing start date from where you want to get the payments in UTC
processing_time_end	int	unix timestamp	N	The processing end date until where you want to get the payments in UTC
source	int		N	The SysPay website reference
reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The merchant payment identifier
token_id	int		N	The token reference with an active mandate.
status	string		N	The payment status. see status
page	int		N	The results page number requested.

Example requests

/api/v2/merchant/payments?currency=EUR&processing_time_start=1363957978&processing_time_end=1364389978
/api/v2/merchant/payments?reference=999
/api/v2/merchant/payments?amount=5000&status=SUCCESS&source=16

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be list.
items_class	string	Y	The type of objects which are being returned in the data field as an array. In this case it will be payment.
total_count	int	Y	The total number of search results.
pages	int	Y	The number of pages to hold all results.
page	int	Y	Current page being returned.
limit	int	Y	Number of results returned per page.
next_page	string|null	Y	A url which must be called to get the next page of payments. Null if we’re already at the last page.
previous_page	string|null	Y	A url which must be called to get the previous page of payments. Null if we’re already in the first page.
data	array	Y	The results corresponding to the current page. An array of payment objects. see payment

Example response

{
   "class": "list",
   "items_class": "payment",
   "total_count": 1000,
   "pages": 10,
   "page": 2,
   "limit": 100,
   "next_page": "https:\/\/www.syspay.com\/api\/v2\/merchant\/payments?status=SUCCESS&processing_time_start=1424097095&page=3",
   "previous_page": "https:\/\/www.syspay.com\/api\/v2\/merchant\/payments?status=SUCCESS&processing_time_start=1424097095&page=1",
   "data":
     [
         { },
         { },
     ]

Get a list of operations

This method allows the merchant to get a list of operations and their corresponding information.

URL syntax:/api/{version}/merchant/operations/ Method:GET

Input parameters

Name	Type	Details	Mandatory	Description
operation_id	int	UNIQUE	N	The syspay identifier.
operation_status	array		N	The operation status (see status).
operation_type	array		N	The type of operations (see type) .
booking	string	UNIQUE	N	The merchant operation identifier.
booking_time_start	int	unix timestamp	N	The creation start date from where you want to get the tokens in UTC.
booking_time_end	int	unix timestamp	N	The creation end date until where you want to get the tokens in UTC.
operation_time_start	int	unix timestamp	N	The creation start date from where you want to get the operations in UTC
operation_time_end	int	unix timestamp	N	The creation end date until where you want to get the operations in UTC.
processing_time_start	int	unix timestamp	N	The start processing date when the operation has been processed, null if the transaction is still not complete.
processing_time_end	int	unix timestamp	N	The end procedding date when the operation has been processed, null if the transaction is still not complete.
check_in_start	int	unix timestamp	N	The start check_in date of the booking.
check_in_end	int	unix timestamp	N	The end check_in date of the booking.
check_out_start	int	unix timestamp	N	The start check out date of the booking.
check_out_end	int	unix timestamp	N	The end check out date of the booking.
customer	string		N	Part of the name of the customer.
email	string	valid email address	N	Customers email address.
page	int		N	Number of page

Example requests

/api/{version}/merchant/operations/?booking_time_start=1363957978&booking_time_end=1364389978
/api/{version}/merchant/operations/?booking=999
/api/{version}/merchant/operations/?operation_status[]=SUCCESS

Response parameters

Name	Type	Mandatory	Description
operation.id	int		The SysPay operation reference.
operation.feature_name	string	Y	The API ‘s name .
operation.processing_time	unix timestamp	N	When the payment has been processed, null if the transaction is still not complete..
operation.operation_time	unix timestamp	N	The timestamp when the operation is created.
operation.booking_time	unix timestamp	N	The timestamp when the token is created.
operation.checking_in	unix timestamp	N	The check_in date of the booking.
operation.checking_out	unix timestamp	N	The check_out date of the booking.
operation.booking	string	N	The partner reference of the booking.
operation.customer	string	N	The customer first name combine with the last name.
operation.payment_method	string	N	A payment method-specific string that can be used to identify the payment method used.
operation.scheme	string	N	Credit card scheme.
operation.type	string	N	Type of operation.
operation.amount	string	N	The amount in cents.
operation.currency	string	N	The currency.
operation.source	string	N	The source of operation.
operation.fee	int	N	The fee of the operation.
operation.status	string	N	The status of the operation.

Example response

"data": [
{
  "class": "Operation",
  "id": 50,
  "feature_name": "Processing",
  "processing_time": "1633000748",
  "operation_time": "1633000745",
  "booking_time": "1633000744",
  "checking_in": null,
  "checking_out": null,
  "booking_reference": "dasd",
  "customer": "Ashley Connell",
  "email": "",
  "payment_method": "5420-71xx-xxxx-0010",
  "scheme": null,
  "type": "BillingAgreement",
  "amount": null,
  "currency": "EUR",
  "source": "Processing",
  "fee": null,
  "status": "SUCCESS"
},
{
  "class": "Operation",
  "id": 51,
  "feature_id": "Processing",
  "processing_time": null,
  "operation_time": "1633000745",
  "booking_time": "1633000769",
  "checking_in": null,
  "checking_out": null,
  "booking_reference": null,
  "customer": "Ashley Connell",
  "email": null,
  "payment_method": "5420-71xx-xxxx-0010",
  "scheme": "MASTERCARD",
  "type": "Payment",
  "amount": "5500",
  "currency": "EUR",
  "source": "Processing",
  "fee": null,
  "status": "OPEN"
},

Capture a pre-authorization

This method allows the merchant to capture a pre authorized payment and move the money from the customer bank account to the merchant SysPay account. This updates the status of the payment from AUTHORIZED to SUCCESS.

URL syntax:/api/{version}/merchant/payment/{payment_id}/capture Method:POST

URL parameters

Name	Type	Details	Mandatory	Description
payment_id	int		Y	The reference id of the payment to be captured.

Example request

/api/{version}/merchant/payment/123/capture

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment.
id	int	Y	The SysPay reference of the returned payment.
reference	string	Y	The merchant payment identifier which was passed in the request.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The payment status see status.
preauth_expiration_date	unix timestamp	Y	The preauth expiration date specifies until when a a preauth can be captured or voided. The transaction will be voided automatically once the preauth expires.
capture_date	unix timestamp	Y	The date after which the preauth may be automatically captured.
action_url	string	N	The url where the customer should be redirected to in order to provide further details required to complete the payment.
flow	string	Y	The flow used to process the payment.
processing_time	unix timestamp	Y	When the payment has been processed, null if the transaction is still not complete.
source	int	N	The id of the website the payment has been made for.
contract	string	N	The name of the payment processor.
descriptor	string	N	The payment description which will be shown on the card payment bank statement.
extra	string	N	The extra parameter which was sent on in the request call.
description	string	N	The merchant payment description.
account_id	int	Y	The SysPay account reference that the API access is linked to.
merchant_id	int	Y	The SysPay API access merchant reference.
merchant_login	string	Y	The SysPay API merchant login which proccessed the payment.
settlement_date	unix timestamp	N	A timestamp indicating when this payment will be settled.
failure_category	string	N	When a payment fails, this parameter will include extra information about the error (reference).
chip_and_pin_status	string	N	This field will be present on Chip&Pin transactions. When the payment has been made using the bluetooth device, the actual payment status will be kept OPEN until the transaction is really captured (which can take 1 business day). In order to let your web shop or native application know about the transaction results synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only.
token	object	N	The token details. see token.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method.
processor_reference	string	N	The reference of the transaction for the processor, in case of supergateway processing.

Example response

{
   "class":"payment",
   "id":123,
   "reference":"99967779",
   "amount":5000,
   "currency":"EUR",
   "status":"SUCCESS",
   "flow":"API",
   "processing_time":1423651917,
   "source":1,
   "contract":"SysPay",
   "descriptor":"Test Contract",
   "extra":null,
   "description":null,
   "account_id":1,
   "merchant_id":1,
   "merchant_login":"login1",
   "settlement_date":1424688717,
   "failure_category":null,
   "chip_and_pin_status":null,
   "token":null,
   "customer":
      {
         "class":"customer",
         "email":"test@domain.com",
         "language":"en",
         "firstname": "John",
         "lastname": "Doe",
         "billing_address":
         {
           "class": "billing_address",
           "address1": "3B, SysPay",
           "address2": "Wied Ghomor Street",
           "address3": null,
           "city": "St. Julians",
           "country": "MT",
           "postal_code": "STJ2041"
         }
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
               "holder":"Card Holder Name",
               "scheme": "VISA",
               "exp_month":"01",
               "exp_year":"2016"
            }
      },
   "processor_reference":"ref1234"
}

Void a pre-authorization

This method allows the merchant to void a pre authorized payment so the customer is not charged the payment. This updates the status of the payment from AUTHORIZED to VOIDED.

URL syntax:/api/{version}/merchant/payment/{payment_id}/void Method:POST

URL parameters

Name	Type	Details	Mandatory	Description
payment_id	int		Y	The reference id of the payment to be voided.

Example requests

/api/{version}/merchant/payment/123/void

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment.
id	int	Y	The SysPay reference of the returned payment.
reference	string	Y	The merchant payment identifier which was passed in the request.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The payment status see status.
preauth_expiration_date	unix timestamp	Y	The preauth expiration date specifies until when a a preauth can be captured or voided. The transaction will be voided automatically once the preauth expires.
capture_date	unix timestamp	Y	The date after which the preauth may be automatically captured.
action_url	string	N	The url where the customer should be redirected to in order to provide further details required to complete the payment.
flow	string	Y	The flow used to process the payment.
processing_time	unix timestamp	Y	When the payment has been processed, null if the transaction is still not complete.
source	int	N	The id of the website the payment has been made for.
contract	string	N	The name of the payment processor.
descriptor	string	N	The payment description which will be shown on the card payment bank statement.
extra	string	N	The extra parameter which was sent on in the request call.
description	string	N	The merchant payment description.
account_id	int	Y	The SysPay account reference that the API access is linked to.
merchant_id	int	Y	The SysPay API access merchant reference.
merchant_login	string	Y	The SysPay API merchant login which proccessed the payment.
settlement_date	unix timestamp	N	A timestamp indicating when this payment will be settled.
failure_category	string	N	When a payment fails, this parameter will include extra information about the error (reference).
chip_and_pin_status	string	N	This field will be present on Chip&Pin transactions. When the payment has been made using the bluetooth device, the actual payment status will be kept OPEN until the transaction is really captured (which can take 1 business day). In order to let your web shop or native application know about the transaction results synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only.
token	object	N	The token details. see token.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method.
processor_reference	string	N	The reference of the transaction for the processor, in case of supergateway processing.

Example response

{
   "class":"payment",
   "id":123,
   "reference":"99967779",
   "amount":5000,
   "currency":"EUR",
   "status":"VOIDED",
   "flow":"API",
   "processing_time":1423651917,
   "source":1,
   "contract":"SysPay",
   "descriptor":"Test Contract",
   "extra":null,
   "description":null,
   "account_id":1,
   "merchant_id":1,
   "merchant_login":"login1",
   "settlement_date":null,
   "failure_category":null,
   "chip_and_pin_status":null,
   "token":null,
   "customer":
      {
         "class":"customer",
         "email":"test@domain.com",
         "language":"en",
         "firstname": "John",
         "lastname": "Doe",
         "billing_address":
         {
           "class": "billing_address",
           "address1": "3B, SysPay",
           "address2": "Wied Ghomor Street",
           "address3": null,
           "city": "St. Julians",
           "country": "MT",
           "postal_code": "STJ2041"
         }
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
               "holder":"Card Holder Name",
               "scheme": "VISA",
               "exp_month":"01",
               "exp_year":"2016"
            }
      },
   "processor_reference":"ref1234"
}

Refund a payment

This method allows the merchant to refund a payment. The response includes a redirect URL, to which the customer has to be routed to confirm and complete the refund process.

URL syntax:/api/{version}/merchant/refund Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
payment_id	int		Y	SysPay payment reference of the payment you want to refund.
reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	Y	Merchant refund identifier, must be unique for each refund.
amount	int		Y	The amount to refund back to the customer must be equal or less than the original payment amount.
currency	string	[A-Z]{3}	Y	The refund currency, should be the same as the currency of the original payment (ISO-4217).
description	string	max length 300	N	The description of this refund.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
ems_url	string		N	This parameter overrides the default ems_url set in the user backend.

Example request

{
    "payment_id": "1458",
    "reference": "998249",
    "amount": "5000",
    "currency": "EUR",
    "description": "goods could not be delivered",
    "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
    "ems_url": "http:\/\/www.mysite.com\/ems.php"
}

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be refund.
id	int	Y	The SysPay reference of the returned refund.
reference	string	Y	The Merchant refund identifier which was sent on in the request call.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The refund status. see status.
processing_time	unix timestamp	Y	The time stamp of when the refund was processed. Null is returned if the transaction is still not complete.
description	string	N	The refund description which was sent on in the request call.
extra	string	N	The extra parameter which was sent on in the request call.
payment	object	Y	The original payment object. see payment.
failure_category	string	N	When a refund fails, this parameter will include extra information about the error (reference).

Example response

{
   "class":"refund",
   "id":64,
   "reference":"998249",
   "amount":5000,
   "currency":"EUR",
   "status":"SUCCESS",
   "processing_time":1367488337,
   "description":"goods could not be delivered",
   "extra":"Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
   "payment":{ }
}

Get refund information

This method allows the merchant to get the refund status and information.

URL syntax:/api/{version}/merchant/refund/{refund_id} Method:GET

URL parameters

Name	Type	Details	Mandatory	Description
refund_id	int		Y	The reference id of the refund to be retrieved.

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be refund.
id	int	Y	The SysPay reference of the returned refund.
reference	string	Y	The Merchant refund identifier which was sent on in the request call.
amount	int	Y	The amount in cents.
currency	string	Y	The currency (ISO-4217).
status	string	Y	The refund status. see status.
processing_time	unix timestamp	Y	The time stamp of when the refund was processed. Null is returned if the transaction is still not complete.
description	string	N	The refund description which was sent on in the request call.
extra	string	N	The extra parameter which was sent on in the request call.
payment	object	Y	The original payment object. see payment.
failure_category	string	N	When a refund fails, this parameter will include extra information about the error (reference).

Example response

{
   "class":"refund",
   "id":64,
   "reference":"998249",
   "amount":5000,
   "currency":"EUR",
   "status":"SUCCESS",
   "processing_time":1367488337,
   "description":"goods could not be delivered",
   "extra":"Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
   "payment":{ }
}

Update an existing token

This method allows the merchant to update specific parameter/s of an existing token.

URL syntax:/api/{version}/merchant/token/{token_id} Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note on Hosted Token Request Section)
expiration_date	unix timestamp		N*	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token.
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	N	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	N*	The check_in date of the booking. (*Required if check_out_date is provided).
booking_details.check_out_date	string	YYYY-mm-dd	N*	The check_out date of the booking. (*Required if check_in_date is provided). If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		N*	The total booking fee amount. (*Required if booking_currency is provided).
booking_details.booking_currency	string	[A-Z]{3}	N*	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform. (*Required if total_booking_amount is provided).

Example request

{
    "authorized_detokenizers": [18223,19726],
    "booking_details": {
      "type": "HOTEL",
      "booking_id": "test-ref",
      "check_in_date": "2016-01-25",
      "check_out_date": "2016-01-30",
      "total_booking_amount": 500,
      "booking_currency": "EUR"
    },
    "expiration_date": "1469871761"
}

Response parameters

The response returned by the service is similar to the token creation one. Depending on the service level (STORAGE/VERIFICATION/PROCESSING), the response could contain an extra mandate object containing the mandate status and its details.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response (without mandate creation)

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_details": {
     "type": "HOTEL",
     "booking_id": "test-ref",
     "check_in_date": "2016-01-25",
     "check_out_date": "2016-01-30",
     "total_booking_amount": 500,
     "booking_currency": "EUR"
   },
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address": null
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2015"
      }
   },
   "risk":{
      "class":"risk",
      "level":"HIGH",
      "reason":"INSUFFICIENT_FUNDS"
   }
}

Example response (including mandate info)

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": null,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1520464268",
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address": null
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "display": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null,
    "details": {
      "class":"payment_method_details",
      "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2015"
    }
  },
  "mandate": {
    "class": "mandate",
    "status": "ACTIVE",
    "end_reason": null,
    "start_date": 1423753881,
    "end_date": null
  },
  "risk":{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
  }
}

Revalidate an existing token

This method allows the merchant to revalidate an existing token.

URL syntax:/api/{version}/merchant/token/{token_id}/validate Method:POST

URL parameters

Name	Type	Details	Mandatory	Description
token_id	int		Y	The reference id of the token to be revalidated.

Example requests

/api/{version}/merchant/token/123/validate

Response parameters

The response returned by the service is similar to the token creation one. Depending on the service level (STORAGE/VERIFICATION/PROCESSING), the response could contain an extra mandate object containing the mandate status and its details.

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response (without mandate creation)

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_details": {
     "type": "HOTEL",
     "booking_id": "test-ref",
     "check_in_date": "2016-01-25",
     "check_out_date": "2016-01-30",
     "total_booking_amount": 500,
     "booking_currency": "EUR"
   },
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address": null
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2015"
      }
   },
   "risk":{
      "class":"risk",
      "level":"HIGH",
      "reason":"INSUFFICIENT_FUNDS"
   }
}

Example response (including mandate info)

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": null,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-refd",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": "1520464268",
  "customer": {
    "class": "customer",
    "email": "test@domain.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address": null
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "display": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null,
    "details": {
      "class":"payment_method_details",
      "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2015"
    }
  },
  "mandate": {
    "class": "mandate",
    "status": "ACTIVE",
    "end_reason": null,
    "start_date": 1423753881,
    "end_date": null
  },
  "risk":{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
  }
}

Import token request

This method allows the merchant to create a token directly by providing the payment method details within the request. This method will just store the card within our system for future use. It is suggested that this method is mainly used for importing of card information into our system.

Note: By default, a token cannot be de-tokenized by anyone unless explicitly specified by giving a list of authorized detokenizers in the authorized_detokenizers parameter. This parameter can only accept up to two ids. If two are provided, one must be your own partner id, (to allow yourself to de-tokenize) the other one is a partner you allow to view the token details.

URL syntax:/api/{version}/merchant/token/import Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
source	int		N	The property reference for which this token request is.
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	Y	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	Y	The check_in date of the booking.
booking_details.check_out_date	string	YYYY-mm-dd	Y	The check_out date of the booking. If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		Y	The total booking fee amount in cents (500 XXX = 5.00 XXX).
booking_details.booking_currency	string	[A-Z]{3}	Y	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform.
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
ems_url	string		N	This parameter overrides the default ems_url configuration set in the user backend.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements made of your own partner id and/or another one (see the note above)
customer.firstname	string	max length 100	N	The customer’s first name
customer.lastname	string	max length 100	N	The customer’s last name
customer.ip	string		N	The customer public ip address.
customer.email	string	valid email address	N	The customer email address.
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
customer.reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	N	The customer’s reference
customer.address_country	string	ISO 3166-1 alpha-2 country code	N	The customer’s address’ country. This parameter will be phased out when 3DS2 becomes mandatory
customer.login	string	max length 150	N	The customer’s login
customer.password_hash	string	max length 64	N	The customer’s password hash
payment_method.type	string	CREDITCARD	N	The type of payment object to be passed in the api call.

Method-specific parameters

Method: CREDITCARD

Name	Type	Details	Mandatory	Description
payment_method.cardholder	string	max length 100	Y	Cardholder name. Please note that non-alphabetic characters other than @ . - _ ‘ will be stripped out. Names containing digits will be rejected by validation.
payment_method.number	string	[0-9]{12,19}	Y	Valid credit card number, only digits.
payment_method.exp_month	string	[0-9]{2}	Y	Credit card expire month (ex: 05).
payment_method.exp_year	string	[0-9]{4}	Y	Credit card expire year (ex: 2015).
payment_method.cvc	int	[0-9]{3,4}	N	Credit card verification code. The CVC is always required if interactive is true or if interactive is false and your API settings do not allow you to process payments or create mandates without providing it.

Example request

{
  "source": 1,
  "booking_details": {
    "type": "HOTEL",
    "booking_id": "test-ref",
    "check_in_date": "2016-01-25",
    "check_out_date": "2016-01-30",
    "total_booking_amount": 500,
    "booking_currency": "EUR"
  },
  "expiration_date": 1420464268,
  "ems_url": "http://www.mysite.com/ems.php",
  "authorized_detokenizers": [
    42,
    9000
  ],
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "reference": "ref-1234",
    "language": "en",
    "address_country": "FR",
    "login": "username",
    "password_hash": "p@55w0rd_#"
  },
  "payment_method": {
    "type": "CREDITCARD",
    "number": 4111111111111111,
    "cardholder": "Card Holder Name",
    "exp_month": "01",
    "exp_year": "2015"
  }
}

Response parameters

In this case since the token is being imported no VALIDATION or MANDATE processing will be performed irrelevant of the service level (STORAGE/VERIFICATION/PROCESSING).

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_details": {
     "type": "HOTEL",
     "booking_id": "test-ref",
     "check_in_date": "2016-01-25",
     "check_out_date": "2016-01-30",
     "total_booking_amount": 500,
     "booking_currency": "EUR"
   },
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en",
      "firstname": "John",
      "lastname": "Doe",
      "billing_address": null
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "NOT_VALIDATED",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "fingerprint": "d7e4fd6f-9aa3-4ae0-80f9-dafeb3581a22",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2015"
      }
   },
   "risk":{
      "class":"risk",
      "level":null,
      "reason":null
   }
}

Get a list of iDeal banks

This method returns a list of all banks handled by iDeal.

URL syntax:/api/v2/merchant/payment-method/ideal/banks Method:GET

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be ideal_banks.
updated	unix timestamp	Y	This is used to check whether the list of banks has been updated.
banks	array	Y	A list of iDeal banks
bank.id	integer	Y	The iDeal bank reference. This value is to be used in payment requests to indicate which bank should be used.
bank.name	string	Y	The name of the bank.
bank.country	string	Y	The country of the bank.

Example response

{
   "class":"ideal_banks",
   "updated":1370858310,
   "banks":
   [
      {
         "class":"bank",
         "id":1,
         "name":"Issuer Simulation V3 - ING",
         "country":"Nederland"
      },
      {
         "class":"bank",
         "id":2,
         "name":"Issuer Simulation V3 - RABO",
         "country":"Nederland"
      }
   ]
}