Background

In November 2024, secupay AG obtained principal membership for Visa and Mastercard for credit card acquiring services. This enables us to offer our customers services that are better tailored to their needs. In order to benefit from the changes, the service must be converted to the new acquiring model and, depending on the scope of functions, the technical connection must also be adapted. We will involve you in this process in good time and to the extent necessary.

The following is only relevant for credit card payments based on secupay acquiring.

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:

Request
POST /Smart/Transactions HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
// ...
"payment_context": {
// ...
        "container_instructions": {
"request_token": true,
"notification_url": "https://shop.example.com/payment_tokens/update?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 /payment_tokens/update?order=12345 HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Accept: */*
 
{
"object": "event.pushes",
"id": "evt_qe5dvzd3ave7hzbi8vlmrdwjypc2k4mg",
"created": "2021-06-21T08:30:28+02:00",
"target": "payment.containers",
"type": "changed",
"data": [
{
"object": "payment.containers",
"id": "PCT_LQS4L6E94XULQINVOI0CCRP19JXF83"
}
]
}

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 Network Tokens

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

Event

"target"

"type"

Payment status changed (s. Read a Payment Transaction)

"payment.containers"

"changed"

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

Read the Payment Container

The endpoint to read a single Payment Container is GET /Payment/Containers/{id}:

Request
GET /api/v2/Payment/Containers/PCT_LQS4L6E94XULQINVOI0CCRP19JXF83 HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the secuconnect API responds with 200 OK, and the Payment Container object:

Response
{
"object": "payment.containers",
"id": "PCT_WWEG8NWW32QCX576ED5T82K6G834AZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_WQFUNMZRYY5NK2C7YQVV4Q48GC2BN3",
"parent": {
"object": "general.merchants",
"id": "MRC_WFVX3EAKBEPNAQ2JWDV7FJ48GAWSNW",
"type": 21
}
},
"customer": {
"object": "payment.customers",
"id": "PCU_WNNDK4NER2QCX56XD2B3VDWZ03RAA3"
},
"type": "credit_card",
"token_status": {
"status": "active",
"created": "2026-02-20T09:30:53+01:00",
"last_modified": "2026-02-20T09:30:53+01:00",
"version": 2
},
"private": {
"owner": "Norbert Ntigstes",
"pan": "463544XXXXXX2298",
"expiration_date": "2029-11-30T22:59:59+01:00",
"issuer": "VISA"
},
"public": {
"owner": "Norbert Ntigstes",
"pan": "463544XXXXXX2298",
"expiration_date": "2029-11-30T22:59:59+01:00",
"issuer": "VISA"
},
"created": "2026-02-20T10:30:52+01:00",
"updated": "2026-02-20T10:30:52+01:00",
"notification_url": "https://shop.example.com/network-token/update"
}

The most interesting field is token_status/status. These are the possible values:

  • "not requested"
  • "requested"
  • "inquiry"
  • "active"
  • "failed"
  • "archivePending"
  • "archived"

So you should only use Payment Containers for credit card payment having status "active". Payment Containers having "requested" or "inquiry" must wait to become "active". Payment Containers having another status can be used no more. You would not more offer them for One-Click-Payment. You will need to manage this situation with your customer if it was saved to be used for a standing order or subscription, technically for MIT transactions.

See Also