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.

.Net SDK Sample

At first you need some URL where we 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. You can transmit this url on each request in the field redirect_url.url_push (when you create a new payment transaction).

Register event listener

On this url you have some application which is listening on HTTP requests. With the SDK and ASP.NET you can do this easily by adding this code:

[HttpPost]
public IHttpActionResult Post(dynamic value)
{
    InitSecucardConnectClient();

    // Register event listiener
    var service = client.Payment.Secupayinvoices;
    service.PaymentEvent += PaymentEvent;

    // Handle event message
    client.HandleEvent(this, "" + value);

    // Return HTTP 200 OK -> To tell that this push notification was processed and the server can cease to send this notification (again).
    return Ok();
}

You can find the complete code on github by follow this link: https://github.com/secucard/secucard-connect-net-sdk-demo/

Define the event method

When you register an event listener you need to define a method which will handle the push event. In the sample above this method is called PaymentEvent. This method need two parameters sender and args. With the first one you know which event listener or which service class has accepted this push notification and with the second one you will get all the event details.

private static void PaymentEvent(object sender, PaymentEventEventArgs<SecupayCreditcard> args)
{
    var service = (Secucard.Connect.Product.Payment.SecupayCreditcardsService)sender;
    var transaction = args.SecucardEvent.Data[0];
}

Handle the event

When you receive some message on you url, you will redirect this message (as plain text) to the event handle of the secuconnect client:

client.HandleEvent(this, "" + value);

The event handle will now check if the message format and type matches with some registered event listener and then it will call the event method to process this message.

Return response

After the event was successfully processed you will just return a HTTP 200 OK back.