The SysPay Event Messaging System will call the URL you provided us anytime one of the following objects undergoes a change:
By default the POSTed data will be encoded in application/json.
The content of the EMS will be the fields within the classes
An event is considered successful if we receive an HTTP response with status 200.
If another response is received, we will re-attempt to send it up to 10 times. If no successful response has been received after these attempts, we will give up.
The retry schedule is the following: (based on the initial attempt)
A callback will be provided with the following HTTP headers that will let you validate that the call is genuine:
The checksum is computed the following way:
HEX_SHA1(REQUEST_BODY + PASSPHRASE)
<?php
$keys = array(
'login1' => 'passphrase1',
'login2' => 'passphrase2'
);
$merchant = $_SERVER['HTTP_X_MERCHANT'];
$checksum = $_SERVER['HTTP_X_CHECKSUM'];
$eventId = $_SERVER['HTTP_X_EVENT_ID'];
$eventDate = $_SERVER['HTTP_X_EVENT_DATE'];
$body = file_get_contents('php://input');
if (!isset($keys[$merchant])) {
die("Unknown merchant login");
}
$shouldBe = sha1($body . $keys[$merchant]);
if ($checksum === $shouldBe) {
// Request is validated
}
Whenever a token will be processed, you will be notified with the full token object. The data provided is structured the same way as what you would receive from the token request API call:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| class | string | Y | The type of object which is being returned. In this case it will be token. |
| id | int | Y | The SysPay reference of the returned token. |
| status | string | Y | The token status. see status. |
| action_url | string | N | The url where the customer should be redirected to in order to access the hosted page and input his/her the card details. |
| extra | string | N | The extra parameter which was passed to the request. |
| booking_details | object | Y | The booking details. see booking_details. |
| creation_date | unix timestamp | Y | The creation date of the token. |
| expiration_date | unix timestamp | Y | The expiration date of the token. The token will not be usable after this date. |
| accept_until | unix timestamp | N | A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow. |
| customer | object | Y | The customer details. see customer. |
| payment_method | object | Y | The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data. |
| moto_instance_id | int | N | The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface |
| mandate | object | N | The mandate details. Will only be returned if a mandate was automatically created. see mandate. |
| payment | object | N | The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment. |
| risk | object | N | The risk of the token. see risk. |
{
"class":"token",
"id":7,
"status":"ACTIVE",
"action_url":null,
"booking_id": "test-ref",
"check_in_date": "2015-08-22",
"check_out_date": "2015-08-24",
"expiration_date":1421426671,
"customer":{
"class":"customer",
"email":"test@domain.com",
"language":"en"
},
"payment_method":{
"class":"payment_method",
"type":"CREDITCARD",
"display":"4111-11xx-xxxx-1111",
"validation_status": "VALID",
"invalid_reason": null,
"details":{
"class":"payment_method_details",
"holder":"Card Holder Name",
"scheme": "VISA",
"exp_month":"01",
"exp_year":"2015"
}
}
}
Whenever a payment will be processed, you will be notified with the full payment object. The data provided is structured the same way as what you would receive from the payment request API call:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| class | string | Y | The type of object which is being returned. In this case it will be payment. |
| id | int | Y | The SysPay reference of the returned payment. |
| reference | string | Y | The merchant payment identifier which was passed in the request. |
| amount | int | Y | The amount in cents. |
| currency | string | Y | The currency (ISO-4217). |
| status | string | Y | The payment status see status. |
| preauth_expiration_date | unix timestamp | Y | The preauth expiration date specifies until when a a preauth can be captured or voided. The transaction will be voided automatically once the preauth expires. |
| capture_date | unix timestamp | Y | The date after which the preauth may be automatically captured. |
| action_url | string | N | The url where the customer should be redirected to in order to provide further details required to complete the payment. |
| flow | string | Y | The flow used to process the payment. |
| processing_time | unix timestamp | Y | When the payment has been processed, null if the transaction is still not complete. |
| source | int | N | The id of the website the payment has been made for. |
| contract | string | N | The name of the payment processor. |
| descriptor | string | N | The payment description which will be shown on the card payment bank statement. |
| extra | string | N | The extra parameter which was sent on in the request call. |
| description | string | N | The merchant payment description. |
| account_id | int | Y | The SysPay account reference that the API access is linked to. |
| merchant_id | int | Y | The SysPay API access merchant reference. |
| merchant_login | string | Y | The SysPay API merchant login which proccessed the payment. |
| settlement_date | unix timestamp | N | A timestamp indicating when this payment will be settled. |
| failure_category | string | N | When a payment fails, this parameter will include extra information about the error (reference). |
| chip_and_pin_status | string | N | This field will be present on Chip&Pin transactions. When the payment has been made using the bluetooth device, the actual payment status will be kept OPEN until the transaction is really captured (which can take 1 business day). In order to let your web shop or native application know about the transaction results synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only. |
| token | object | N | The token details. see token. |
| customer | object | Y | The customer details. see customer. |
| payment_method | object | Y | The payment method details. see payment_method. |
| processor_reference | string | N | The reference of the transaction for the processor, in case of supergateway processing. |
{
"class": "payment",
"id": 123,
"reference": "Unique-11111",
"amount": 5000,
"currency": "EUR",
"status": "SUCCESS",
"action_url": null,
"flow": "API",
"processing_time": 1423737892,
"source": null,
"contract": "Syspay",
"descriptor": "@SYSPAY*mysite.com",
"extra": "extra",
"description": "Some description",
"account_id": 42,
"merchant_id": 65,
"merchant_login": "42001",
"settlement_date": 1423737892,
"failure_category": null,
"chip_and_pin_status": null,
"token": {
"class": "token",
"id": "44",
"status": "ACTIVE",
"action_url": null,
"booking_id":"test-ref",
"check_in_date":"2015-08-22",
"check_out_date":"2015-08-24",
"expiration_date": 1523737892,
"description": "description",
"customer": {
"class": "customer",
"email": "test@domain.com",
"language": "en"
},
"payment_method": {
"class": "payment_method",
"type": "CREDITCARD",
"display": "4111-11xx-xxxx-1111",
"validation_status": "VALID",
"invalid_reason": null,
"details": {
"class":"payment_method_details",
"holder":"Card Holder Name",
"scheme": "VISA",
"exp_month":"01",
"exp_year":"2016"
}
}
},
"customer": {
"class": "customer",
"email": "test@domain.com",
"language": "en"
},
"payment_method": {
"class": "payment_method",
"type": "CREDITCARD",
"display": "4111-11xx-xxxx-1111",
"validation_status": "VALID",
"invalid_reason": null,
"details": {
"class":"payment_method_details",
"holder":"Card Holder Name",
"scheme": "VISA",
"exp_month":"01",
"exp_year":"2016"
}
}
}
As with the payments, you will be notified whenever a refund is complete, with the same data structure as the one returned during the refund request API call:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| class | string | Y | The type of object which is being returned. In this case it will be refund. |
| id | int | Y | The SysPay reference of the returned refund. |
| reference | string | Y | The Merchant refund identifier which was sent on in the request call. |
| amount | int | Y | The amount in cents. |
| currency | string | Y | The currency (ISO-4217). |
| status | string | Y | The refund status. see status. |
| processing_time | unix timestamp | Y | The time stamp of when the refund was processed. Null is returned if the transaction is still not complete. |
| description | string | N | The refund description which was sent on in the request call. |
| extra | string | N | The extra parameter which was sent on in the request call. |
| payment | object | Y | The original payment object. see payment. |
| failure_category | string | N | When a refund fails, this parameter will include extra information about the error (reference). |
{
"class":"refund",
"id":64,
"reference":"998249",
"amount":5000,
"currency":"EUR",
"status":"SUCCESS",
"processing_time":1367488337,
"description":"goods could not be delivered",
"extra":"Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
"payment": { /* ... related payment object ... */ }
}
When a chargeback has been received for a payment you made, you will be notified with a dedicated event that will also include the original payment information:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| class | string | Y | The type of object which is being returned. In this case it will be chargeback. |
| id | int | Y | The SysPay reference of the returned chargeback. |
| amount | int | Y | The amount in cents. |
| currency | string | Y | The currency (ISO-4217). |
| status | string | Y | The chargeback status. see status. |
| 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 |
| processing_time | unix timestamp | Y | The time stamp of when the chargeback was processed. Null is returned if the transaction is still not complete. |
| bank_time | unix timestamp | N | When the chargeback has been approved by the bank. |
| reason_code | string | Y | The chargeback reason code (the value depends on the card scheme or the payment method used) - UNKNOWN if the reason was not given by the bank. |
| payment | object | Y | The original payment object. see payment. |
{
"class": "chargeback",
"id": 19,
"amount": 500,
"currency": "EUR",
"status": "SUCCESS",
"level": "HARD",
"processing_time": 1426171000,
"bank_time": 1426230400,
"reason_code": "UNKNOWN",
"payment": { /* ... related payment object ... */ }
}