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

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.

The message is sent repeatedly until your system responds with 200 OK or another 2xx status code. After 24 hours without such acknowledgement, our system discards the notification for this event. 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.

Check the Status and Amount of the Payment

For concerns of security and simplicity, you should not regard the Payment Transaction ID in the push event as definitive. The Payment Transaction ID could be the original ID, associated with a refund, a mixed-basket or stakeholder payment relating to the same transaction. But it could also be completely forged.

Although it is unlikely that anyone would obtain both the URL and one of your IDs, you should only work with the Payment Transaction ID that you found in the Smart Transaction after the payment has been authorised.

Using the original Payment Transaction ID also simplifies your implementation, since it is much easier to consider refunds based on the remaining amount returned by `checkStatus`, provided these do not need to be recorded individually.

The API endpoint to obtain the current status and the effective amount is GET /api/v2/Payment/Transactions/{id}/checkStatus.

Request
GET /api/v2/Payment/Transactions/PCI_AEVDQO42JC3YHO4PSAZ3CQJU4S0P5A/checkStatus HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo

The request needs no body.

If everything is fine, the API responds with 200 OK and these details:

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"status": 9,
"status_text": "vorautorisiert",
"status_simple": 2,
"status_simple_text": "authorized",
"amount": 8600,
"currency": "EUR"
}

The fields are:

Field

Type

Meaning

status

int

Status ID

status_text

string

Status text (translated)

status_simple

int

Simple status ID:

  • 1 – Accepted

  • 2 – Authorised

  • 3 – Denied

  • 4 – Issue

  • 5 – Void

  • 6 – Issue resolved

  • 7 – Refund

  • 9 – Paid (requires a special contract setting)

  • 10 – Pending

  • 11 – Subscription approved

  • 12 – Subscription declined

  • 13 – On hold

  • 14 – Waiting for shipment (only invoice payment)

  • 15 – Container authorised

  • 16 – Container denied

status_simple_text

string

Simple status text (English)

amount

int

Effective amount of the transaction including refunds. Like all monetary amounts, it is rendered in the smallest currency unit, e. g. Euro Cents.

Zero (0), when the transaction has been completely cancelled. Otherwise the current transaction amount minus all promising or completed refund transactions.

A more complex example:

  1. Original amount of 50.00 EUR
  2. Partial cancellation of 10.00 EUR — original Payment Transaction is reduced to 40.00 EUR
  3. Payment arrived — original Payment Transaction will stay at 40.00 EUR from now on
  4. Refund of 5.00 EUR — push for refund transaction, checkStatus returns 35.00 EUR
  5. Refund fails (e. g. account dissolved) or gets cancelled in time — push for refund transaction, checkStatus returns 40.00 EUR again

currency

string

ISO 4217 currency code such as EUR or CHF.

See Also