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

In order to authenticate to our API, your request must provide an X-Wsse header that matches the following pattern:

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

Where:

• merchantLogin is your 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))

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

Example code (PHP)

<?php

function generateHeaders($merchantLogin, $passphrase) {
  $nonce = md5(rand(), true);
  $timestamp = time();

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

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

  return $header;
}

generateHeaders("mylogin", "mypassphrase");

You would expect the following output::

X-Wsse: AuthToken MerchantAPILogin="mylogin", PasswordDigest="pIHzLACUUUZjsDkugJZnWESHYFQ=", Nonce="Uc7+N/ygEmQAfOOvrYHOow==", Created="1369414302"

Errors

When a request is not valid or is not succesfully 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.

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 website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
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.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
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.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

Example request (hosted page)

{
  "flow": "BUYER",
  "source": 16,
  "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",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "language": "en",
    "reference": "ref-1234",
    "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 mandate request parameter, the token creation could include the 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.
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.
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.
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",
  "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 mandate creation)

{
  "class": "token",
  "id": "8",
  "status": "REDIRECT",
  "action_url": "http://www.syspay.com/redirect/hosted/token/28",
  "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.

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

Input parameters

Example request (hosted page)

{
  "flow": "BUYER",
  "source": 16,
  "description": "Shopping basket payment",
  "return_url": "http:\/\/www.mysite.com\/return.php",
  "ems_url": "http:\/\/www.mysite.com\/ems.php",
  "notify": "EMAIL",
  "mandate": true,
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "test@domain.com",
    "language": "en",
    "reference": "ref-1234",
    "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

Depending on the mandate request parameter, the token creation could include the 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.
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.
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.
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": "https:\/\/app.syspay.com\/redirect\/payment\/80\/eea8ed0769d0984eb52b6f6e035642fca0e60a61\/HOSTED?_locale=fr",
  "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,
  "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"
}

Example response (with mandate creation)

{
  "class": "token",
  "id": "8",
  "status": "REDIRECT",
  "action_url": "https:\/\/app.syspay.com\/redirect\/payment\/80\/eea8ed0769d0984eb52b6f6e035642fca0e60a61\/HOSTED?_locale=fr",
  "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"
}

Hosted payment request

This method allows the merchant to initiate a payment 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.

URL syntax:/api/{version}/merchant/payment 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 website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
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.
reference	string	UNIQUE, [ -~]+ (max: 85 ascii printable characters)	Y	The merchant payment identifier for the request. This must be unique for each request.
mandate	boolean	true|false	N	If set to true, a token with a mandate will be created along the process of the passed payment request.
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.
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
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. The list of currencies you are allowed to process can be checked from the settings page in the user backend.
notify	string	EMAIL	N	The notification method for the BUYER flow to be used within this API request.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or event message.
recipient_map	array		N	Array of ‘payment recipients’ directives to pay out (part(s) of) the payment to other accounts (see Paying out to other accounts on how to build a recipient)
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_method_options	array	payment method options	N	Extra parameters to override payment method options

Example request

 {
    "flow": "BUYER",
    "source": 123,
    "extra": "extra",
    "reference": "Unqiue-111111",
    "description": "Shopping basket payment",
    "amount": 5000,
    "currency": "EUR",
    "return_url": "http:\/\/www.mysite.com\/return.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "customer": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "test@domain.com",
        "language": "en",
        "reference": "ref-1234",
        "ip":"80.90.62.101",
        "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_options": [
        {
            "type" : "CREDITCARD",
            "three_ds" : "MUST"
        }
    ]
}

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":75,
  "reference":"Unqiue-111111",
  "amount":5000,
  "currency":"EUR",
  "status":"OPEN",
  "action_url":"https:\/\/app.syspay.com\/redirect\/payment\/27\/296bcd0a084b8b7c7f84534b66e701839dea522d\/HOSTED?_locale=en",
  "flow":"BUYER",
  "processing_time":null,
  "source":null,
  "contract":null,
  "descriptor":null,
  "extra":"extra",
  "description":"Shopping basket payment",
  "account_id":123,
  "merchant_id":123,
  "merchant_login":"****",
  "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":null,
  "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.

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 website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
interactive	boolean	1|0	Y	This parameter specifies whether the paying customer is present or not.
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.
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.} 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.
payment_method.token_id	int		N	The token reference with an active mandate. If this is given, then there is no need to give the others except CVC if it is required.

Example request

 {
    "flow": "API",
    "source": 1,
    "interactive": "0",
    "return_url": "http:\/\/www.mysite.com\/return.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "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": "2016",
        "cvc": "123"
    }
}

Response parameters

Depending on the mandate request parameter, the token creation could include the 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.
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.
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.
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": "1",
  "status": "ACTIVE",
  "action_url": 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": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null
  },
}

Example response (with mandate creation)

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": 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": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null
  },
  "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.

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	The website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
interactive	boolean	1|0	Y	This parameter specifies whether the paying customer is present or not.
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 lenght 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.
mandate	boolean	true|false	N	This flag will determine if the token can be used to make future payments.
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.} 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. This will also be the default currency for the created mandate.
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.recipient_map	array		N	Array of ‘payment recipients’ directives to pay out (part(s) of) the payment to other accounts (see Paying out to other accounts on how to build a recipient)
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.
payment_method.token_id	int		N	The token reference with an active mandate. If this is given, then there is no need to give the others except CVC if it is required.

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,
  "interactive": "0",
  "return_url": "http:\/\/www.mysite.com\/return.php",
  "ems_url": "http:\/\/www.mysite.com\/ems.php",
  "mandate": true,
  "description": "Shopping basket payment",
  "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "test@domain.com",
      "language": "en",
      "reference": "ref-1234",
      "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": "2016",
      "cvc": "123"
  },
  "payment": {
      "reference": "Unqiue-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

Depending on the mandate request parameter, the token creation could include the 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.
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.
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.
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": "1",
  "status": "ACTIVE",
  "action_url": 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": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null
  },
  "payment": {
    "class": "payment",
    "id": 16,
    "reference": "Unique-111111",
    "amount": 5000,
    "currency": "EUR",
    "status": "SUCCESS",
    "action_url": 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
    },
    "processor_reference":"ref1234"
  },
  "risk":{
    "class":"risk",
    "level":"HIGH",
    "reason":"INSUFFICIENT_FUNDS"
  }
}

Example response (with mandate creation)

{
  "class": "token",
  "id": "1",
  "status": "ACTIVE",
  "action_url": 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": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null
  },
  "payment": {
    "class": "payment",
    "id": 16,
    "reference": "Unique-111111",
    "amount": 5000,
    "currency": "EUR",
    "status": "SUCCESS",
    "action_url": 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
    },
    "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 rebill request on a token with mandate

This method allows the merchant to take a payment on an existing token with an active 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 with an active mandate.
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.
interactive	boolean	1|0	N	This parameter specifies whether the paying customer is present or not. Defaults to false.
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.

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",
    "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "test@domain.com",
      "language": "en",
      "reference": "ref-1234",
      "address_country": "FR",
      "login": "username",
      "password_hash": "p@55w0rd_#"
    }
}

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_id":"test-ref",
    "check_in_date":"2015-08-22",
    "check_out_date":"2015-08-24",
    "expiration_date": 1523737892,
    "description": "description",
    "customer": {
      "class": "customer",
      "email": "test@domain.com",
      "language": "en",
      "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": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
        "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": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
      "holder":"Card Holder Name",
      "scheme": "VISA",
      "exp_month":"01",
      "exp_year":"2016"
    }
  }
}

Server-to-Server payment request

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

URL syntax:/api/v2/merchant/payment 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 website reference for which this payment request is. (The website/s reference id/s can be checked from the user backend settings page).
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. The list of currencies you are allowed to process can be checked from the settings page in the user backend.
description	string	max lenght 300	N	The product/service description.
interactive	boolean	1|0	Y	This parameter specifies whether the paying customer is present or not.
extra	string	max length 300	N	An extra parameter that is passed back to the merchant when sending a redirect or 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.
mandate	boolean	true|false	N	If set to true, a token with a mandate will be created along the process of the passed payment request.
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
recipient_map	array		N	Array of ‘payment recipients’ directives to pay out (part(s) of) the payment to other accounts (see Paying out to other accounts on how to build a recipient)
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		Y	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
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.) See the client-side tokenization documentation.
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.
payment_method.token_id	int		N	The token reference with an active mandate. If this is given, then there is no need to give the others except CVC if it is required.

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": 123,
    "extra": "extra",
    "reference": "Unqiue-111111",
    "description": "Shopping basket payment",
    "interactive": 1,
    "amount": 5000,
    "currency": "EUR",
    "return_url": "http:\/\/www.mysite.com\/return.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "customer": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "test@domain.com",
        "language": "en",
        "reference": "ref-1234",
        "ip":"80.90.62.101",
        "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": "2030",
        "cvc": "123"
    },
    "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

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":75,
  "reference":"Unqiue-111111",
  "amount":5000,
  "currency":"EUR",
  "status":"SUCCESS",
  "flow":"API",
  "processing_time":1423732957,
  "source":null,
  "contract":"Contract",
  "descriptor":"Contract",
  "extra":"extra",
  "description":"Shopping basket payment",
  "account_id":123,
  "merchant_id":123,
  "merchant_login":"****",
  "settlement_date":1423732957,
  "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": "4111-11xx-xxxx-1111",
    "validation_status": "VALID",
    "invalid_reason": null
  },
  "processor_reference":"ref1234"
}

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.
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.
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.
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,
   "creation_date":"1492681635",
   "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": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
        "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&page=3",
   "previous_page": "https:\/\/www.syspay.com\/api\/v2\/merchant\/tokens?status=ACTIVE&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": null
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
               "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":
     [
         { },
         { },
     ]

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"
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
               "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": null
      },
   "payment_method":
      {
         "class":"payment_method",
         "type":"CREDITCARD",
         "display":"4543-46xx-xxxx-0485",
         "validation_status": "VALID",
         "invalid_reason": null,
         "details":
            {
               "class":"payment_method_details",
               "fingerprint": "c98a804b-42e1-49ee-83a2-ea4a00c48b08",
               "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 lenght 300	N	The description of this refund.
extra	string	max lenght 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",
   "failure_category":null,
   "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":{ }
}

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

Paying out to other accounts

You have the possibility to automatically pay out a share or the entire amount of a payment (oneshot or rebill) to one or multiple accounts. For example you could send a given percentage of a sale to an account dedicated to taxes, a fixed amount to another one dedicated to a charity, or both.

In order to do so, your payment object (hosted or server-to-server) must contain a recipient_map array made of recipients with the following properties:

Name	Type	Mandatory	Description
account_id	int	Y	The SysPay account id of the recipient (the account could belong to another user)
user_id	int	Y	The SysPay user id of the owner of the recipient account (to prevent paying out a wrong account)
calc_type	fixed|percent	Y	The way the pay out is calculated
value	integer	Y	If calc_type is percent, this is the percentage*100 to substract off the full payment amount (100 == 1%), if calc_type is fixed, this will be a fixed amount.
currency	string	If fixed	This value must be the same as the currency of the payment
settlement_delay	int	N	A number of seconds the pay out settlement will be delayed for compared to the actual payment settlement

Example request

The following example will pay out a fixed 10 EUR amount to the account 4242, and 19% of the total payment amount to the account 3434 with a 7-day delay settlement.

{
  "payment": {
      "recipient_map": [
          {"account_id": 4242, "user_id": 5432, "calc_type": "fixed", "value": 1000, "currency": "EUR"},
          {"account_id": 3434, "user_id": 8765, "calc_type": "percent", "value": 1900, "settlement_delay": 604800}
      ]
  }
}