Navigation

Table Of Contents

1.6. eMerchant Event Messaging System (EMS)

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.

1.6.1. EMS message content

The data provided will contain the following keys:

1.6.2. EMS callback validation

A callback will be provided with the following HTTP headers that will let you validate that the call is genuine:

  • X-Merchant: Your API login
  • X-Checksum: A checksum computed from the request body and the shared passphrase
  • X-Event-Id: Event unique ID
  • X-Event-Date: Event creation date, as timestamp

The checksum is computed the following way:

HEX_SHA1(REQUEST_BODY + PASSPHRASE)

Example code (PHP)

<?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
}

1.6.3. Event types

Payment event

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:

Event parameters

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

Raw sample of HTTP body content (application/x-www-form-urlencoded)

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
                        )
                )
        )
)

Refund event

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)

Raw sample of HTTP body content (application/x-www-form-urlencoded)

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
                        )
                )
        )
)

Chargeback event

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:

  • The call will always be made to your default EMS url
  • If a billing agreement is linked to the payment that the chargeback has been made on, this billing agreement will be automatically ended.

Event parameters

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)

Raw sample of HTTP body content (application/x-www-form-urlencoded)

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
                                )
                        )
                )
        )
)

Billing Agreement event

Whenever the status of one of your billing agreements changes, you will be notified.

The typical reason for a billing agreements to end are:

  • You requested explicitely to cancel the billing agreement (see Cancel a billing agreement)
  • A chargeback has been received on a payment part of the billing agreement (see Chargeback event)
  • The card linked to the billing agreement has expired or has been reported as stolen, lost or cancelled

Event parameters

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

Raw sample of HTTP body content (application/x-www-form-urlencoded)

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
                )
        )
)

Subscription event

When the status or the phase of a subscription changes, you will receive a notification with the up-to-date information.

Event parameters

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)

Raw sample of HTTP body content (application/x-www-form-urlencoded)

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
                        )
                )
        )
)

Navigation

© Copyright 2016, SysPay.