Get All Payment Series

GET 
/payment-series

Returns a list of all payment series with pagination, based on the filters passed on as query parameters.

info

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

info

If a query parameter that is not listed below is included in the request, it will be ignored. Similarly, any query parameter with an invalid value will also be disregarded.

tip

Gte: Greater Than or Equal >=
Lte: Lower Than or Equal <=

Request

Query Parameters

page integer

Number of the desired page for which data should be returned. Page numbers use zero-based numbering e.g., to get the 10th page, you need to set page=9.

pageSize integer

Number of Payment series per Page requested (e.g., 10).

createdAtLte string<date-time>

Created before the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

createdAtGte string<date-time>

Created after the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

updatedAtLte string<date-time>

Updated before the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

updatedAtGte string<date-time>

Updated after the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

deleted string

Possible values: [true, false]

Possible values: true, false

externalMerchantId string

Custom merchant external reference linked to the payment series during its creation

externalReference string

Custom external reference linked to the payment series during its creation

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 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.
]

Example (auto)

{
  "page": 0,
  "pageSize": 0,
  "count": 0,
  "totalPages": 0,
  "data": [
    {
      "id": "PaymentSeries-fe3f839f-c8b5-48cd-a4f4-cbbb3766013b",
      "createdAt": "2021-05-10T15:38:01.02Z",
      "updatedAt": "2021-05-10T15:38:01.02Z",
      "deletedAt": null,
      "customerAccountId": "NewcustomerTestPSerie00",
      "currencyIsoCode": "EUR",
      "externalMerchantId": "MerchantExternalIDPSeries01",
      "merchantMetadata": "{ \"clientId\": 453456790 }",
      "externalReference": "PaymentSeries 1 Payment 1",
      "billingAgreement": null,
      "billingAddress": {
        "addressLine1": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
      },
      "shippingAddress": {
        "addressLine1": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
      },
      "consumer": {
        "firstName": "FirstNameA",
        "lastName": "LastNameA",
        "emailAddress": "NewcustomerTestPSerie00@mail.com",
        "title": "Mr",
        "culture": "en-en",
        "dateOfBirth": "1995-01-26",
        "gender": "M",
        "mobilePhone": "1234567890",
        "homePhone": "1234567891",
        "workPhone": "1234567892"
      },
      "customReferences": {
        "custom1": "custom reference 1",
        "custom2": "custom reference 2",
        "custom3": null
      }
    }
  ]
}

Example

{
  "page": 0,
  "pageSize": 3,
  "count": 3,
  "totalPages": 1,
  "data": [
    {
      "id": "PaymentSeries-2399b4ad-7d69-42bd-b08e-65884391f72f",
      "createdAt": "2021-06-14T17:57:24.93Z",
      "updatedAt": "2021-06-14T17:57:24.93Z",
      "deletedAt": null,
      "customerAccountId": "NewcustomerSeries01",
      "currencyIsoCode": "EUR",
      "externalMerchantId": "MerchantExternalPSeries01",
      "merchantMetadata": "{ \"clientId\": 453456790 }",
      "externalReference": "PaymentSeries 01 Payment02",
      "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": "NewcustomerSerie01@email.com",
        "title": "Mr",
        "culture": "en-en",
        "dateOfBirth": "1995-01-26",
        "gender": "M",
        "mobilePhone": "1234567890",
        "homePhone": "1234567891",
        "workPhone": "1234567892",
        "taxId": null
      },
      "billingAgreement": null
    }
  ]
}

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