Table Of Contents

1.2. API Methods

The SysPay REST API is a simple programmatic interface that allows you, 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 “v1”.

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. You can find a full list of all possible errors in Appendix XXXX. If there was no error, the data section will give you the information you requested.

Status code Description
200 Success
201 Created
400 Bad request
403 Forbidden (wrong authentication, invalid source ip or forbidden resource)
404 Not found
500 System error

1.2.1. 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");
// X-Wsse: AuthToken MerchantAPILogin="mylogin", PasswordDigest="pIHzLACUUUZjsDkugJZnWESHYFQ=", Nonce="Uc7+N/ygEmQAfOOvrYHOow==", Created="1369414302"

1.2.2. Errors

When a request is not valid or is not succesfully processed, the API returns the first error which occured.

Response parameters

Name Type Mandatory Description
error object Y An object containing a code and a message describing the error. see error codes

Example response

{
  "error": {
    "code":10003,
    "message":"Missing required parameters: reference"
  }
}

1.2.3. Hosted payment request

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

One the payment will be complete, he will be sent back to the default or payment-specific redirect_url. In order to interpret the parameters appended to that URL, please refer to Post-payment redirection.

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

Input parameters

Name Type Details Mandatory Description
flow string BUYER|SELLER Y BUYER: The buyer is in front of the screen (online eMerchant payment), SELLER: The sale is made by the merchant himself (or an agent) e.g. a face-to-face payment or a payment taken over the phone.
mode string BOTH|ONLINE|TERMINAL N The ONLINE mode means that the redirect will take the user to our hosted payment page. This is available for both the BUYER and the SELLER flow. The TERMINAL mode will directly trigger a Chip&PIN payment (SELLER flow only). BOTH means that the user can choose between paying online or with Chip&Pin (on BUYER mode the order will be pending and will be finalized on collection/delivery). Mandatory if flow is set to SELLER
website int   N The Syspay website reference for which the customer makes the payment (The list of available websites can be checked from the merchant backend)
agent int   N The agent in charge of the sale. SELLER flow only.
redirect_url string   N This URL can overwrite the default Redirect URL
ems_url string   N This URL can overwrite the default EMS URL
billing_agreement boolean true|false N Create a billing agreement so that you can rebill the customer at a later point (defaults to 0). If given, only rebillable payment methods will be displayed.
allowed_retries integer 0 to 5 N This will let the user attempt up to allowed_retries times if the payment fails. It will create a new payment operation each time, with the same merchant reference
payment.reference string UNIQUE, [ -~]+ (ascii printable characters) Y Merchant payment identifier, must be unique for each payment
payment.amount int   Y The amount we need to bill in cents (500 XXX = 5.00 XXX)
payment.currency string [A-Z]{3} Y The currency (ISO-4217)
payment.description string max length 300 N The product description
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.preauth boolean true|false N If set to 1, the payment will not be fully processed by authorized only. It will need to be confirmed or voided later. (defaults to 0). If true, only payment methods supporting preauthorizations will be displayed.
payment.extra string max length 300 N Extra parameter that is passed back to the merchant when sending redirect or event message
notify array   N Array of notification methods for the BUYER flow. Valid values are ‘email’ and ‘mobile’
customer.email string valid email address N Customers email address. Mandatory if flow is set to BUYER with notify set to ‘email’
customer.mobile string valid phone number N Customers mobile phone number. The user must specifify the country profix (for instance: +356 99124578 (MALTA) OR +33 661234567 (FRANCE) OR +44 2012341234 (UK)). Mandatory when notify has an ‘mobile’ element.
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
threatmetrix_attributes object attr_1 - attr_10 N Additional attributes used by threatmetrix for better fraud detection.

Example request (eMerchant hosted payment page)

{
    "flow": "BUYER",
    "mode": "ONLINE",
    "redirect_url": "http:\/\/www.mysite.com\/redirect.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "threatmetrix_attributes": {
        "attr_1": "objectA",
        "attr_2": "objectPriceA",
        "attr_10": "flowA"
    },
    "payment": {
        "reference": "99965349",
        "amount": 5000,
        "currency": "EUR",
        "description": "shopping basket payment",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
    },
    "customer": {
        "email": "test@domain.com",
        "reference": "ref-1234",
        "language": "en"
    }
}

Response parameters

Name Type Mandatory Description
redirect string Y The URL you should redirect the customer to in order to complete the payment. You could also include this URL in an email or an invoice to propose the customer to pay later (see offline payments)
payment.id int Y The SysPay payment reference
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.status string Y The payment status (reference)
payment.extra string N Extra parameter that was passed

Example response

{
    "data": {
        "redirect": "http:\/\/www.syspay.com\/payment-page",
        "payment": {
            "id": 46,
            "reference": "99965349",
            "amount": 5000,
            "currency": "EUR",
            "status": "OPEN",
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "processing_time": null
        }
    }
}

Processing offline payments

The link given back by the API call can also be used to get a customer to pay asynchronously. That is, instead of initiating a payment following a user action on your checkout page, you can call our API from e.g. your own backend in order to retrieve a hosted payment page link, which can then be sent to your customer by email or by including it in a PDF invoice.

Eventhough the hosted payment page does not follow a checkout on your site, it is still advised to provide a redirect_url that will send the customer to some confirmation page of yours. (Passing null will hide the ‘Return To The Shop’ button on our confirmation page and make it a dead-end).

In any case, it is advised to rely on the EMS notifications in order to get the final payment status.

1.2.4. Server-to-server payment request

This method allows you to process a server-to-server payment, i.e. the payment form will reside on your site. Depending on the payment method, a redirection could be necessary (e.g. a 3DS creditcard payment request). In this case, the customer will be redirected back to your default or payment-specific redirect_url. In order to interpret the parameters appended to that URL, please refer to Post-payment redirection.

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

Input parameters

Name Type Details Mandatory Description
flow string API Y For server-to-server payments it should be API
method string CREDITCARD | IDEAL | BCMC Y The payment method used for this payment
billing_agreement boolean true|false N Create a billing agreement so that you can rebill the customer at a later point (defaults to 0)
website int   N The Syspay website reference for which the customer makes the payment (list of websites manageble in merchant interface)
redirect_url string   N This URL can overwrite the default Redirect URL
ems_url string   N This URL can overwrite the default EMS URL
payment.reference string UNIQUE, [ -~]+ (ascii printable characters) Y Merchant payment identifier, must be unique for each payment
payment.preauth boolean true|false N If set to 1, the payment will not be fully processed by authorized only. It will need to be confirmed or voided later. (defaults to 0)
payment.amount int   Y The amount we need to bill in cents (500 XXX = 5.00 XXX)
payment.currency string [A-Z]{3} Y The currency (ISO-4217)
payment.description string max length 300 N The product description
payment.extra string max length 300 N Extra parameter that is passed back to the merchant when sending redirect or event message
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)
customer.email string valid email address Y Customers email address.
customer.ip string valid IPv4 ip address Y Ip address of the customer
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
threatmetrix_session_id string <feature_id>-<session_id> OR a<account_id>-<session_id> OR u<user_id>-.<session_id>, max length 128 N* A security parameter to check that the transaction is legitimate. {*Required if option is set to true in your API Configuration. Please check with account manager to verify if this parameter is set.}
threatmetrix_attributes object attr_1 - attr_10 N Additional attributes used by threatmetrix for better fraud detection.

Method-specific parameters

Method: CREDITCARD
Name Type Details Mandatory Description
creditcard.cardholder string max length 100 Y Cardholder name
creditcard.number string [0-9]{12,19} Y Valid credit card number, only digits
creditcard.cvc int [0-9]{3,4} Y Credit card verification code
creditcard.exp_month string [0-9]{2} Y Credit card expire month (ex: 05)
creditcard.exp_year string [0-9]{4} Y Credit card expire year (ex: 2015)
Method: IDEAL
Name Type Details Mandatory Description
ideal.bank_id int   Y The iDeal bank id (see Get a list of iDeal banks)

If you use the client-side tokenization to collect card data, there will only be a single token property to pass:

Name Type Details Mandatory Description
creditcard.token string   Y The token posted

Example request (standard form)

{
    "flow": "API",
    "method": "CREDITCARD",
    "billing_agreement": 0,
    "website": 16,
    "redirect_url": "http:\/\/www.mysite.com\/redirect.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "payment": {
        "reference": "99965359",
        "amount": 5000,
        "currency": "EUR",
        "description": "shopping basket payment",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en",
        "reference": "ref-1234",
        "ip": "82.192.64.29"
    },
    "creditcard": {
        "cardholder": "John Doe",
        "number": "4556253971599407",
        "cvc": 123,
        "exp_month": "05",
        "exp_year": "2015"
    },
    "threatmetrix_session_id": "9-sfss31f3sfsfs5f6"
    "threatmetrix_attributes": {
        "attr_1": "objectA",
        "attr_2": "objectPriceA",
        "attr_10": "flowA"
    },
}

Example request (with client-side tokenization)

{
    "flow": "API",
    "method": "CREDITCARD",
    "billing_agreement": 0,
    "website": 16,
    "redirect_url": "http:\/\/www.mysite.com\/redirect.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "payment": {
        "reference": "99965359",
        "action": "DIRECT",
        "amount": 5000,
        "currency": "EUR",
        "description": "shopping basket payment",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en",
        "reference": "ref-1234",
        "ip": "82.192.64.29"
    },
    "creditcard": {
        "token": "4f7964aef61b02dd00d3617a3fa0652dff49d99d94955f8907e4e4210e366d78:mia5z816e8dc8dcizpfcdrdgdaayjylf"
    },
    "threatmetrix_session_id": "9-sfss31f3sfsfs5f6"
}

Response parameters

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

Example response

{
    "data": {
        "payment": {
            "id": 47,
            "reference": "99965359",
            "payment_type": "ONESHOT",
            "amount": 5000,
            "currency": "EUR",
            "status": "SUCCESS",
            "processing_time": 1367488337,
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "website": 42,
            "website_url": "https:\/\/merchant.com",
            "contract": "SysPay",
            "descriptor": "@SYSPAY*merchant.com",
            "account_id": 4700,
            "merchant_id": 4387,
            "merchant_login": "4387001",
            "settlement_date": 1367518337
        }
    }
}

1.2.5. 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.

{
    "flow": "BUYER",
    "mode": "ONLINE",
    "redirect_url": "http:\/\/www.mysite.com\/redirect.php",
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "payment": {
        "reference": "99965349",
        "amount": 10000,
        "currency": "EUR",
        "description": "shopping basket payment",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
        "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}
        ]
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en"
    }
}

1.2.6. Post-payment redirection

Once a payment made using the hosted payment flow or the server-to-server using a payment method that required a direction (e.g. a 3DS credit card transaction) is complete, the user will be redirected back to your default redirect URL or the one that you specified during the payment request call.

In order for you to validate synchronously the result of the transaction, three GET parameters will be added to that URL in order:

  • result: a base64-encoded JSON object, similar to what you would receive back from the API call
  • merchant: your merchant id
  • checksum: A checksum computed with the passphrase linked to that merchant id, in order to validate that the result have not been tampered with.

This checksum is computed the following way:

HEX_SHA1(RESULT + PASSPHRASE)

Example code (PHP)

<?php

$keys = array(
    'login1' => 'passphrase1',
    'login2' => 'passphrase2'
);

$merchant = $_GET['merchant'];
$result   = $_GET['result'];
$checksum = $_GET['checksum'];

if (!isset($keys[$merchant])) {
    die("Unknown merchant login");
}

$shouldBe = sha1($result . $keys[$merchant]);

if ($checksum !== $shouldBe) {
    // URL is not genuine
}

// $result is a base64-encoded json string
$result = json_decode(base64_decode($result));

Once base64-decoded, the json will look like the following:

{
    "payment": {
        "id": 204,
        "reference": "51eff066688ab",
        "amount": 2900,
        "currency": "EUR",
        "status": "SUCCESS",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
        "description": "some description",
        "processing_time": 1374679168,
        "website": 6
    }
}

Fields description

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

1.2.7. 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

Response parameters

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

Example response

{
    "data": {
        "payment": {
            "id": 53,
            "reference": "99967779",
            "amount": 5000,
            "currency": "EUR",
            "status": "SUCCESS",
            "processing_time": 1367488337,
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "billing_agreement": {
                "id": 44,
                "status": "ACTIVE",
                "currency": "EUR",
                "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
                "start_date": "1364980261"
            }
        }
    }
}

1.2.8. 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

Input 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)
start_date int unix timestamp N The start date from where you want to get the payments
end_date int unix timestamp N The end date until where you want to get the payments
reference string UNIQUE, [ -~]+ (ascii printable characters) N The merchant payment identifier
flow string BUYER|SELLER|API N The flow of the payments you are searching for
website int   N The Syspay website reference
status string   N The payment status

Example requests

/api/{version}/merchant/payments/?currency=EUR&start_date=1363957978&end_date=1364389978
/api/{version}/merchant/payments/?reference=999
/api/{version}/merchant/payments/?flow=HOSTED&amount=5000&status=SUCCESS&website=16

Response parameters

Name Type Mandatory Description
payments array Y An array of payment objects (see Get payment information)

Example response

{
    "data": {
        "payments": [
            {
                "id": 53,
                "reference": "1364304359",
                "amount": 10000,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367488337,
                "extra": null
            },
            {
                "id": 58,
                "reference": "99975213",
                "amount": 5000,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367488337,
                "extra": "dd52",
                "billing_agreement": {
                   "id": 22,
                   "status": "ACTIVE",
                   "currency": "EUR",
                   "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
                   "start_date": "1364980261"
                }
            },
            {
                "id": 61,
                "reference": "9995489978",
                "amount": 5000,
                "currency": "EUR",
                "status": "OPEN",
                "processing_time": null,
                "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
            }
        ]
    }
}

1.2.9. Confirm a pre-authorization

This method allows the merchant to confirm a pre authorized payment and capture the money from the customer.

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

Example request

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

Response parameters

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

Example response

{
    "data": {
        "payment": {
            "id": 123,
            "reference": "99967779",
            "amount": 5000,
            "currency": "EUR",
            "status": "SUCCESS",
            "processing_time": 1367488337,
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
        }
    }
}

1.2.10. Void a pre-authorization

This method allows the merchant to void a pre authorized payment so the customer does not pay anything.

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

Example requests

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

Response parameters

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

Example response

{
    "data": {
        "payment": {
            "id": 123,
            "reference": "99967779",
            "amount": 5000,
            "currency": "EUR",
            "status": "VOIDED",
            "processing_time": 1367488337,
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
        }
    }
}

1.2.11. Make a refund

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 payment.

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, [ -~]+ (ascii printable characters) Y Merchant refund identifier, must be unique for each refund
amount int   Y The amount you want to refund in cents (500 XXX = 5.00 XXX)
currency string [A-Z]{3} Y The refund currency, should be the same tike the currency of the original payment (ISO-4217)
description string max length 300 N The description of this refund
extra string max length 300 N Extra parameter that is passed back to the merchant when sending the event message
ems_url string   N This URL can overwrite the default EMS URL

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
refund.id int Y The SysPay refund reference
refund.reference string Y Merchant refund identifier
refund.amount int Y The amount in cents
refund.currency string Y The currency (ISO-4217)
refund.status string Y The refund status
refund.processing_time unix timestamp Y When the refund has been processed, null if the transaction is still not complete
refund.description string N The refund description
refund.extra string N Extra parameter that was passed
refund.payment object Y The original payment object (see Get payment information)

Example response

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

1.2.12. 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

Response parameters

Name Type Mandatory Description
refund.id int Y The SysPay refund reference
refund.reference string Y Merchant refund identifier
refund.amount int Y The amount in cents
refund.currency string Y The currency (ISO-4217)
refund.status string Y The refund status
refund.processing_time unix timestamp Y When the refund has been processed, null if the transaction is still not complete
refund.description string N The refund description
refund.extra string N Extra parameter that was passed
refund.payment object Y The original payment object (see Get payment information)

Example response

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

1.2.13. Get a list of refunds

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

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

Input parameters

Name Type Details Mandatory Description
amount int   N The amount of the refund
currency string [A-Z]{3} N The currency of the refund (ISO-4217)
start_date int unix timestamp N The start date from where you want to get the refunds
end_date int unix timestamp N The end date until where you want to get the refunds
reference string UNIQUE, [ -~]+ (ascii printable characters) N The merchant refund identifier
website int   N The Syspay website reference
status string   N The refund status

Example requests

/api/{version}/merchant/refunds/?currency=EUR&start_date=1363957978&end_date=1364389978
/api/{version}/merchant/refunds/?reference=999&amount=5000
/api/{version}/merchant/refunds/?status=SUCCESS&website=16

Response parameters

Name Type Mandatory Description
refunds array Y An array of refund objects (see Get refund information)

Example response

{
    "data": {
        "refunds": [
            {
                "id": 64,
                "reference": "998249",
                "amount": 5000,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367488337,
                "description": "goods could not be delivered",
                "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
            },
            {
                "id": 65,
                "reference": "98123",
                "amount": 5000,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367488337,
                "description": "out of stock",
                "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
            }
        ]
    }
}

1.2.14. Get billing agreement information

This method allows the merchant to get the billing agreement status and information.

URL syntax:/api/{version}/merchant/billing-agreement/{billing_agreement.id}
Method:GET

Response parameters

Name Type Mandatory Description
billing_agreement.id int Y The SysPay billing agreement reference
billing_agreement.status string Y The billing agreement status
billing_agreement.currency string N The billing agreement currency (ISO-4217)
billing_agreement.extra string N Extra parameter that was passed when the first payment took place
billing_agreement.start_date unix timestamp N When the billing agreement was created
billing_agreement.end_date unix timestamp N When the billing agreement was ended
billing_agreement.end_reason string N If the billing agreement is ended, this will give you extra information about the reason
billing_agreement.expiration_date unix timestamp N When the billing agreement will expire

Example response

{
    "data": {
        "billing_agreement": {
            "id": 64,
            "status": "ACTIVE",
            "currency": "EUR",
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "start_date": "1364980261"
        }
    }
}

1.2.15. Get a list of billing agreements

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

URL syntax:/api/{version}/merchant/billing-agreements/
Method:GET

Input parameters

Name Type Details Mandatory Description
start_date int unix timestamp N The start date from where you want to get the billing agreements
end_date int unix timestamp N The end date until where you want to get the billing agreements
website int   N The Syspay website reference
status string   N The billing agreement status

Example requests

/api/{version}/merchant/billing-agreements/?start_date=1363957978&end_date=1364389978
/api/{version}/merchant/billing-agreements/?status=SUCCESS&website=16

Response parameters

Name Type Mandatory Description
billing_agreements array Y An array of billing agreement objects (see Get billing agreement information)

Example response

{
    "data": {
        "billing_agreements": [
            {
                "id": 4,
                "status": "ACTIVE",
                "currency": "EUR",
                "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
                "start_date": "1364980261"
            },
            {
                "id": 5,
                "status": "ENDED",
                "currency": "EUR",
                "start_date": "1364980261",
                "end_date": "1364990261"
            },
            {
                "id": 6,
                "status": "PENDING",
                "currency": "EUR",
                "start_date": "1364980261"
            }
        ]
    }
}

1.2.16. Cancel a billing agreement

This method allows the merchant to cancel a billing agreement.

URL syntax:/api/{version}/merchant/billing-agreement/{billing_agreement.id}/cancel
Method:POST

Response parameters

Name Type Mandatory Description
billing_agreement.id int Y The SysPay billing agreement reference
billing_agreement.status string Y The billing agreement status
billing_agreement.currency string N The billing agreement currency (ISO-4217)
billing_agreement.extra string N Extra parameter that was passed when the first payment took place
billing_agreement.start_date unix timestamp N When the billing agreement was created
billing_agreement.end_date unix timestamp N When the billing agreement was ended
billing_agreement.end_reason string Y The end reason of the billing agreement, in this case, UNSUBSCRIBED_MERCHANT
billing_agreement.expiration_date unix timestamp N When the billing agreement will expire

Example response

{
    "data": {
        "billing_agreement": {
            "id": 64,
            "status": "ENDED",
            "currency": "EUR",
            "start_date": "1364980261",
            "end_date": "1364990261"
        }
    }
}

1.2.17. Issue a rebill on a billing agreement

This method allows the merchant to rebill the customer.

URL syntax:/api/{version}/merchant/billing-agreement/{billing_agreement.id}/rebill
Method:POST

Input parameters

Name Type Details Mandatory Description
website int   N The Syspay website reference for which the customer makes the payment (list of websites manageble in merchant interface)
ems_url string   N This URL can overwrite the default EMS URL
payment.reference string UNIQUE, [ -~]+ (ascii printable characters) Y Merchant payment identifier, must be unique for each payment
payment.amount int   Y The amount we need to bill in cents (500 XXX = 5.00 XXX)
payment.currency string [A-Z]{3} Y The currency (ISO-4217)
payment.description string max length 300 N The product description where the customer is paying for
payment.extra string max length 300 N Extra parameter that is passed back to the merchant when sending redirect or event message
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)

Example request

{
    "website": 16,
    "ems_url": "http:\/\/www.mysite.com\/ems.php",
    "payment": {
        "reference": "99965359",
        "amount": 5000,
        "currency": "EUR",
        "description": "monthly magazine subscription",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
        "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}
        ]
    },
}

Response parameters

Name Type Mandatory Description
payment.id int Y The SysPay payment reference
payment.payment_type string Y The payment type (reference)
payment.reference string Y Merchant payment identifier
payment.amount int Y The amount in cents
payment.currency string Y The currency (ISO-4217)
payment.status string Y The payment status (reference)
payment.flow string Y The flow used to process the payment
payment.preauth_expiration_date unix timestamp N 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.
payment.capture_date unix timestamp Y The date after which the preauth may be automatically captured.
payment.processing_time unix timestamp Y When the payment has been processed, null if the transaction is still not complete
payment.website int N The id of the website the payment has been made for
payment.website_id string N The URL of the website the payment has been made for
payment.contract string N The contract name used to process the payment (relevant only when using the super gateway feature)
payment.descriptor string N For creditcard payments, this is the descriptor that will be shown on the card statement
payment.extra string N Extra parameter that was passed on payment request
payment.description string N The merchant payment description
payment.account_id int Y The SysPay account id that the API access is linked to
payment.merchant_id int Y The SysPay API access id
payment.merchant_login string Y The SysPay API login used to process the payment
payment.settlement_date unix timestamp N A timestamp indicating when this payment will be settled
payment.failure_category string N When a payment failed, this field will include extra information about the failure (reference)
payment.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
payment.payment_method object Y A payment method object representing the payment method used to process this payment
payment.payment_method.type string Y The payment method type
payment.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.billing_agreement object N If the payment is part of a billing agreement, the relevant information will be included
payment.billing_agreement.id int N The SysPay billing agreement reference
payment.billing_agreement.status string N The billing agreement status
payment.billing_agreement.currency string N The billing agreement currency (ISO-4217)
payment.billing_agreement.extra string N Extra parameter that was passed when the first payment took place
payment.billing_agreement.start_date unix timestamp N When the billing agreement was created
payment.billing_agreement.expiration_date unix timestamp N When the billing agreement will expire
payment.billing_agreement.customer object Y Information about the user linked to the billing agreement
payment.billing_agreement.customer.id int Y The SysPay ID of the customer
payment.billing_agreement.customer.firstname string N The first name of the customer (when available)
payment.billing_agreement.customer.laststname string N The last name of the customer (when available)
payment.billing_agreement.customer.email string N The email of the customer (when available)
payment.billing_agreement.payment_method object Y A payment method object representing the payment method used to process this payment
payment.billing_agreement.payment_method.type string Y The payment method type
payment.billing_agreement.payment_method.display string Y Some payment method-specific string that can be used to identify the payment method used. For creditcard payment this will be the last 4 digits of the card
payment.subscription object N If the payment is part of a subscription, the subscription information will be included
payment.subscription.id int Y The SysPay subscription id
payment.subscription.plan_id int Y The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
payment.subscription.plan_type string Y The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
payment.subscription.created unix timestamp Y The subscription’s creation date
payment.subscription.ems_url string N The URL that is used to notify about events related to this subscription.
payment.subscription.reference string N Your own reference for this subscription
payment.subscription.status string Y The subscription status (PENDING) (see Subscription statuses)
payment.subscription.phase string Y The phase the subscription is in (NEW) (see Subscription phases)
payment.subscription.customer object Y The customer information
payment.subscription.customer.id int Y The Syspay reference for this customer
payment.subscription.customer.firstname string N The customer’s first name
payment.subscription.customer.lastname string N The customer’s last name
payment.subscription.customer.email string N The customer’s email address
payment.subscription.extra string N The extra parameter received upon request
payment.subscription.start_date unix timestamp N The subscription start date, if it has already been started
payment.subscription.end_date unix timestamp N The subscription end date, if the subscription is over
payment.subscription.end_reason int N The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
payment.subscription.next_event object N Information about the next scheduled event for this subscription
payment.subscription.next_event.event_type string Y The next event type (subscription events)
payment.subscription.next_event.scheduled_date unix timestamp Y The event’s scheduled date/time

Example response

{
    "data": {
        "payment": {
            "id": 47,
            "reference": "99965359",
            "amount": 5000,
            "currency": "EUR",
            "status": "SUCCESS",
            "processing_time": 1367488337,
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "billing_agreement": {
                "id": 24,
                "status": "ACTIVE",
                "currency": "EUR",
                "extra": "6900",
                "start_date": "1364980261",
            }
        }
    }
}

1.2.18. Get chargeback information

This method allows the merchant to get the details about a chargeback.

URL syntax:/api/{version}/merchant/chargeback/{chargeback.id}
Method:GET

Response parameters

Name Type Mandatory Description
chargeback array Y A chargeback object
chargeback.id int Y The SysPay chargeback reference
chargeback.amount int Y The amount in cents
chargeback.currency string Y The currency (ISO-4217)
chargeback.status string Y The chargeback status. This field is there for consistency but will always be SUCCESS
chargeback.level HARD|SOFT Y The chargeback level. HARD chargebacks will automatically cancel any mandate or subscription linked to the related payment method, while SOFT ones won’t
chargeback.processing_time unix timestamp Y When the chargeback has been processed by SysPay
chargeback.bank_time unix timestamp N When the chargeback has been approved by the bank
chargeback.reason_code string Y The chargeback reason code (the value depends on the card scheme) - UNKNOWN if the reason was not given by the bank
chargeback.payment object Y The original payment object (see Get payment information)

Example response

{
    "data": {
        "chargeback": {
            "id": 42,
            "amount": 5000,
            "currency": "EUR",
            "status": "SUCCESS",
            "level": "HARD",
            "processing_time": 1367488337,
            "reason_code": "VI57",
            "payment": { }
        }
    }
}

1.2.19. Get a list of chargebacks

This method allows the merchant to get a list of chargebacks.

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

Input parameters

Name Type Details Mandatory Description
amount int   N The amount of the chargeback
currency string [A-Z]{3} N The currency of the refund (ISO-4217)
start_date int unix timestamp N The start date from where you want to get the chargebacks
end_date int unix timestamp N The end date until where you want to get the chargebacks
website int   N The Syspay website reference
email int   N The email the chargeback was received for

Example requests

/api/{version}/merchant/chargebacks/?currency=EUR&start_date=1363957978&end_date=1364389978
/api/{version}/merchant/chargebacks/?email=foo%40bar.com
/api/{version}/merchant/chargebacks/?website=16

Response parameters

Name Type Mandatory Description
chargebacks array Y An array of chargeback objects (see Get chargeback information)

Example response

{
    "data": {
        "chargebacks": [
            {
                "id": 42,
                "amount": 5000,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367488337,
                "reason_code": "VI57",
                "payment": { }
            },
            {
                "id": 47,
                "amount": 4050,
                "currency": "EUR",
                "status": "SUCCESS",
                "processing_time": 1367489453,
                "reason_code": "VI72",
                "payment": { }
            }
        ]
    }
}

1.2.20. Get system ip addresses

This method returns a list of all SysPay IP-addresses that can make EMS calls. You should use this webservices to secure your EMS handler script. We advise a merchant to fetch the list once per day, and store the IP-addresses locally.

URL syntax:/api/{version}/merchant/system-ip
Method:GET

Response parameters

Name Type Mandatory Description
ip_addresses array Y A list of IPv4 ip addresses

Example response

{
    "data": {
        "ip_addresses": [
            "82.192.64.30",
            "82.192.64.31",
            "82.192.64.32"
        ]
    }
}

1.2.21. Get a list of Astropay banks

This method returns a list of all banks handled by Astropay in a specified country. It is used for Boleto Bancario, Bank Transfer and DebitCard payment methods.

URL syntax:/api/{version}/merchant/astropay/banks/{country_code}
Method:GET

Input parameters

Name Type Mandatory Description
country_code string Y ISO country code

Example request

/api/{version}/merchant/astropay/banks/BR

Response parameters

Name Type Mandatory Description
banks array Y A list of banks in the specified country

Example response

{
    "data": {
        "banks": [
            {
              "code": "TE",
              "name": "GNB TEST BANK"
            },
            {
              "code": "BL",
              "name": "BOLETO BANCARIO"
            }
        ]
    }
}

1.2.22. Get a list of iDeal banks

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

URL syntax:/api/{version}/merchant/ideal/banks
Method:GET

Response parameters

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

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

1.2.23. 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}
      ]
  }
}