Objects Reference¶

The objects returned by the API will always include a class property that will tell you the object type. Each class has its own set of related properties.

Token¶

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¶

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "booking_id":"test-ref",
   "check_in_date":"2015-08-22",
   "check_out_date":"2015-08-24",
   "expiration_date":1421426671,
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en"
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "validation_date":"1443607554",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2016"
      }
   }
}

Mandate¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be mandate
status	string	Y	The status of the mandate. see status.
currency	string	Y	The mandate currency (ISO-4217).
end_reason	string	N	Reason why the mandate has ended.
start_date	string	N	The date when the mandate was authorized by the customer.
end_date	string	N	The date when the mandate ended.

Example¶

{
    "class":"mandate",
    "status":"ACTIVE",
    "currency":"EUR",
    "end_reason":null,
    "start_date":1423755674,
    "end_date":null
}

Payment¶

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¶

{
    "class":"payment",
    "id":16,
    "reference":"Unqiue-111111",
    "amount":5000,
    "currency":"EUR",
    "status":"SUCCESS",
    "preauth_expiration_date":"1421426671",
    "action_url": null,
    "flow":"API",
    "processing_time":1423501843,
    "website":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":"token",
        "id":7,
        "status":"ACTIVE",
        "action_url":null,
        "booking_id":"test-ref",
        "check_in_date":"2015-08-22",
        "check_out_date":"2015-08-24",
        "expiration_date":1421426671,
        "customer":{
            "class":"customer",
            "email":"test@domain.com",
            "language":"en"
        },
        "payment_method":{
            "class":"payment_method",
            "type":"CREDITCARD",
            "display":"4111-11xx-xxxx-1111",
            "validation_status": "VALID",
            "validation_date":"1443607554",
            "invalid_reason": null,
            "details":{
                "class":"payment_method_details",
                "holder":"Card Holder Name",
                "scheme": "VISA",
                "exp_month":"01",
                "exp_year":"2016"
            }
        }
    },
    "customer":{
        "class":"customer",
        "email":"test@domain.com",
        "language":"en"
    },
    "payment_method":{
        "class":"payment_method",
        "type":"CREDITCARD",
        "display":"4111-11xx-xxxx-1111",
        "validation_status": "VALID",
        "validation_date":"1443607554",
        "invalid_reason": null,
        "details":{
            "class":"payment_method_details",
            "holder":"Card Holder Name",
            "scheme": "VISA",
            "exp_month":"01",
            "exp_year":"2016"
        }
    },
    "processor_reference":"ref1234"
}

Payment Method¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment_method.
type	string	N	The payment method type. See the available payment method types
display	string	N	A payment method-specific string that can be used to identify the payment method used.
validation_status	string	N	The card validation status. See the available statuses. For creditcards only, and if validation is enabled for your account.
validation_date	unix timestamp	N	The card’s last validation date. For creditcards only, and if validation is enabled for your account.
invalid_reason	string	N	If the card validation status is invalid this field will specify the reason. See the invalid reason codes.
details	object	N	The payment method details object. The parameters returned differ according to the payment method type. see payment method details.

Example¶

{
    "class":"payment_method",
    "type":"CREDITCARD",
    "display":"4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "validation_date":"1443607554",
    "invalid_reason": null,
    "details":
    {
        "class":"payment_method_details",
        "holder":"Card Holder Name",
        "scheme": "VISA",
        "exp_month":"01",
        "exp_year":"2016"
    }
}

Payment Method Details¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be payment_method_details.

Method-specific parameters¶

Method: CREDITCARD¶

Name	Type	Mandatory	Description
payment_method_details.fingerprint	string	Y	The credit card fingerprint Uuid.
payment_method_details.holder	string	Y	The credit card holder name.
payment_method_details.scheme	string	Y	Credit card scheme. See the payment method credit card type schemes.
payment_method_details.exp_month	string	Y	Credit card expire month (ex: 01).
payment_method_details.exp_year	string	Y	Credit card expire year (ex: 2016).

Method: SEPA DIRECT PAYMENT | IDEAL | SOFORT¶

Name	Type	Mandatory	Description
payment_method_details.fingerprint	string	Y	The bank account fingerprint Uuid.
payment_method_details.holder	string	Y	The bank account holder name.
payment_method_details.iban	string	Y	The bank account IBAN code.
payment_method_details.bic	string	Y	The bank account BIC/SWIFT code.

Example¶

{
    "class":"payment_method_details",
    "holder":"Card Holder Name",
    "scheme": "VISA",
    "exp_month":"01",
    "exp_year":"2016"
}

Payment Method Options¶

Parameters¶

Name	Type	Mandatory	Details	Description
type	string	Y	CREDITCARD	The payment method type which will be affected by this option
three_ds	string	N*	MUST\|PREFER\|DONT_CARE\|NEVER	Option to override the 3d preference (*Required if type is set to CREDITCARD)

Example¶

{
    "type" : "CREDITCARD",
    "three_ds" : "MUST"
}

Customer¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be customer.
email	string	N	The customer email address.
language	string	N	The customer language according to (ISO-639-1).
firstname	string	N	The customer first name.
lastname	string	N	The customer last name.
billing_address	object	N	The customer’s billing address. see billing address

Example¶

{
    "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"
    }
}

Device¶

Parameters¶

Name	Type	Mandatory	Description
type	string	Y	The device used to process the payment. Browser is currently the only supported type
browser_width	int	Y	Total width of the screen in pixels
browser_height	int	Y	Total width of the screen in pixels
browser_time_zone_offset	int	Y	Time difference between UTC time and the browser local time, in minutes
browser_color_depth	int	Y	Value representing the bit depth of the colour palette, in bits per pixel. (Accepted values: 1, 4, 8, 15, 16, 24, 32, 48)
browser_java_enabled	bool	Y	Represents the ability of the browser to execute Java
browser_language	string	Y	Value representing the browser language as defined in IETF BCP47
accept_header	string	Y	Exact content of the HTTP accept headers
user_agent_header	string	Y	Exact content of the HTTP user-agent header

Example¶

{
   "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"
}

Billing Address¶

Parameters¶

Name	Type	Details	Mandatory	Description
address1	string		Y	Cardholder Billing address
address2	string		N	Cardholder Billing address
address3	string		N	Cardholder Billing address
city	string		Y	Cardholder Billing address city
country	string	ISO 3166-1 alpha-2 country code	Y	Cardholder Billing address country
postal_code	string		Y	Cardholder Billing address postal code

Example¶

{
    "address1": "3B, SysPay",
    "address2": "Wied Ghomor Street",
    "city": "St. Julians",
    "country": "MT",
    "postal_code": "STJ2041"
}

Error¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be error.
message	string	Y	The error message.
property	string	N	The parameter which caused an error.
code	string	N	The error code. see error_codes.
data	string	N	The invalid data.

Example¶

{
   "class":"error",
   "property":"website",
   "message":"Website not found",
   "code":20006,
   "data":"60"
}

Reference¶

Note¶

Sometimes you might encounter an object of the special reference class. This has been created in order to avoid circular references, for example when making a server-2-server token creation including an initial payment where a token includes a payment which also includes the token this payment was made on. In this case the token in the payment object will be a reference.

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be reference.
type	string	Y	The actual class of the object being referenced.
id	string	Y	The id of the object.
link	string	N	If our API provides a service to access this object’s details, this property will include the link to retrieve it.

Example¶

{
  "class": "reference",
  "type": "token",
  "id": 7,
  "link": "https://www.syspay.com/api/v2/merchant/token/1"
}

Moto Instance (Phone Booking)¶

Parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be moto_instance
id	string	Y	The instance unique identifier
action_url	string	Y	The URL to use the generated instance

Example¶

{
    "class":"moto_instance",
    "id":"555f0310b1afb0cf6c5a19c1",
    "action_url":"https:\/\/app.syspay.com\/moto-instance\/dmnzrj9y4np83vcffngzuc33yhkbqanz"
}

Risk¶

Parameters¶

Name	Type	Details	Mandatory	Description
class	string		Y	The type of object which is being returned. In this case it will be risk
level	string	HIGH\|MEDIUM\|LOW	N	The risk level.
reason	string	PREPAID\|COUNTRY_MISMATCH\|INSUFFICIENT_FUNDS\|BANK_DECLINED\|EXPIRY_DATE\|3DS\|SCHEME_NOT_SUPPORTED\|NOT_ENOUGH_DATA_FROM_BANK	N	The risk level reason.

Example¶

{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
}

Booking Details¶

Parameters¶

Name	Type	Details	Mandatory	Description
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.

Example¶

{
    "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"
}

Navigation

Table Of Contents

Objects Reference¶

Token¶

Parameters¶

Example¶

Mandate¶

Parameters¶

Example¶

Payment¶

Parameters¶

Example¶

Payment Method¶

Parameters¶

Example¶

Payment Method Details¶

Parameters¶

Method-specific parameters¶

Method: CREDITCARD¶

Method: SEPA DIRECT PAYMENT | IDEAL | SOFORT¶

Example¶

Payment Method Options¶

Parameters¶

Example¶

Customer¶

Parameters¶

Example¶

Device¶

Parameters¶

Example¶

Billing Address¶

Parameters¶

Example¶

Error¶

Parameters¶

Example¶

Reference¶

Note¶

Parameters¶

Example¶

Moto Instance (Phone Booking)¶

Parameters¶

Example¶

Risk¶

Parameters¶

Example¶

Booking Details¶

Parameters¶

Example¶

Navigation