Create PS Transaction

POST 
/payment-series/:paymentSeriesId

Creates a new transaction under a specific Payment Series. You need to provide only the amount of the transaction and its description, all other needed details would be inherited from the parent Payment Series.

info

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

Request

Path Parameters

paymentSeriesId stringrequired
Unique Identifier of the Payment Series. Format: PaymentSeries + - + <UUID>
Example: PaymentSeries-5fb19b1b-8990-4c79-b45c-775f3140dcbb

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}

application/json

Body

Bodyrequired

amountnumber<decimal>

Amount of the transaction

descriptionstring

Description of the transaction. Could be used to send a unique identifier from the Merchant end for the transaction

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

Example

{
  "amount": 7.3,
  "description": "OrderId0010"
}

Responses

201

Transaction created successfully

application/json

Schema

Schema

idstringrequired
Unique Identifier of the Transaction. Format: Transaction + - + <UUID>
Example: Transaction-5f391daa-80a8-4292-96d9-3fdc1a12192b
customerAccountIdstringrequired
Customer Account ID - A unique identifier provided by the integrating merchant.
Possible values: <= 125 characters
Example: NewcustomerTestPy14
storedPaymentOptionReferencestringrequired
The stored payment instrument reference.
Possible values: <= 255 characters
Example: 8ac7a49f790baf4001790eb90ee26064
modificationIdstringrequired
Your unique reference for the requested transaction.
Possible values: <= 255 characters
Example: 4d875985-f9a2-4eb5-8dff-73b64c8915a7
transactionReferenceIdstringrequired
SmartPay transaction Id, could be used to call SmartPay modification APIs (e.g., refund).
Possible values: <= 255 characters
Example: aeaabe56-3c05-44fb-9f19-9f27074ef5a4
reconciliationReferenceIdstringrequired
External payment provider unique transaction identifier.
Possible values: <= 255 characters
Example: pzFdwq0ImRFYGYuq41xCH
paymentStatusstring
Status of the transaction.
Example: captured
payment objectrequired
Payment details of the Subscription created inherited from the provided plan. Please refer to Data Model for details.
descriptionstring
Description of the payment or plan.
Possible values: <= 60 characters
Example: Premium sub for only 90.99 EUR!
recurrentAmountnumber<decimal>required
Recurrent amount to charge the customer.
Possible values: <= 60 characters
Example: 90.99
currencyIsoCodestringrequired
Currency of the charges. Format ISO 4217.
Possible values: >= 3 characters and <= 3 characters
Example: EUR
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 objectnullablerequired
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
transactionLogs object[]
Array [
idstringrequired
Unique Identifier of the Transaction Log. Format: TransactionLog + - + <UUID>
Example: TransactionLog-3c2e60ea-2eb9-4162-bcb1-7034f5d4c27f
createdAtstring<date-time>required
Timestamp of when the transaction log was created.
Example: 2021-02-11T15:00:44.718Z
updatedAtstring<date-time>required
Timestamp of when the transaction log was last updated.
Example: 2021-02-11T15:00:44.718Z
statusstringrequired
Status of the transaction or retried transaction.
Example: captured
descriptionstringrequired
Description of the transaction result or retry result.
Possible values: <= 255 characters
Example: Transaction with modificationId 4d875985-f9a2-4eb5-8dff-73b64c8915a7 is updated with status captured and description MerchantExternal
]
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

Example (auto)

{
  "id": "Transaction-5f391daa-80a8-4292-96d9-3fdc1a12192b",
  "customerAccountId": "NewcustomerTestPy14",
  "storedPaymentOptionReference": "8ac7a49f790baf4001790eb90ee26064",
  "modificationId": "4d875985-f9a2-4eb5-8dff-73b64c8915a7",
  "transactionReferenceId": "aeaabe56-3c05-44fb-9f19-9f27074ef5a4",
  "reconciliationReferenceId": "pzFdwq0ImRFYGYuq41xCH",
  "paymentStatus": "captured",
  "payment": {
    "description": "MerchantExternal",
    "amount": 10,
    "currencyIsoCode": "EUR"
  },
  "billingAddress": {
    "addressLine1": "Leopoldstrasse",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE"
  },
  "shippingAddress": {
    "addressLine1": "Leopoldstrasse",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE"
  },
  "consumer": {
    "firstName": "FirstName1",
    "lastName": "LastName1",
    "middleName": ".",
    "emailAddress": "NewcustomerTestPy14@mail.com",
    "title": "Mr",
    "culture": "en-en",
    "dateOfBirth": "1995-01-26",
    "gender": "M",
    "mobilePhone": "1234567890",
    "homePhone": "1234567891",
    "workPhone": "1234567892"
  },
  "transactionLogs": [
    {
      "id": "TransactionLog-bf55539a-fc69-410a-a684-99b2fb06bfb2",
      "createdAt": "2021-06-17T12:46:33.99Z",
      "updatedAt": "2021-06-17T12:46:33.99Z",
      "status": "captured",
      "description": "Transaction with modificationId 4d875985-f9a2-4eb5-8dff-73b64c8915a7 is updated with status captured and description MerchantExternal"
    }
  ],
  "customReferences": {
    "custom1": "custom1 test1",
    "custom2": "custom1 test2",
    "custom3": null
  }
}

Example

{
  "id": "Transaction-60b8fe39-1c71-40e8-b2b8-d2ae4b5d9c20",
  "customerAccountId": "NewcustomerTestPSerie00",
  "storedPaymentOptionReference": "8ac7a49f79ea7b760179eaae946a4ff7",
  "modificationId": "e6b98627-e7eb-4a41-ae32-540f2e22d309",
  "transactionReferenceId": "aeaabe56-3c05-44fb-9f19-9f27074ef5a4",
  "reconciliationReferenceId": "pzFdwq0ImRFYGYuq41xCH",
  "paymentStatus": "captured",
  "payment": {
    "description": "OrderId0010",
    "amount": 7.3,
    "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
  },
  "customReferences": {
    "custom1": "custom1 test1",
    "custom2": "custom1 test2",
    "custom3": null
  },
  "transactionLogs": [
    {
      "id": "TransactionLog-00601b47-1322-48b3-9772-c70cad35d086",
      "createdAt": "2021-06-22T16:32:42.39Z",
      "updatedAt": "2021-06-22T16:32:42.39Z",
      "status": "captured",
      "description": "Transaction with modificationId: e6b98627-e7eb-4a41-ae32-540f2e22d309 is updated with status captured and description: OrderId0010"
    }
  ]
}

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