Get All Events

GET 
/events

Returns a list of all events with pagination. This feature enables the Merchant to check all events that were processed for a specific object (e.g., subscription, transaction). It enables tracking an object from its creation, the updates that were performed on its level, and even when it was deleted if applicable.

info

The request must provide the following header: x-api-key: {merchantKey}

Request

Query Parameters

origin string

Possible values: [api, widget, automated]

Origin triggering the event: an API call, an action performed on the Widget or an event triggered by SmartPay backend

page integer

Number of the page for which the data is to be returned.

pageSize integer

Number of the records to display per page.

objectType string

Possible values: [subscription, plan, billing-cycle, payment-series, transactions, manual-retry, payment, refund]

Type of the object linked to the created event & notification.

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

x-api-key stringrequired

x-api-key: {merchantKey}

Responses

200

Successful response

application/json

Schema

Schema

pageinteger
pageSizeinteger
countinteger
totalPagesinteger
data object[]
Array [
idstringrequired
Unique Identifier of the Event. Format: Event + - + <UUID>
Example: event-f81c4016-9c74-4046-9079-c00dbe4a5ce2
createdAtstring<date-time>required
Time of the creation of the event.
Example: 2021-05-26T14:29:05.994Z
sourceSystemstring
Origin system.
Possible values: [subscription-module]
Example: subscription-module
originstringrequired
Origin triggering the event.
Possible values: [api, widget, automated]
Example: api
eventTypestringrequired
Description of the event type.
Possible values: [updated, created, deleted, status.updated, billing.expires, billing.updated, billing.scheduled]
Example: created
objectIdstringrequired
Unique identifier of the object linked to the created event & notification.
Example: subscription-f81c4016-9c74-4046-9079-c00dbe4a5ce2
objectTypestringrequired
Name of the object linked to the created event & notification.
Possible values: [subscription, subscription.plan, billing-cycle, payment-series, transactions, manual-retry, payment, refund]
Example: subscription
metadata object
Optional object. Additional Ids and details linked to the notification.
property name*string
data object[]
Data of the object linked to the events.
Array [
idstringrequired
Unique Identifier of the Payment Series. Format: PaymentSeries + - + <UUID>
Example: PaymentSeries-fe3f839f-c8b5-48cd-a4f4-cbbb3766013b
createdAtstring<date-time>required
Timestamp of when the payment series was created.
Example: 2021-05-10T15:38:01.02Z
updatedAtstring<date-time>required
Timestamp of when the payment series was last updated.
Example: 2021-05-10T15:38:01.02Z
deletedAtstring<date-time>nullable
Timestamp of when the payment series was deleted (if applicable).
customerAccountIdstringrequired
Customer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g., customer number For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any.
Possible values: <= 125 characters
Example: NewcustomerTestPSerie00
currencyIsoCodestringrequired
Currency code. Format ISO 4217.
Possible values: >= 3 characters and <= 3 characters
Example: EUR
externalMerchantIdstring
Field that allows the merchant to store a specific value for external reference. Available as a filtering field.
Possible values: <= 255 characters
Example: MerchantExternalIDPSeries01
merchantMetadatastringnullable
Field that allows the merchant to store a specific metadata linked with the payment series.
Possible values: <= 255 characters
Example: { "clientId": 453456790 }
externalReferencestring
Integrating merchant could link any custom reference on their end to the payment series through this field.
Possible values: <= 255 characters
Example: PaymentSeries 1 Payment 1
billingAgreement object
Billing Agreement linked to the Subscription.
Hosting the payment instrument information returned as null for newly created subscription.
idstringrequired
Unique Identifier of the Billing Agreement. Format: BillingAgreement + - + <UUID>
Possible values: <= 50 characters
Example: BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771
paymentObjectIdstringrequired
PaymentObject used for billing this subscription.
Example: 8ac7a49f8609e07601860ca28ce656ed
billingAgreementDatestring<date-time>required
Date when the billing agreement was created.
Possible values: <= 24 characters
Example: 2021-01-26T14:29:05.994Z
namestringrequired
Display name of the payment option which has been stored.
Possible values: <= 255 characters
Example: Mastercard
codestringrequired
Code of the payment option which has been stored.
Possible values: <= 255 characters
Example: MSTRCRD
carrierNumberstring
Masked carrier number of the payment instrument which has been stored.
Example: 401288****1881
isExpiredbooleanrequired
Indicates if a card used as a payment option is expired or not.
Possible values: [true, false]
Example: false
expiryDatestringrequired
If a card is used as a payment option, this shows its expiry date.
Possible values: <= 7 characters, Value must match regular expression ^(0[1-9]|1[0-2])/[0-9]{4}$
Example: 04/2024
storedPaymentOptionDataobjectnullable
Additional data related to the stored payment option.
billingAddress objectrequired
Billing or shipping address of the consumer. Please refer to Data Model for details.
addressLine1stringrequired
Address line 1.
Possible values: <= 60 characters
Example: Leopoldstrasse
addressLine2stringnullable
Address line 2.
Possible values: <= 60 characters
addressLine3stringnullable
Address line 3.
Possible values: <= 60 characters
numberstringrequired
House number/building number.
Possible values: <= 10 characters
Example: 244
citystringrequired
City name of the address.
Possible values: <= 50 characters
Example: Munich
postCodestringrequired
Postal code of the address.
Possible values: <= 10 characters
Example: 80807
countryCodestringrequired
Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.
Possible values: >= 2 characters and <= 3 characters
Example: DE
statestringnullable
State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.
Possible values: <= 3 characters
shippingAddress object
Billing or shipping address of the consumer. Please refer to Data Model for details.
addressLine1stringrequired
Address line 1.
Possible values: <= 60 characters
Example: Leopoldstrasse
addressLine2stringnullable
Address line 2.
Possible values: <= 60 characters
addressLine3stringnullable
Address line 3.
Possible values: <= 60 characters
numberstringrequired
House number/building number.
Possible values: <= 10 characters
Example: 244
citystringrequired
City name of the address.
Possible values: <= 50 characters
Example: Munich
postCodestringrequired
Postal code of the address.
Possible values: <= 10 characters
Example: 80807
countryCodestringrequired
Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.
Possible values: >= 2 characters and <= 3 characters
Example: DE
statestringnullable
State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.
Possible values: <= 3 characters
consumer objectnullable
Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
Conditional. Can be present if businessConsumer is missing from the request.
firstNamestringrequired
First name of the consumer.
Possible values: <= 60 characters
Example: John
lastNamestringrequired
Last name of the consumer.
Possible values: <= 60 characters
Example: Smith
middleNamestringnullable
Middle name of the consumer.
Possible values: <= 60 characters
Example: .
emailAddressstring<email>required
Email address of the customer.
Possible values: <= 255 characters
Example: john.smith@smithentreprise.com
titlestring
Title of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
Example: Mr
culturestring
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-de
dateOfBirthstring<date>required
Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
Example: 1995-01-26
genderstring
Gender of the consumer.
Possible values: [M, F, D]
Example: M
mobilePhonestring
Mobile phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
homePhonestring
Home phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
workPhonestring
Work phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
taxIdstringnullable
Tax ID of the consumer.
Possible values: <= 30 characters
Example: DE1927456229
businessConsumer objectnullable
Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
Conditional. Can be present if consumer is missing from the request.
firstNamestringrequired
First name of the consumer.
Possible values: <= 60 characters
Example: John
lastNamestringrequired
Last name of the consumer.
Possible values: <= 60 characters
Example: Smith
middleNamestringnullable
Middle name of the consumer.
Possible values: <= 60 characters
Example: .
emailAddressstring<email>required
Email address of the customer.
Possible values: <= 255 characters
Example: john.smith@smithentreprise.com
titlestring
Title of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
Example: Mr
culturestring
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-de
dateOfBirthstring<date>required
Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
Example: 1995-01-26
genderstring
Gender of the consumer.
Possible values: [M, F, D]
Example: M
mobilePhonestring
Mobile phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
homePhonestring
Home phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
workPhonestring
Work phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
taxIdstringnullable
Tax ID of the consumer.
Possible values: <= 30 characters
Example: DE1927456229
customReferences object
Custom references for external party usage
custom1stringnullable
Custom reference 1 for external party usage
Possible values: <= 255 characters
Example: custom1 test1
custom2stringnullable
Custom reference 2 for external party usage
Possible values: <= 255 characters
Example: custom1 test2
custom3stringnullable
Custom reference 3 for external party usage
Possible values: <= 255 characters
Example: null
criteria object
An array of key-value pair objects. Please refer to Data Model for details.
namestringrequired
Parameter name.
Possible values: <= 50 characters
Example: recollectionDate
valuestringrequired
Parameter value.
Possible values: <= 100 characters
Example: 2023-07-15
targetMerchantAccountReference
If provided, the payment is processed in favour of the indicated sub-merchant account, and the main merchant account number is ignored.
]
contextstring
This is the request body for api and widget events.
]

Example (auto)

{
  "page": 0,
  "pageSize": 0,
  "count": 0,
  "totalPages": 0,
  "data": [
    {
      "id": "event-f81c4016-9c74-4046-9079-c00dbe4a5ce2",
      "createdAt": "2021-05-26T14:29:05.994Z",
      "origin": "api",
      "eventType": "created",
      "objectId": "Subscription-7a3df18e-eb91-429f-99da-b52a2823de87",
      "objectType": "subscription",
      "metadata": {
        "reconciliationId": "102957125651"
      },
      "data": {
        "id": "Subscription-7a3df18e-eb91-429f-99da-b52a2823de87",
        "status": "created"
      },
      "context": "{\"customerAccountId\":\"customer123\",\"planId\":\"plan456\"}"
    }
  ]
}

Example

{
  "page": 7,
  "pageSize": 1,
  "count": 8,
  "totalPages": 8,
  "data": [
    {
      "id": "Event-0d51a439-7e17-4dc8-9060-5c2ec9ac9ce7",
      "createdAt": "2021-06-08T08:37:03.14Z",
      "origin": "api",
      "eventType": "created",
      "objectId": "Transaction-cc9b3585-c7bf-4ae0-9be7-545778593299",
      "objectType": "transaction",
      "data": {
        "id": "Transaction-cc9b3585-c7bf-4ae0-9be7-545778593299",
        "customerAccountId": "NewcustomerTestPSeries00",
        "storedPaymentOptionReference": "8ac7a49f79ea7b760179eaae946a4ff7",
        "modificationId": "783ad3b1-69a6-4fe1-9c3e-1742dd81e4a6",
        "paymentStatus": null,
        "payment": {
          "description": "MerchantExternalIDPSeries01",
          "amount": 6,
          "currencyIsoCode": "EUR"
        },
        "billingAddress": {
          "addressLine1": "Leopoldstrasse",
          "addressLine2": null,
          "addressLine3": null,
          "number": "244",
          "city": "Munich",
          "postCode": "80807",
          "countryCode": "DE",
          "state": null
        },
        "shippingAddress": {
          "addressLine1": "Leopoldstrasse",
          "addressLine2": null,
          "addressLine3": null,
          "number": "244",
          "city": "Munich",
          "postCode": "80807",
          "countryCode": "DE",
          "state": null
        },
        "consumer": {
          "firstName": "FirstNameA",
          "lastName": "LastNameA",
          "middleName": null,
          "emailAddress": "NewcustomerTestPSerie00@mail.com",
          "title": "Mr",
          "culture": "en-en",
          "dateOfBirth": "1995-01-26",
          "gender": "M",
          "mobilePhone": "1234567890",
          "homePhone": "1234567891",
          "workPhone": "1234567892",
          "taxId": null
        },
        "transactionLogs": null
      },
      "context": "{"description":"first TRX PS!","amount":6.00}"
    }
  ]
}

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}