The SysPay Event Messaging System will call the URL you provided us anytime an event occurs. By default the data will be encoded in application/x-www-form-urlencoded.
The data provided will contain the following keys:
data: The event-specific data
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 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 |
---|---|---|---|
type | string | Y | payment |
data.payment.id | int | Y | The SysPay payment reference |
data.payment.payment_type | string | Y | The payment type (reference) |
data.payment.reference | string | Y | Merchant payment identifier |
data.payment.amount | int | Y | The amount in cents |
data.payment.currency | string | Y | The currency (ISO-4217) |
data.payment.status | string | Y | The payment status (reference) |
data.payment.flow | string | Y | The flow used to process the payment |
data.payment.processing_time | unix timestamp | Y | When the payment has been processed, null if the transaction is still not complete |
data.payment.website | int | N | The id of the website the payment has been made for |
data.payment.website_url | string | N | The URL of the website the payment has been made for |
data.payment.contract | string | N | The contract name used to process the payment (relevant only when using the super gateway feature) |
data.payment.descriptor | string | N | For creditcard payments, this is the descriptor that will be shown on the card statement |
data.payment.extra | string | N | Extra parameter that was passed on payment request |
data.payment.description | string | N | The merchant payment description |
data.payment.account_id | int | Y | The SysPay account id that the API access is linked to |
data.payment.merchant_id | int | Y | The SysPay API access id |
data.payment.merchant_login | string | Y | The SysPay API login used to process the payment |
data.payment.settlement_date | unix timestamp | N | A timestamp indicating when this payment will be settled |
data.payment.failure_category | string | N | When a payment failed, this field will include extra information about the failure (reference) |
data.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 sdata.tatus 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 rdata.esults synchronously, this field will reflect the status seen on the device (SUCCESS / FAILED). This should be used for display purpose only |
data.payment.payment_method | object | Y | A payment method object representing the payment method used to process this payment |
data.payment.billing_agreement | object | N | The SysPay billing agreement object, if this payment is part of a billing agreement |
data.payment.subscription | object | N | The SysPay subscription object, if this payment is part of a subscription |
data.payment.parent_id | int | N | (subscription payments only) In case of a re-attempt, this is the id of the failed payment we are re-attempting to charge |
data.payment.subscription_counter | int | N | (subscription payments only) This counter increments every time a payment (trial, standard, re-attempt) occurs on a subscription |
data.payment.subscription_counter_type | int | N | (subscription payments only) This counter increments on every new payment for the current phase (trial, standard) but not if there’s a re-attempt. Basically this shows the number of periods your customer has been subscribed for |
data.payment.subscription_attempt | int | N | (subscription payments only) This counter starts from 1 and increments for every new re-attempt made on a failed subscription rebill |
data.payment.billing_agreement | object | N | If the payment is part of a billing agreement, the event will include the billing agreement information as described in the billing agreement section |
data.payment.subscription | object | N | If the payment is part of a subscription, the event will include the subscription information as described in the subscription section |
type=payment&data%5Bpayment%5D%5Bid%5D=638&data%5Bpayment%5D%5Breference%5D=99946759&data%5Bpayment%5D%5Bamount%5D=5000
&data%5Bpayment%5D%5Bcurrency%5D=EUR&data%5Bpayment%5D%5Bstatus%5D=SUCCESS&data%5Bpayment%5D%5Bextra%5D=some_hash_here
&data%5Bpayment%5D%5Bdescription%5D=shopping+basket+payment&data%5Bpayment%5D%5Bprocessing_time%5D=1370423161&data%5Bpayment%5D%5Bwebsite%5D=29
&data%5Bpayment%5D%5Bbilling_agreement%5D%5Bid%5D=115&data%5Bpayment%5D%5Bbilling_agreement%5D%5Bcurrency%5D=EUR
&data%5Bpayment%5D%5Bbilling_agreement%5D%5Bstatus%5D=ACTIVE&data%5Bpayment%5D%5Bbilling_agreement%5D%5Bextra%5D=some_hash_here
&data%5Bpayment%5D%5Bbilling_agreement%5D%5Bstart_date%5D=1370423159&data%5Bpayment%5D%type%5D=ONESHOT
This decodes to:
Array
(
[type] => payment
[data] => Array
(
[payment] => Array
(
[id] => 638
[reference] => 99946759
[amount] => 5000
[currency] => EUR
[status] => SUCCESS
[extra] => some_hash_here
[description] => shopping basket payment
[processing_time] => 1370423161
[website] => 29
[type] => ONESHOT
[billing_agreement] => Array
(
[id] => 115
[currency] => EUR
[status] => ACTIVE
[extra] => some_hash_here
[start_date] => 1370423159
)
)
)
)
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:
Event parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Y | refund |
data.refund | object | Y | A refund object, as it would be returned from the refund request call |
data.refund.id | int | Y | The SysPay refund reference |
data.refund.reference | string | Y | Merchant refund identifier |
data.refund.amount | int | Y | The amount in cents |
data.refund.currency | string | Y | The currency (ISO-4217) |
data.refund.status | string | Y | The refund status |
data.refund.processing_time | unix timestamp | Y | When the refund has been processed, null if the transaction is still not complete |
data.refund.description | string | N | The refund description |
data.refund.extra | string | N | Extra parameter that was passed |
data.refund.payment | object | Y | The original payment object (see Payment event) |
type=refund&data%5Brefund%5D%5Bid%5D=644&data%5Brefund%5D%5Breference%5D=1237254&data%5Brefund%5D%5Bamount%5D=1000
&data%5Brefund%5D%5Bcurrency%5D=EUR&data%5Brefund%5D%5Bstatus%5D=SUCCESS&data%5Brefund%5D%5Bextra%5D=some_hash_here
&data%5Brefund%5D%5Bprocessing_time%5D=1370427168&data%5Brefund%5D%5Bpayment%5D%5Bid%5D=643
&data%5Brefund%5D%5Bpayment%5D%5Breference%5D=8889320&data%5Brefund%5D%5Bpayment%5D%5Bamount%5D=1000
&data%5Brefund%5D%5Bpayment%5D%5Bcurrency%5D=EUR&data%5Brefund%5D%5Bpayment%5D%5Bstatus%5D=SUCCESS
&data%5Brefund%5D%5Bpayment%5D%5Bextra%5D=some_hash_here&data%5Brefund%5D%5Bpayment%5D%5Bdescription%5D=some+description
&data%5Brefund%5D%5Bpayment%5D%5Bprocessing_time%5D=1370427081&data%5Brefund%5D%5Bpayment%5D%5Bwebsite%5D=29
This decodes to:
Array
(
[type] => refund
[data] => Array
(
[refund] => Array
(
[id] => 644
[reference] => 1237254
[amount] => 1000
[currency] => EUR
[status] => SUCCESS
[extra] => some_hash_here
[processing_time] => 1370427168
[payment] => Array
(
[id] => 643
[reference] => 8889320
[amount] => 1000
[currency] => EUR
[status] => SUCCESS
[extra] => some_hash_here
[description] => some description
[processing_time] => 1370427081
[website] => 29
)
)
)
)
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.
Notes:
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Y | chargeback |
data.chargeback | object | Y | A chargeback object |
data.chargeback.id | int | Y | The SysPay chargeback reference |
data.chargeback.amount | int | Y | The amount in cents |
data.chargeback.currency | string | Y | The currency (ISO-4217) |
data.chargeback.status | string | Y | The chargeback status. This field is there for consistency but will always be SUCCESS |
data.chargeback.processing_time | unix timestamp | Y | When the chargeback has been processed by SysPay |
data.chargeback.bank_time | unix timestamp | N | When the chargeback has been approved by the bank |
data.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 |
data.chargeback.payment | object | Y | The original payment object (see Payment event) |
type=chargeback&data%5Bchargeback%5D%5Bid%5D=612&data%5Bchargeback%5D%5Bamount%5D=5000&data%5Bchargeback%5D%5Bcurrency%5D=EUR
&data%5Bchargeback%5D%5Bstatus%5D=SUCCESS&data%5Bchargeback%5D%5Bprocessing_time%5D=1374054951&data%5Bchargeback%5D%5Breason_code%5D=VI76
&data%5Bchargeback%5D%5Bpayment%5D%5Bid%5D=611&data%5Bchargeback%5D%5Bpayment%5D%5Breference%5D=99927956
&data%5Bchargeback%5D%5Bpayment%5D%5Bamount%5D=5000&data%5Bchargeback%5D%5Bpayment%5D%5Bcurrency%5D=EUR
&data%5Bchargeback%5D%5Bpayment%5D%5Bstatus%5D=SUCCESS&data%5Bchargeback%5D%5Bpayment%5D%5Bextra%5D=some_hash_here
&data%5Bchargeback%5D%5Bpayment%5D%5Bdescription%5D=shopping+basket+payment&data%5Bchargeback%5D%5Bpayment%5D%5Bprocessing_time%5D=1374054731
&data%5Bchargeback%5D%5Bpayment%5D%5Bwebsite%5D=26&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bid%5D=279
&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bcurrency%5D=EUR&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bstatus%5D=ENDED
&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bextra%5D=some_hash_here
&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bstart_date%5D=1374054729&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bend_date%5D=1374055015
&data%5Bchargeback%5D%5Bpayment%5D%5Bbilling_agreement%5D%5Bend_reason%5D=SUSPENDED_CHARGEBACK
This decodes to:
Array
(
[type] => chargeback
[data] => Array
(
[chargeback] => Array
(
[id] => 612
[amount] => 5000
[currency] => EUR
[status] => SUCCESS
[processing_time] => 1374054951
[reason_code] => VI76
[payment] => Array
(
[id] => 611
[reference] => 99927956
[amount] => 5000
[currency] => EUR
[status] => SUCCESS
[extra] => some_hash_here
[description] => shopping basket payment
[processing_time] => 1374054731
[website] => 26
[billing_agreement] => Array
(
[id] => 279
[currency] => EUR
[status] => ENDED
[extra] => some_hash_here
[start_date] => 1374054729
[end_date] => 1374055015
[end_reason] => SUSPENDED_CHARGEBACK
)
)
)
)
)
Whenever the status of one of your billing agreements changes, you will be notified.
The typical reason for a billing agreements to end are:
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Y | billing_agreement |
data.billing_agreement | object | Y | A billing_agreement object |
data.billing_agreement.id | int | Y | The SysPay billing agreement reference |
data.billing_agreement.status | string | Y | The billing agreement status |
data.billing_agreement.currency | string | N | The billing agreement currency (ISO-4217) |
data.billing_agreement.extra | string | N | Extra parameter that was passed when the first payment took place |
data.billing_agreement.start_date | unix timestamp | N | When the billing agreement was created |
data.billing_agreement.end_date | unix timestamp | N | When the billing agreement was ended |
data.billing_agreement.end_reason | string | N | If the billing agreement is ended, this will give you extra information about the reason |
type=billing_agreement&data%5Bbilling_agreement%5D%5Bid%5D=282&data%5Bbilling_agreement%5D%5Bcurrency%5D=EUR
&data%5Bbilling_agreement%5D%5Bstatus%5D=ENDED&data%5Bbilling_agreement%5D%5Bextra%5D=some_hash_here
&data%5Bbilling_agreement%5D%5Bstart_date%5D=1374055834&data%5Bbilling_agreement%5D%5Bend_date%5D=1374056115
&data%5Bbilling_agreement%5D%5Bend_reason%5D=SUSPENDED_CHARGEBACK
This decodes to:
Array
(
[type] => billing_agreement
[data] => Array
(
[billing_agreement] => Array
(
[id] => 282
[currency] => EUR
[status] => ENDED
[extra] => some_hash_here
[start_date] => 1374055834
[end_date] => 1374056115
[end_reason] => SUSPENDED_CHARGEBACK
)
)
)
When the status or the phase of a subscription changes, you will receive a notification with the up-to-date information.
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Y | subscription |
data.subscription | object | Y | A subscription object |
data.subscription.id | int | Y | The SysPay subscription id |
data.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) |
data.subscription.plan_type | string | Y | The subscription’s plan type (SUBSCRIPTION / INSTALMENT) |
data.subscription.ems_url | string | N | The URL that is used to notify about events related to this subscription. |
data.subscription.reference | string | N | Your own reference for this subscription |
data.subscription.status | string | Y | The subscription status (PENDING) (see Subscription statuses) |
data.subscription.phase | string | Y | The phase the subscription is in (NEW) (see Subscription phases) |
data.subscription.customer | object | Y | The customer information |
data.subscription.extra | string | N | The extra parameter received upon request |
data.subscription.start_date | int | N | The subscription start date, if it has already been started |
data.subscription.end_date | int | N | The subscription end date, if the subscription is over |
data.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) |
data.subscription.next_event | object | N | Information about the next scheduled event for this subscription |
data.subscription.next_event.event_type | string | Y | The next event type (subscription events`) |
data.subscription.next_event.scheduled_date | int | Y | The event’s scheduled date/time (timestamp) |
type=subscription&data%5Bsubscription%5D%5Bid%5D=4242&data%5Bsubscription%5D%5Bplan_id%5D=42&data%5Bsubscription%5D%5Breference%5D=52a7026d09420
&data%5Bsubscription%5D%5Bstatus%5D=ACTIVE&data%5Bsubscription%5D%5Bphase%5D=TRIAL
&data%5Bsubscription%5D%5Bextra%5D=Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK
&data%5Bsubscription%5D%5Bcustomer%5D%5Bemail%5D=test%40domain.com&data%5Bsubscription%5D%5Bcustomer%5D%5Blanguage%5D=en
This decodes to:
Array
(
[type] => subscription
[data] => Array
(
[subscription] => Array
(
[id] => 4242
[plan_id] => 42
[reference] => 52a7026d09420
[status] => ACTIVE
[phase] => TRIAL
[extra] => Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK
[customer] => Array
(
[email] => test@domain.com
[language] => en
)
[next_event] => Array
(
[event_type] => "INITIAL"
[scheduled_date] => 1403105797
)
)
)
)