Push-Service

The Push Service enables automatic updates when status changes for transactions occur (e.g. when s prepay transaction was paid and can now be shipped by the merchant). With that, it is not necessary to request details of each past transaction to check if a status change happened.

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

The values for target and object may change depending on the payment method that you use.

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"
}
]
}

The body of the message contains a payment transaction id for an invoice payment. The parameter "type":"changed" indicates that the status of the payment transaction has changed and you can now request new data. Data changes need to be requested via a separate call for security reasons and in order to keep messages as small as possible, so that the for example a mobile client can decide which data is needed or when to 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 to the API-Endpoint for retrieving details: payment.secupayprepays -> GET /api/v2/Payment/Secupayprepays/xxx )

  • type – see above

  • data.id – The Payment-ID which is needed for the GET call

Implementation

A URL is needed for the secupay system to send push notifications to.

Example:

With a Shop domain:

https://shop.example.com .

A possible Push URL as an endpoint for the push service is:

https://api.example.com/secupay/push

This URL requires an application that is listening to HTTPS requests. The URL is transmitted with every request in the field redirect_url.url_push (when you create a new payment transaction).

Steps to implement the push-service

  1. Check the event type

  2. Request additional data via the API

  3. Handle the event

  4. Confirm the event

1 Check the event type

Make sure your event controller is checking type and target parameter received JSON - messages. These two parameters specify the group of the event.

Payment transactions are always events with "type":"changed", and have a payment method as target.

The event controller will check if there is an active event listener for this group of event messages.

2 Request additional data via the API

Calling the method GetByID of the used SDKs will let you receive the details of the specified data model. Requires an active event listener.

3 Handle the event

Process the new event with a defined event action using the returned data model.

Use this to update the status of your order. For example, when a payment is received, update the order to paid and to inform the payer that you will now ship their order.

4 Confirm the event

Send a "HTTP 200 OK" status back to secupay upon processing this event message. If the event is unconfirmed, secupay will try to send the message again, every 5 minutes for up to 2 days.

The event should be processed in less than 30 seconds. Otherwise, the domain of the Push-URL will be blacklisted (for a a few mintes) and all other event messages to the application are delayed.