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 |
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:
BASE64(BINARY_SHA1(NONCE + TIMESTAMP + PASSPHRASE))
This header can only be used once and must be re-generated on each request.
<?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"
When a request is not valid or is not succesfully processed, the API returns the first error which occured.
Name | Type | Mandatory | Description |
---|---|---|---|
error | object | Y | An object containing a code and a message describing the error. see error codes |
{
"error": {
"code":10003,
"message":"Missing required parameters: reference"
}
}
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 |
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 |
payment_method.type | string | N | Type of payment (CREDITCARD) | |
payment_method.token_id | string | N | Token of payment |
{
"flow": "BUYER",
"mode": "ONLINE",
"redirect_url": "http:\/\/www.mysite.com\/redirect.php",
"ems_url": "http:\/\/www.mysite.com\/ems.php",
"payment": {
"reference": "99965349",
"amount": 5000,
"currency": "EUR",
"description": "shopping basket payment",
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
},
"customer": {
"email": "test@domain.com",
"reference": "ref-1234",
"language": "en"
}
}
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 |
{
"data": {
"redirect": "http:\/\/www.syspay.com\/payment-page",
"payment": {
"id": 46,
"reference": "99965349",
"amount": 5000,
"currency": "EUR",
"status": "OPEN",
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
"processing_time": null
}
}
}
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.
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 |
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 |
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) |
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 |
{
"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"
},
}
{
"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"
},
}
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 |
{
"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
}
}
}
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 |
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"
}
}
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:
This checksum is computed the following way:
HEX_SHA1(RESULT + PASSPHRASE)
<?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
}
}
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 |
This method allows the merchant to get the payment status and information.
URL syntax: | /api/{version}/merchant/payment/{payment.id} |
---|---|
Method: | GET |
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 |
{
"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"
}
}
}
}
This method allows the merchant to get a list of payments and their corresponding information.
URL syntax: | /api/{version}/merchant/payments/ |
---|---|
Method: | GET |
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 |
/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
Name | Type | Mandatory | Description |
---|---|---|---|
payments | array | Y | An array of payment objects (see Get payment information) |
{
"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"
}
]
}
}
This method allows the merchant to get a list of operations and their corresponding information.
URL syntax: | /api/{version}/merchant/operations/ |
---|---|
Method: | GET |
Name | Type | Details | Mandatory | Description |
---|---|---|---|---|
operation_id | int | UNIQUE | N | The syspay identifier. |
operation_status | array | N | The operation status (see status). | |
operation_type | array | N | The type of operations (see type) . | |
booking | string | UNIQUE | N | The merchant operation identifier. |
booking_time_start | int | unix timestamp | N | The creation start date from where you want to get the tokens in UTC. |
booking_time_end | int | unix timestamp | N | The creation end date until where you want to get the tokens in UTC. |
operation_time_start | int | unix timestamp | N | The creation start date from where you want to get the operations in UTC |
operation_time_end | int | unix timestamp | N | The creation end date until where you want to get the operations in UTC. |
processing_time_start | int | unix timestamp | N | The start processing date when the operation has been processed, null if the transaction is still not complete. |
processing_time_end | int | unix timestamp | N | The end procedding date when the operation has been processed, null if the transaction is still not complete. |
check_in_start | int | unix timestamp | N | The start check_in date of the booking. |
check_in_end | int | unix timestamp | N | The end check_in date of the booking. |
check_out_start | int | unix timestamp | N | The start check out date of the booking. |
check_out_end | int | unix timestamp | N | The end check out date of the booking. |
customer | string | N | Part of the name of the customer. | |
string | valid email address | N | Customers email address. | |
page | int | N | Number of page |
/api/{version}/merchant/operations/?booking_time_start=1363957978&booking_time_end=1364389978
/api/{version}/merchant/operations/?booking=999
/api/{version}/merchant/operations/?operation_status[]=SUCCESS
Name | Type | Mandatory | Description |
---|---|---|---|
operation.id | int | The SysPay operation reference. | |
operation.feature_name | string | Y | The API ‘s name . |
operation.processing_time | unix timestamp | N | When the payment has been processed, null if the transaction is still not complete.. |
operation.operation_time | unix timestamp | N | The timestamp when the operation is created. |
operation.booking_time | unix timestamp | N | The timestamp when the token is created. |
operation.checking_in | unix timestamp | N | The check_in date of the booking. |
operation.checking_out | unix timestamp | N | The check_out date of the booking. |
operation.booking | string | N | The partner reference of the booking. |
operation.customer | string | N | The customer first name combine with the last name. |
operation.payment_method | string | N | A payment method-specific string that can be used to identify the payment method used. |
operation.scheme | string | N | Credit card scheme. |
operation.type | string | N | Type of operation. |
operation.amount | string | N | The amount in cents. |
operation.currency | string | N | The currency. |
operation.source | string | N | The source of operation. |
operation.fee | int | N | The fee of the operation. |
operation.status | string | N | The status of the operation. |
operation.rolling_reserve | string | N | The amount of the rolling reserve. |
operation.reserve_release_time | string | N | The end time of the reserve. |
"data": [
{
"class": "Operation",
"id": 50,
"feature_name": "Processing",
"processing_time": "1633000748",
"operation_time": "1633000745",
"booking_time": "1633000744",
"checking_in": null,
"checking_out": null,
"booking_reference": "dasd",
"customer": "Ashley Connell",
"email": "",
"payment_method": "5420-71xx-xxxx-0010",
"scheme": null,
"type": "BillingAgreement",
"amount": null,
"currency": "EUR",
"source": "Processing",
"fee": null,
"status": "SUCCESS"
},
{
"class": "Operation",
"id": 51,
"feature_id": "Processing",
"processing_time": null,
"operation_time": "1633000745",
"booking_time": "1633000769",
"checking_in": null,
"checking_out": null,
"booking_reference": null,
"customer": "Ashley Connell",
"email": null,
"payment_method": "5420-71xx-xxxx-0010",
"scheme": "MASTERCARD",
"type": "Payment",
"amount": "5500",
"currency": "EUR",
"source": "Processing",
"fee": null,
"status": "OPEN"
},
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 |
/api/{version}/merchant/payment/123/confirm
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 |
"data": [
{
"class": "Operation",
"id": 50,
"feature_id": "25",
"processing_date": "1633000748",
"booking_date": "1633000744",
"checking_in": null,
"checking_out": null,
"booking_reference": "dasd",
"customer": "Ashley Connell",
"email": "",
"payment_method": "5420-71xx-xxxx-0010",
"scheme": null,
"type": "BillingAgreement",
"amount": null,
"currency": "EUR",
"source": "Processing",
"fee": null,
"status": "SUCCESS"
},
{
"class": "Operation",
"id": 51,
"feature_id": "25",
"processing_date": null,
"booking_date": "1633000769",
"checking_in": null,
"checking_out": null,
"booking_reference": null,
"customer": "Ashley Connell",
"email": null,
"payment_method": "5420-71xx-xxxx-0010",
"scheme": "MASTERCARD",
"type": "Payment",
"amount": "5500",
"currency": "EUR",
"source": "Processing",
"fee": null,
"status": "OPEN"
}
}
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 |
/api/{version}/merchant/payment/123/void
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 |
{
"data": {
"payment": {
"id": 123,
"reference": "99967779",
"amount": 5000,
"currency": "EUR",
"status": "VOIDED",
"processing_time": 1367488337,
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
}
}
}
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 |
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 |
{
"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"
}
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) |
{
"data": {
"refund": {
"id": 64,
"reference": "998249",
"amount": 5000,
"currency": "EUR",
"status": "SUCCESS",
"processing_time": 1367488337,
"description": "goods could not be delivered",
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
"payment": { }
}
}
}
This method allows the merchant to get the refund status and information.
URL syntax: | /api/{version}/merchant/refund/{refund.id} |
---|---|
Method: | GET |
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) |
{
"data": {
"refund": {
"id": 64,
"reference": "998249",
"amount": 5000,
"currency": "EUR",
"status": "SUCCESS",
"processing_time": 1367488337,
"description": "goods could not be delivered",
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
"payment": { }
}
}
}
This method allows the merchant to get a list of refunds and their corresponding information.
URL syntax: | /api/{version}/merchant/refunds/ |
---|---|
Method: | GET |
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 |
/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
Name | Type | Mandatory | Description |
---|---|---|---|
refunds | array | Y | An array of refund objects (see Get refund information) |
{
"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"
}
]
}
}
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 |
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 |
{
"data": {
"billing_agreement": {
"id": 64,
"status": "ACTIVE",
"currency": "EUR",
"extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
"start_date": "1364980261"
}
}
}
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 |
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 |
/api/{version}/merchant/billing-agreements/?start_date=1363957978&end_date=1364389978
/api/{version}/merchant/billing-agreements/?status=SUCCESS&website=16
Name | Type | Mandatory | Description |
---|---|---|---|
billing_agreements | array | Y | An array of billing agreement objects (see Get billing agreement information) |
{
"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"
}
]
}
}
This method allows the merchant to cancel a billing agreement.
URL syntax: | /api/{version}/merchant/billing-agreement/{billing_agreement.id}/cancel |
---|---|
Method: | POST |
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 |
{
"data": {
"billing_agreement": {
"id": 64,
"status": "ENDED",
"currency": "EUR",
"start_date": "1364980261",
"end_date": "1364990261"
}
}
}
This method allows the merchant to rebill the customer.
URL syntax: | /api/{version}/merchant/billing-agreement/{billing_agreement.id}/rebill |
---|---|
Method: | POST |
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) |
{
"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}
]
},
}
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 |
{
"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",
}
}
}
}
This method allows the merchant to get the details about a chargeback.
URL syntax: | /api/{version}/merchant/chargeback/{chargeback.id} |
---|---|
Method: | GET |
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) |
{
"data": {
"chargeback": {
"id": 42,
"amount": 5000,
"currency": "EUR",
"status": "SUCCESS",
"level": "HARD",
"processing_time": 1367488337,
"reason_code": "VI57",
"payment": { }
}
}
}
This method allows the merchant to get a list of chargebacks.
URL syntax: | /api/{version}/merchant/chargebacks/ |
---|---|
Method: | GET |
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 | |
int | N | The email the chargeback was received for |
/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
Name | Type | Mandatory | Description |
---|---|---|---|
chargebacks | array | Y | An array of chargeback objects (see Get chargeback information) |
{
"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": { }
}
]
}
}
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 |
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 |
This method returns a list of all banks handled by iDeal.
URL syntax: | /api/{version}/merchant/ideal/banks |
---|---|
Method: | GET |
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. |
{
"updated":1370858310,
"banks":[
{
"id":1,
"name":"Issuer Simulation V3 - ING",
"country":"Nederland"
},
{
"id":2,
"name":"Issuer Simulation V3 - RABO",
"country":"Nederland"
}
]
}
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 |
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}
]
}
}