Integration Guide

Prerequisites

Before you read this, you should understand this:

What Is a Push Notification?

Our secuconnect API can send host-to-host push notifications to inform you about new transactions or important changes. There are also push notifications for more elaborate use cases like subscriptions, or activation of contracted merchants (marketplaces) or projects (crowd platforms).

Push notifications are sent for Payment Transactions whenever the simple status has changed, or when a subscription payment or a refund transaction have been created.

Set a Push URL

If you want to receive status updates, you can pass a push URL to the Smart Transaction:

Smart Transaction

{
    // ...
    "application_context": {
        "return_urls": {
            "url_push": "https://shop.example.org/PUSH?order=12345"
        }
    }
}

The push URL is forwarded to objects created during the life cycle of the Smart Transaction.

Process a Push Notification

Our system sends an HTTP POST request to the push URL. The JSON body contains information about the object and the event it was generated for.

Callback Request

POST /order/payment/status-push?order=OID_100716 HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Accept: */*
 
{
    "object": "event.pushes",
    "id": "evt_d7a9cbd91c125ae409398b4e0e3199be",
    "created": "2021-06-21T08:30:28+02:00",
    "target": "payment.transactions",
    "type": "changed",
    "data": [
        {
            "object": "payment.transactions",
            "id": "PCI_2FY48DT0P2X6G636N5QK64UK2ADZAZ"
        }
    ]
}

The message is sent repeatedly until your system responds with 200 OK. After 24 hours without such acknowledgement, our system discards the notification for this event.

These are the details of the notification:

Field	Type	Meaning
`object`	`string`	Object type (always `"event.pushes"`)
`id`	`string`	Object ID of the push event
`created`	`string`	Time of the event
`target`	`string`	Object type: `payment.transactions`: Payment Transaction `payment.subscriptions`: Subscription
`type`	`string`	Event type: `changed`: The object has changed `added`: The object has been added
`data`	`array`	Related data objects. There should be only one object `/data/0`.

Every related object (data) has these fields:

Field	Type	Meaning
`object`	`string`	Object type; same as `target` (see above)
`id`	`string`	Object ID

Now you might read the related data object, or perhaps related ones, and process the outcome. Finally you would signalise our push service whether your system could process the push notification successfully or not.

If your application responds with any HTTP status 200 .. 299, it is evaluated as completed. Any other HTTP response status will cause the push service to repeat the notification for that event. This happens at increasing intervals for 24 hours. You can also provide a short response body in any format for help us with troubleshooting.

Push Events for Payments

For payments you receive a push notification for important status changes:

Event	`"target"`	`"type"`
Payment status changed (s. Read a Payment Transaction)	`"payment.transactions"`	`"changed"`

The Payment Transaction is already known from the authorised or captured Smart Transaction.

Find Smart Transaction by Payment Transaction ID

You may know the Smart Transaction ID for your order, but not the Payment Transaction ID. For example, the URL for the success or failure may not have been accessed for some reason. However, you can search for Smart Transactions associated with a Payment Transaction.

The endpoint to find Smart Transactions is GET /Smart/Transactions?q={criteria}, and the only criteria for our question are transactions.id:{pci-id} and optionally count=1:

Request

GET /Smart/Transactions?q=transactions.id:PCI_8G1AWZV5DAD855Y3WSXEA6I1D6HSUH&count=1 HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

A request body is not needed.

If everything is fine, the secuconnect API responds with a list of Smart Transactions:

Request

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "count": 1,
    "data": [
        {
            "object": "smart.transactions",
            "id": "STX_71AYP2RUKQF5GGRK879IIU1EPPPPQ8",
            ...
            "transactions": [
                {
                    "object": "payment.transactions",
                    "id": "PCI_8G1AWZV5DAD855Y3WSXEA6I1D6HSUH",
                    "trans_id": 110099706,
                    "transaction_hash": "mcqukfrkwgxz11060212"
                }
            ],
            ...
            "transactionRef": "12345",
            ...
        }
    ]
}

The response should contain one Smart Transaction if matching, or none of not.

You should also save the Payment Transaction ID to your order. It is likely that more pushes will arrive. If you save your order IDs to transactionRef, you can also use this field.

The field count returns the number of total matches, including those not returned. One is a match, zero is a mismatch, everything else should be handled as application error.