With the integration of our push service it's possible to get automatically an update when f. e. a status change for a transaction occurs (f. e. when some prepay transaction was paid and can now be shipped by the merchant). So you don't need to request the details of each transaction in the last days to only check if some status change happen.

Here is a sample message which was send from the secuconnect server to a client system:

Headers

Content-Type: application/json
Content-Length: 209
Accept: */*
Connection: close
Referer: https://connect.secucard.com

Body

{
  "object":"event.pushes",
  "id":"evt_12345678",
  "created":"2018-10-19T09:28:48+02:00",
  "target":"payment.secupayinvoices",
  "type":"changed",
  "data":[
    {
      "object":"payment.secupayinvoices",
      "id":"gcacbezjwtrt12052450"
    }
  ]
}

In the body of the message you can see that there is some payment transaction id for an invoice payment. There is also a reason why you got this message. In this case it's the value "changed", which should indicate that the status of the payment transaction has changed and you can request the new data now. You need always to request the changed data via a separate call. This is because of some security reasons and also because the message should be as small as possible, so that the f. e. a mobile client can decide which data he needs or when he will process the changed status information.

Currently there are only a few types possible:

  • changed
  • added
  • display

Parameter

  • id – An internal ID of the Push-Notification
  • created – Time of the status change of the transaction
  • target – Object-Type (identical with the API-Endpoint with which the details can be retrieved: payment.secupayprepays -> GET /api/v2/Payment/Secupayprepays/xxx )
  • type – see above
  • data.id – The Payment-ID which is needed for the GET call

Implementation

At first you need some URL where the secupay system can send the push notifications to you. F. e. if you have this as shop domain: https://shop.example.com . You can use something like this https://api.example.com/secupay/push as your endpoint for your push service. On this URL you have some application which is listening on HTTPS requests.

You can transmit this URL on each request in the field redirect_url.url_push (when you create a new payment transaction).

Here is a list of steps you need to implement into this application:

Check the event type

Your event controller needs to check the type and the target parameter of the received JSON-Message. These two parameter specify the group of the event.

In case of a payment transaction you will always get event with type = changed and with the specific payment method as target.

The event controller should now look if there is some active event listener for this group of event messages.

Request additional data via the API

If there is a active event listener you should normally call the "GetByID" method of the used SDK to receive the details of the specified data model.

Handle the event

With this returned data model you should now process the event with your defined event action.

This can be for example to update the status of your order to paid and to inform the payer that you will now ship his order.

Confirm the event

After you have processed this event message you should send us a "HTTP 200 OK" status back. Otherwise we will try to send you the message again (up to two days). The messages will be send on every 5 minutes, currently.

You need to process the event in less than 30 seconds! Otherwise the domain of the Push-URL will be blacklisted (for a couple of minutes) and we will delay all other event messages to your application.