secuconnect logo
API docs by Redocly

Secuconnect API (2.0.0)

Download OpenAPI specification:

General Merchants

Contains all settings that are universally valid for the merchant. One merchant can have multiple contracts, and multiple stores.

Find General Merchants

Returns the General Merchants matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 23,
  • "data": [
    ]
}

Read General Merchant

Returns the specified General Merchant.

Authorizations:
oauth_token
path Parameters
generalMerchantId
required
string

General Merchant ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "general.merchants",
  • "id": "MRC_1HVSZKD4LQ44D9AUX2JZ6S1OPS3G9B",
  • "id_old": 2332534,
  • "user": {
    },
  • "type": 46,
  • "store_name": null,
  • "parent": {
    }
}

Update General Merchant

Updates the specified General Merchant with the given data.

Authorizations:
oauth_token
path Parameters
generalMerchantId
required
string

General Merchant ID

Request Body schema: application/json

Merchant details

Array of objects or null (GeneralMerchantsLegalDetailsDTO)

Legal details like terms of use, privacy policy, or imprint

Array of objects or null (GeneralMerchantsUrls)

Return URLs

Responses

Request samples

Content type
application/json
{
  • "legal_details": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "general.merchants",
  • "id": "MRC_1HVSZKD4LQ44D9AUX2JZ6S1OPS3G9B",
  • "id_old": 2332534,
  • "user": {
    },
  • "type": 46,
  • "store_name": null,
  • "parent": {
    },
  • "legal_details": []
}

Get public data

Returns the public data of the specified General Merchant and General Contract.

Authorizations:
oauth_token
path Parameters
generalMerchantId
required
string

General Merchant ID

generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "legal_details": null,
  • "company": {
    },
  • "merchant_urls": null,
  • "checkout_options": null
}

Get merchant categories

Returns the available merchant categories for the authenticated merchant.

Authorizations:
oauth_token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

General Contracts

Manages the contracts of a merchant, including the specific options and conditions. A merchant can have one contract, but also multiple contracts for different purposes. There are separate views on the contracts for payment (s. Payment Contracts) and e-goods (s. Prepaid Contracts).

Find General Contracts

Returns the General Contracts matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 48,
  • "data": [
    ]
}

Read General Contract

Returns the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_LG68DKRBHVBYTLVWGQM6T9YMYW2XFU",
  • "id_old": 1357999,
  • "approved": false,
  • "merchant": {
    },
  • "pay_in_advance_account": {
    },
  • "paypal_configuration": {
    },
  • "easycredit_configuration": {
    },
  • "checkout_configuration": {
    },
  • "payment_link_options": {}
}

Update General Contract

Updates the specified General Contract with the given data.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Contract details

object (CheckoutConfiguration)

General checkout settings

Responses

Request samples

Content type
application/json
{
  • "checkout_configuration": {
    }
}

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_LG68DKRBHVBYTLVWGQM6T9YMYW2XFU",
  • "id_old": 1357999,
  • "approved": false,
  • "merchant": {
    },
  • "pay_in_advance_account": {
    },
  • "paypal_configuration": {
    },
  • "easycredit_configuration": {
    },
  • "checkout_configuration": {
    },
  • "payment_link_options": {}
}

Update General Contract partially

Updates the specified General Contract with the given data.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Contract details

object (CheckoutConfiguration)

General checkout settings

Responses

Request samples

Content type
application/json
{
  • "checkout_configuration": {
    }
}

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_LG68DKRBHVBYTLVWGQM6T9YMYW2XFU",
  • "id_old": 1357999,
  • "approved": false,
  • "merchant": {
    },
  • "pay_in_advance_account": {
    },
  • "paypal_configuration": {
    },
  • "easycredit_configuration": {
    },
  • "checkout_configuration": {
    },
  • "payment_link_options": {}
}

Get balance from bank transfer

Returns the balance eligible for payouts resulting from bank transfers for each currency of the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string <id> (ObjectId)
Example: OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "id": "GCR_LG68DKRBHVBYTLVWGQM6T9YMYW2XFU",
  • "balances": [
    ]
}

Get available payment methods for Smart Transaction

Returns the payment methods, available for the specified General Contract and Smart Transactions. It considers currency and demo mode from the response header, and other data from the Smart Transaction.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

smartTransactionId
required
string

Smart Transaction ID

Request Body schema: application/json

Request details

currency
required
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

is_demo
required
boolean

Demo mode. Such transactions are not actually processed.

apiv2_products
boolean or null

If TRUE, the response will use the flex.API/APIv2 product names, and the other parameters will be ignored.

Responses

Request samples

Content type
application/json
{
  • "is_demo": true,
  • "currency": "EUR"
}

Response samples

Content type
application/json
[
  • "Creditcard",
  • "Debit",
  • "easyCredit",
  • "eps",
  • "Invoice",
  • "Paypal",
  • "Prepay",
  • "Sofort",
  • "Applepay",
  • "Googlepay"
]

Get third party configuration

Returns the configuration for third parties, e. g. PayPal.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Set third party configuration

Sets the configuration for third parties, e. g. PayPal.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Third party configuration

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

Responses

Request samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Response samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Update third party configuration

Updates the configuration for third parties, e. g. PayPal.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Third party configuration

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

Responses

Request samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Response samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Update third party configuration partially

Updates the configuration for third parties, e. g. PayPal, partially.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Third party configuration

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

object or null (ThirdPartyEnvironmentDTO)

Third-Party environment settings

Responses

Request samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Response samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Delete third party configuration

Deletes one or all third party configurations for the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

thirdPartyName
required
string or null
Default: null
Example: paypal

Third party name:

  • "paypal"
  • "easycredit"
  • "saferpay"

Responses

Response samples

Content type
application/json
{
  • "paypal": {
    },
  • "easycredit": {
    },
  • "saferpay": {
    }
}

Get payment methods

Returns the payment methods, available for the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Request details

currency
required
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

is_demo
required
boolean

Demo mode. Such transactions are not actually processed.

apiv2_products
boolean or null

If TRUE, the response will use the flex.API/APIv2 product names, and the other parameters will be ignored.

Responses

Request samples

Content type
application/json
{
  • "is_demo": true,
  • "currency": "EUR"
}

Response samples

Content type
application/json
[
  • "Creditcard",
  • "Debit",
  • "easyCredit",
  • "eps",
  • "Invoice",
  • "Paypal",
  • "Prepay",
  • "Sofort",
  • "Applepay",
  • "Googlepay"
]

Revoke all accruals

Revokes the accrual flags for all transactions of the specified General Contract. Thus all these transactions are executed then.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "error": "ProductUnauthorizedException",
  • "error_details": "Invalid token",
  • "error_user": "ungültiger Token",
  • "code": 0,
  • "supportId": "s4l2y7oyr10p7wjtg8o6gnq2esly6r3v"
}

Terminate contract

Terminates the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "result": true
}

Set Payment Link configuration

Saves the configuration for Payment Link, the payment page, for the specified General Contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Payment Link configuration

object (BackgroundImageOption)

BackgroundImageOption

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_LG68DKRBHVBYTLVWGQM6T9YMYW2XFU",
  • "id_old": 1357999,
  • "approved": false,
  • "merchant": {
    },
  • "pay_in_advance_account": {
    },
  • "paypal_configuration": {
    },
  • "easycredit_configuration": {
    },
  • "checkout_configuration": {
    },
  • "payment_link_options": {}
}

Get iframe options

Returns the options for the payment iframe for the given contract. The payment iframe was based on the obsolete Flex.API.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
{
  • "payment_hint_title": null,
  • "project_title": null,
  • "project_logo": null,
  • "submit_button_title": null,
  • "primary_colour": null,
  • "language": "de_DE",
  • "basket_title": null,
  • "is_basket_shown": true,
  • "language_formality": "formal",
  • "payment_config": {
    }
}

Get currencies

Returns the payment methods, available for the given contract.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Responses

Response samples

Content type
application/json
[
  • "EUR",
  • "CHF"
]

Update bank account

Changes the bank account, that is used for payouts.

Authorizations:
oauth_token
path Parameters
generalContractId
required
string

General Contract ID

Request Body schema: application/json

Bank details

iban
string

International Bank Account Number (IBAN)

bic
string

Bank Identifier Code (BIC)

owner
string

Account owner name (personal name or company name)

bankname
string or null

Bank name

verification_document
string or null
Default: null

Document Uploads ID of verification document

Responses

Request samples

Content type
application/json
{
  • "iban": "DE02120300000000202051",
  • "bic": "BYLADEM1001",
  • "owner": "Max Mustermann",
  • "bankname": "Deutsche Kreditbank Berlin",
  • "verification_document": "DUP_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH"
}

Response samples

Content type
application/json
{
  • "result": true
}

General Stores

The stores of a merchant. Smart ZVT devices are assigned to stores. And Click & Collect arrangements are for specific stores.

Find General Stores

Returns the General Stores matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "data": [
    ]
}

Create General Store

Creates a new General Store from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Store details

name
string

Name

merchant
string

General Merchant ID

object (Address)

Postal address

facebook_id
string

New facebook ID

phone
string

New phone number

url_website
string

New URL to general store website

photo_main
string

New main photo

photo
Array of strings

New photos

Array of objects (OpenHours)

Opening hours per weekday

Responses

Request samples

Content type
application/json
{
  • "name": "Musterstadt Muster-Centerg",
  • "merchant": "MRC_KLMDFHSWEYQ938WPCJHGF3D74XUMNI",
  • "address": {
    },
  • "phone": "+49 555 5555555"
}

Response samples

Content type
application/json
{
  • "object": "general.stores",
  • "id": "STO_G6ZOIFP46V02KUJBPDTKK008VIK4QH",
  • "id_old": 1046176,
  • "store_name": null,
  • "merchant": {
    },
  • "acceptance_point": false,
  • "name": "Musterstadt Muster-Center",
  • "name_raw": "Musterstadt Muster-Center",
  • "facebook_id": "",
  • "has_beacon": false,
  • "open_hours": [
    ],
  • "open_now": true,
  • "open_time": 321,
  • "phone_number_formatted": "",
  • "url_website": "https://www.example.com/stores/musterstadt-mustercenter"
}

Read General Store

Returns the specified General Store.

Authorizations:
oauth_token
path Parameters
generalStoreId
required
string

General Store ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "general.stores",
  • "id": "STO_G6ZOIFP46V02KUJBPDTKK008VIK4QH",
  • "id_old": 1046176,
  • "store_name": null,
  • "merchant": {
    },
  • "acceptance_point": false,
  • "name": "Musterstadt Muster-Center",
  • "name_raw": "Musterstadt Muster-Center",
  • "facebook_id": "",
  • "has_beacon": false,
  • "open_hours": [
    ],
  • "open_now": true,
  • "open_time": 321,
  • "phone_number_formatted": "",
  • "url_website": "https://www.example.com/stores/musterstadt-mustercenter"
}

Update General Store

Updates the specified General Store with the given data.

Authorizations:
oauth_token
path Parameters
generalStoreId
required
string

General Store ID

Request Body schema: application/json

Store details

name
string

Name

merchant
string

General Merchant ID

object (Address)

Postal address

facebook_id
string

New facebook ID

phone
string

New phone number

url_website
string

New URL to general store website

photo_main
string

New main photo

photo
Array of strings

New photos

Array of objects (OpenHours)

Opening hours per weekday

Responses

Request samples

Content type
application/json
{
  • "name": "Musterstadt Muster-Center"
}

Response samples

Content type
application/json
{
  • "object": "general.stores",
  • "id": "STO_G6ZOIFP46V02KUJBPDTKK008VIK4QH",
  • "id_old": 1046176,
  • "store_name": null,
  • "merchant": {
    },
  • "acceptance_point": false,
  • "name": "Musterstadt Muster-Center",
  • "name_raw": "Musterstadt Muster-Center",
  • "facebook_id": "",
  • "has_beacon": false,
  • "open_hours": [
    ],
  • "open_now": true,
  • "open_time": 321,
  • "phone_number_formatted": "",
  • "url_website": "https://www.example.com/stores/musterstadt-mustercenter"
}

Make default store

Makes the specified General Store the default store of its General Merchant.

Authorizations:
oauth_token
path Parameters
generalStoreId
required
string

General store id

Request Body schema: application/json

Short reason note

reason
string

Reason

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "result": true
}

Smart Transactions

In difference to a Payment Transaction, a Smart Transaction covers a wider range of use cases. It is also more connected to the business case than to the many details of the payment process. And it is the basis for Smart Checkout and Payment Link.

Smart Transactions can be used for e-commerce and cross channel scenarios, to integrate customer loyalty programmes at the POS, etc., etc. It is not predetermined to a specific payment method, and will manage the Payment Transaction for you.

Create Smart Transaction

Creates a new Smart Transaction from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Transaction details

merchant
string

Merchant

object (ProductInstanceUID)

Object type and ID

transactionRef
string

Purpose for bank statement; would usually contain shop name and order number or date

merchantRef
string

Merchant reference for secuOffice; usually shop order number or ID

object (SmartTransactionsBasket)

Basket items, several sub-baskets or subscription details

object (SmartTransactionsBasketInfo)

Basket information

Array of objects (SmartTransactionsIdent)

secucard customer card or voucher, or request to create it

tax_amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

tax_rate
integer (TaxRate)

Tax rate in percent

market
string

Market

cashier
string

Cashier

product
string

Product

object (ProductInstanceUID)

Object type and ID

trans_id
integer

Transaction ID (TA code)

object (ProductInstanceID)

Object ID

last_visited_page
string

Last visited page

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentContainerDTO)

Payment instrument

object (SmartTransactionsCheckin)

Check-in

is_demo
boolean

Whether the transaction is in demo mode (payment not executed)

intent
string

Intent:

  • "sale"
  • "order"
object (SmartTransactionsCheckoutLinks)

Checkout URLs

object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

object (SmartTransactionsCommunication)

Send an email with execution of the Smart Transaction; loyalty card only

object (SmartTransactionsApplicationContext)

Controls the integration between Smart Checkout and the shop.

object (PaymentContext)

Controls some payment details

Responses

Request samples

Content type
application/json
Example
{
  • "is_demo": true,
  • "contract": {
    },
  • "customer": {
    },
  • "basket_info": {
    },
  • "application_context": {
    }
}

Response samples

Content type
application/json
Example
{}

Find Smart Transactions

Returns the Smart Transactions matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{}

Read Smart Transaction

Returns the specified Smart Transaction.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
Example
{}

Update Smart Transaction

Updates the specified Smart Transaction with the given data. It can only be updated before the payment is executed with POST /Smart/Transactions/{id}/start[/{method}], or with POST /Smart/Transactions/{id}/prepare/{method} in combination with auto_capture.

You must always pass basket and basket_info. Otherwise basket is removed, and basket info is set to the defaults.

Some data can not be changed after creation, f. e. application_context.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

Request Body schema: application/json

Transaction details

merchant
string

Merchant

object (ProductInstanceUID)

Object type and ID

transactionRef
string

Purpose for bank statement; would usually contain shop name and order number or date

merchantRef
string

Merchant reference for secuOffice; usually shop order number or ID

object (SmartTransactionsBasket)

Basket items, several sub-baskets or subscription details

object (SmartTransactionsBasketInfo)

Basket information

Array of objects (SmartTransactionsIdent)

secucard customer card or voucher, or request to create it

tax_amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

tax_rate
integer (TaxRate)

Tax rate in percent

market
string

Market

cashier
string

Cashier

product
string

Product

object (ProductInstanceUID)

Object type and ID

trans_id
integer

Transaction ID (TA code)

object (ProductInstanceID)

Object ID

last_visited_page
string

Last visited page

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentContainerDTO)

Payment instrument

object (SmartTransactionsCheckin)

Check-in

is_demo
boolean

Whether the transaction is in demo mode (payment not executed)

intent
string

Intent:

  • "sale"
  • "order"
object (SmartTransactionsCheckoutLinks)

Checkout URLs

object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

object (SmartTransactionsCommunication)

Send an email with execution of the Smart Transaction; loyalty card only

object (SmartTransactionsApplicationContext)

Controls the integration between Smart Checkout and the shop.

object (PaymentContext)

Controls some payment details

Responses

Request samples

Content type
application/json
Example
{
  • "is_demo": true,
  • "contract": {
    },
  • "customer": {
    },
  • "transactionRef": "Bestellnr. 20000345 bei Example.com",
  • "merchantRef": "20000345",
  • "basket_info": {
    }
}

Response samples

Content type
application/json
Example
{}

Apply secucard (“pre-transaction”)

Checks the balance of the secucard Merchant Card in ident. If there is cash or bonus balance that can be applied, it adds bonus items to the basket and sets missing_sum inside basket_info.

Note: In contrast to other operations it doesn't return the full object.

In order to pay, you need to call one of the endpoints:

  • /start/loyalty if there is no missing sum;
  • /start/cash if the remainder is paid at the cash register (ECR) without our terminals;
  • /start/cashless if the remainder is paid at the ECR with one of our terminals;
  • /prepare/debit and /start if the remainder is paid with SEPA direct debit;
  • /prepare/creditcard and /start if the remainder is paid with credit card.
Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

Responses

Response samples

Content type
application/json
{
  • "missing_sum": 576,
  • "bonus_products": [
    ]
}

Authorize payment (”prepare”)

Create the Payment Transaction and links it to the Smart Transaction. If required, a scoring is performed. When auto_capture is set on true it will also start the Smart Transaction and execute the payment.

You can pass the payment data or the ID of an existing Payment Container. Likewise, you can also pass the customer details or the ID of an existing Payment Customer. If not passed, it is expected these details have been set before.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

paymentMethod
required
string
Example: creditcard

Payment method:

  • "creditcard" (also for Google Pay and Apple Pay)
  • "debit"
  • "eps" (deprecated)
  • "easycredit"
  • "giropay" (deprecated)
  • "invoice"
  • "paypal"
  • "prepaid"
  • "sofort" (deprecated)
Request Body schema: application/json

Optional customer and/or payment details

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentContainerDTO)

Payment instrument

object (SmartTransactionsPrepareCallbackUrls)

Return URLs for external payment authorization.

Note: Please don't mix them up with the return URLs for Smart Checkout. These here are intended for custom checkout implementations to catch the user when he returns from 3-D Secure, PayPal, Sofort, and the like.

object (SmartTransactionsPrepareDynamicDescriptor)

Dynamic Descriptor to allow the cardholder to recognize the business name and city on their card or bank statement.

email
string

Email address

Responses

Request samples

Content type
application/json
Example
{
  • "container": {
    },
  • "callback_urls": {}
}

Response samples

Content type
application/json
Example
{}

Capture payment (“start”)

Starts the Smart Transaction and captures the payment.

You can either pass the payment method and start it directly, or you can authorize it before with a call to POST /Smart/Transactions/{id}/prepare/{method}. You must call /prepare, if an external authorization might be needed (credit card 3-D Secure, PayPal, Sofort, etc.).

You can save the call to /start when you use /prepare in combination with auto_capture. This will automatically start the Smart Transaction after the payment has been authorised.

In case of direct debit, you can either pass the payment data or the ID of an existing Payment Container.

Likewise you can pass the customer details or the ID of an existing Payment Customer. If not passed, it expects these details to be set before.

If started with method "cash", it only tracks the ECR payment so that loyalty operations can be applied.

Type "cashless" is blocking, and starts a card payment at the payment terminal attached with SmartZVT.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

paymentMethod
required
string
Example: prepaid

Payment method, if not in succession to /prepare:

  • "cash"
  • "cashless"
  • "debit"
  • "invoice"
  • "loyalty"
  • "prepaid"
  • "cashless_direct"
  • "ccload"
Request Body schema: application/json

Optional customer and/or payment details

object (SmartTransactionPaymentCustomerDTO)

Customer details

object (SmartTransactionPaymentContainerDTO)

Payment instrument

object (SmartTransactionsPrepareCallbackUrls)

Return URLs for external payment authorization.

Note: Please don't mix them up with the return URLs for Smart Checkout. These here are intended for custom checkout implementations to catch the user when he returns from 3-D Secure, PayPal, Sofort, and the like.

object (SmartTransactionsPrepareDynamicDescriptor)

Dynamic Descriptor to allow the cardholder to recognize the business name and city on their card or bank statement.

email
string

Email address

tid
string

Terminal ID Number (TID), required for 'cashless_direct' method

trace
integer

Trace number from the card processing response, required for 'cashless_direct' method

cardtype
string

Card Type ('visa', 'mastercard', 'mastercard_debit', 'maestro', 'vpay' or 'girocard'), required for 'cashless_direct' method

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
Example
{
  • "object": "smart.transactions",
  • "id": "STX_27WNVTS2K2P6CRMGHV58RNZ7GTBXA4",
  • "merchant": {
    },
  • "contract": {
    },
  • "customer": {
    },
  • "container": {
    },
  • "transactions": [
    ],
  • "created": "2023-08-04T13:14:41+02:00",
  • "updated": "2023-08-04T13:14:45+02:00",
  • "status": "ok",
  • "transactionRef": "Bestellnr. 20000345 bei Example.com",
  • "merchantRef": "20000345",
  • "intent": "sale",
  • "basket_info": {
    },
  • "payment_method": "creditcard",
  • "trans_id": 73323994,
  • "is_demo": true,
  • "application_context": {},
  • "payment_context": {
    }
}

Set delivery

Adds shipping information, and marks the Payment Transaction as shipped when called the first time.

Note: This is obligatory for purchase on account, because otherwise it is not known that and when the invoice is due.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

Request Body schema: application/json

Shipping information

object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

Responses

Request samples

Content type
application/json
{
  • "delivery_options": {
    }
}

Response samples

Content type
application/json
{
  • "object": "smart.transactions",
  • "id": "STX_3R64KEXM02P6CRXPSHGS7ZFA0SX3A4",
  • "merchant": {
    },
  • "contract": {
    },
  • "customer": {
    },
  • "transactions": [
    ],
  • "created": "2023-08-04T13:17:07+02:00",
  • "updated": "2023-08-07T09:35:52+02:00",
  • "status": "ok",
  • "transactionRef": "Bestellnr. 20000345 bei Example.com",
  • "merchantRef": "20000345",
  • "intent": "sale",
  • "basket_info": {
    },
  • "payment_method": "invoice",
  • "payment_instructions": {},
  • "trans_id": 73323996,
  • "is_demo": true,
  • "application_context": {},
  • "payment_context": {
    },
  • "delivery_options": {
    }
}

Abort order

Abandons a Smart Transaction that has not yet been started.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_3ZA5YGRB82P6A42QM84N0P9YG0Y7A4

Smart Transaction ID

Responses

Response samples

Content type
application/json
{}

Cancel payment

Cancels the Smart Transaction.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_2ZVEFT7YV2P6BNCP8QNQ66N4GEA0AK

Smart Transaction ID

Responses

Response samples

Content type
application/json
{}

Cancel cash transaction

Cancels the terminal-induced "cash" transaction with the given receipt number.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: 3

Receipt number

Responses

Response samples

Content type
application/json
{
  • "object": "smart.transactions",
  • "id": "STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ",
  • "merchant": {
    },
  • "contract": {
    },
  • "customer": {
    },
  • "transactions": [ ],
  • "created": "2023-08-04T13:22:56+02:00",
  • "updated": "2023-08-07T09:53:18+02:00",
  • "status": "cancelled",
  • "transactionRef": "Bestellnr. 20000345 bei Example.com",
  • "merchantRef": "20000345",
  • "intent": "sale",
  • "basket": {
    },
  • "basket_info": {
    },
  • "payment_method": "cash",
  • "trans_id": 55679607,
  • "is_demo": true,
  • "receipt_number": 3,
  • "payment_context": {
    }
}

Update payment container for subscription

Requests new authorization for a subscription.

The Payment Container for a subscription may have become unusable. For instance may the customer have returned their card or changed their bank account.

The returned Smart Transaction is to be used like after a call to /prepare. There are URLs inside payment_links to authorize for credit card, SEPA direct debit or with PayPal.

Authorizations:
oauth_token
path Parameters
subscriptionId
required
string

Subscription ID

Responses

Response samples

Content type
application/json
{}

Terminal end-of-day report

Runs the end of day report on the POS payment terminal. This operation is usually called by SDKs from the electronic cash register (ECR).

This request is blocking. Secuconnect API only answers after the payment terminal has finished the end-of-day report.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string
Example: me

Smart Device ID

Responses

Response samples

Content type
application/json
{
  • "object": "smart.transactions",
  • "id": "STX_2PR98002A2X6WVHJC12VHAGQ05N2A4",
  • "merchant": {
    },
  • "device_source": {
    },
  • "created": "2021-06-10T13:49:58+02:00",
  • "updated": "2021-06-10T13:50:30+02:00",
  • "status": "ok",
  • "receipt": [
    ]
}

Terminal diagnosis

Runs the diagnosis process on the POS payment terminal (PT). This operation is usually called by SDKs from the electronic cash register (ECR).

This request is blocking. Secuconnect API only answers after the payment terminal has finished the end-of-day report.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string
Example: me

Smart Device ID

Responses

Response samples

Content type
application/json
{
  • "object": "smart.transactions",
  • "id": "STX_3462KF9P12X2BCHTD3H588YVNG34AH",
  • "merchant": {
    },
  • "device_source": {
    },
  • "created": "2021-03-12T13:54:18+01:00",
  • "updated": "2021-03-12T13:54:33+01:00",
  • "status": "ok",
  • "receipt": [
    ]
}

Payment Transactions

Payment Transactions control the actual payment. When you work with Smart Transactions, the needed Payment Transaction is created in the background when calling POST /Smart/Transactions/{id}/prepare or POST /Smart/Transactions/{id}/start. There are also additional Payment Transactions for things like stakeholder payments, refunds, and the like. These are linked with the original Payment Transaction.

Find Payment Transactions

Returns the Payment Transactions matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 13264,
  • "data": [
    ]
}

Create TWINT Payment

Creates a new Payment Transaction from the given data for TWINT.

Authorizations:
oauth_token
Request Body schema: application/json

Transaction details

amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

purpose
string

The purpose of the payment, for the account statement for example.

payment_methods
Array of strings or null

Payment methods.

  • "twint"
order_id
string

Your order number. If set for the contract, there must be a unique number for each payment.

Array of objects (SecupayBasketItem)

Basket items, several sub-baskets or subscription details

accrual
boolean

Locks for payout, if set on true. Needed f.e. for crowd funding or crowd investment.

payment_action
string

Specifies whether to authorize only ("authorization"), or to pay immediately ("sale"). The capture of the pre-authorized payment is made with a call to /capture.

object (PaymentCustomersProductModel)
Default: {}

Customer details

object (SecupayRedirectUrl)

SecupayRedirectUrl

contract
string

Contract ID

container
string

Container ID

object

Options for customizing the checkout page

object (SecupayTransactionProductDTOSubscription)

Recurring payments

demo
boolean

Demo mode

object

Customer experience score

Responses

Request samples

Content type
application/json
{
  • "demo": false,
  • "contract_id": "GCR_HGEZ958JZWVKLEBUNYV87TTLXHFDEA",
  • "customer": {
    },
  • "amount": 1995,
  • "currency": "CHF",
  • "purpose": "Kauf bei Example.com",
  • "payment_methods": [
    ],
  • "redirect_url": {}
}

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "gqaymbtaduzc7420193",
  • "trans_id": 71734972,
  • "payment_id": "PCI_W5SNC4GVPHXX0KC4NPZYA95XN6ZBNZ",
  • "status": "internal_server_status",
  • "amount": 1995,
  • "currency": "CHF",
  • "purpose": "Kauf bei Example.com",
  • "transaction_status": 1,
  • "accrual": false,
  • "customer": {
    },
  • "redirect_url": {},
  • "iframe_url": "https://test.saferpay.com/vt2/api/PaymentPage/251852"
}

Read Payment Transaction

Returns the specified Payment Transaction.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.transactions",
  • "id": "PCI_23XAR0HTRVA2ZM0STUB0J248W0U9MG",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [
    ],
  • "trans_id": 119879108,
  • "product_id": 16,
  • "product": "Direct debit",
  • "product_raw": "Zahlungsgarantie Lastschrift",
  • "zahlungsmittel_id": 1796483,
  • "contract_id": 81698,
  • "amount": 13000,
  • "currency": "EUR",
  • "created": "2023-06-29T16:50:47+02:00",
  • "completion_date": "2023-06-29T16:50:48+02:00",
  • "updated": "2023-06-29T16:59:57+02:00",
  • "description": "Bestellung am 29.06.2023 via secupay bei Secupay Test-Shop (264748)",
  • "description_raw": "Bestellung am 29.06.2023 via secupay bei Secupay Test-Shop (264748)",
  • "status": 6,
  • "status_text": "abgeschlossen",
  • "details": {
    },
  • "customer": {
    },
  • "payment_data": "DE37 XXXX XXXX XXXX XX05 24",
  • "transaction_hash": "bxxdkdlcexgt10709743",
  • "accrual": false,
  • "order_id": "50001234"
}

Capture

Captures an authorised invoice Payment Transaction.

Note: For invoice payment, this must be invoked. Otherwise it is not known that and when the invoice becomes due.

Note: This works only for authorised invoice payment transactions. The transaction must have status 85 as a pre-condition.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Request Body schema: application/json
amount
integer

Optional parameter for MoTo Transactions to capture a new amount which has to be equal or less than the authorized amount of the transaction.

object (SecupayTransactionSetShippingInformationDTO)

Shipping information (incl. invoice number and order ID)

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_3JSVHBEBA3XNCP6Y46BZX248W25BM7",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [ ],
  • "trans_id": 110111567,
  • "product_id": 329,
  • "product": "Kauf auf Rechnung (Demo)",
  • "product_raw": "Kauf auf Rechnung (Demo)",
  • "zahlungsmittel_id": 0,
  • "contract_id": 49760,
  • "amount": 1250,
  • "currency": "EUR",
  • "created": "2023-07-12T09:41:47+02:00",
  • "updated": "2023-07-12T09:42:11+02:00",
  • "completion_date": "2024-12-04T00:00:00+01:00",
  • "description": "Bestellung am 12.07.2023 via secupay bei Musterfirma GmbH (264748)",
  • "description_raw": "Bestellung am 12.07.2023 via secupay bei Musterfirma GmbH (264748)",
  • "status": 86,
  • "status_text": "abgeschlossen (Rechnung offen)",
  • "details": {
    },
  • "customer": {
    },
  • "transaction_hash": "vyemyhtuqvun11132775",
  • "accrual": false,
  • "order_id": "ORD-12345"
}

Cancel or refund

Cancels or refunds the payment in full or in part.

Note: It is not possible to exceed the original amount.

If the payer has already made the payment, it creates a new Payment Transaction for the refund, and links it to the original one. The amount of the original Payment Transaction then remains unchanged.

If the payment was not made yet, the amount is reduced (partial cancellation) or the status is set to cancelled (full cancellation). There will be no additional Payment Transaction.

The amount still in effect can be read with GET /Payment/Transactions/{id}/checkStatus.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Request Body schema: application/json

Amount and reason

reason
string <[0-9a-zA-Z .,+\-:?()\/\']+>

The reason of this cancel or refund

amount
integer
Deprecated

Amount in smallest currency unit (e. g. Euro Cent)

reduce_amount_by
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

reduce_stakeholder_payment
boolean
Default: false

Only for the mixed basket. Reduces stakeholder shares proportionately.

container_id
string

Payment Container ID

Responses

Request samples

Content type
application/json
{
  • "reduce_amount_by": 1000,
  • "reason": "Nachlass fuer kleinen Fleck"
}

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_23XAR0HTRVA2ZM0STUB0J248W0U9MG",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [
    ],
  • "trans_id": 119879108,
  • "product_id": 16,
  • "product": "Direct debit",
  • "product_raw": "Zahlungsgarantie Lastschrift",
  • "zahlungsmittel_id": 1796483,
  • "contract_id": 81698,
  • "amount": 13000,
  • "currency": "EUR",
  • "created": "2023-06-29T16:50:47+02:00",
  • "completion_date": "2023-06-29T16:50:48+02:00",
  • "updated": "2023-06-29T16:59:57+02:00",
  • "description": "Bestellung am 29.06.2023 via secupay bei Secupay Test-Shop (264748)",
  • "description_raw": "Bestellung am 29.06.2023 via secupay bei Secupay Test-Shop (264748)",
  • "status": 6,
  • "status_text": "abgeschlossen",
  • "details": {
    },
  • "customer": {
    },
  • "payment_data": "DE37 XXXX XXXX XXXX XX05 24",
  • "transaction_hash": "bxxdkdlcexgt10709743",
  • "accrual": false,
  • "order_id": "50001234"
}

Revoke accrual

Revokes the accrual flag of a Payment Transaction. This flag withholds the actual execution of the payment. The payment will now be made if it has not already been made.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Responses

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_3JSVHBEBA3XNCP6Y46BZX248W25BM7",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [ ],
  • "trans_id": 110111567,
  • "product_id": 329,
  • "product": "Kauf auf Rechnung (Demo)",
  • "product_raw": "Kauf auf Rechnung (Demo)",
  • "zahlungsmittel_id": 0,
  • "contract_id": 49760,
  • "amount": 1250,
  • "currency": "EUR",
  • "created": "2023-07-12T09:41:47+02:00",
  • "updated": "2023-07-12T09:42:11+02:00",
  • "description": "Bestellung am 12.07.2023 via secupay bei Musterfirma GmbH (264748)",
  • "description_raw": "Bestellung am 12.07.2023 via secupay bei Musterfirma GmbH (264748)",
  • "status": 85,
  • "status_text": "Kauf auf Rechnung genehmigt",
  • "details": {
    },
  • "customer": {
    },
  • "transaction_hash": "bxxdkdlcexgt10709743",
  • "accrual": false
}

Get payment instructions for Payment Transaction

POST Payment/Transactions/{paymentTransactionId}/getPaymentInstructions

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Responses

Response samples

Content type
application/json
{
  • "lang": "de_DE",
  • "amount": "140,00",
  • "currency": "EUR",
  • "payment_instructions": {
    }
}

Get payment instructions for Smart Transaction

POST Payment/Transactions/me/getPaymentInstructions/{smartTransactionId}

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string

Smart Transaction ID

Responses

Response samples

Content type
application/json
{
  • "lang": "de_DE",
  • "amount": "140,00",
  • "currency": "EUR",
  • "payment_instructions": {
    }
}

Read in old format

Returns the specified Payment Transaction in old format.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID (PCI_...) or Flex.API transaction hash

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.transactions",
  • "id": "gqaymbtaduzc7420193",
  • "trans_id": 71734972,
  • "payment_id": "PCI_W5SNC4GVPHXX0KC4NPZYA95XN6ZBNZ",
  • "status": "internal_server_status",
  • "amount": 1995,
  • "currency": "EUR",
  • "purpose": "Kauf bei Example.com",
  • "transaction_status": 1,
  • "accrual": false,
  • "payment_action": "sale",
  • "customer": {
    },
  • "redirect_url": {},
  • "iframe_url": "https://api-testing.secupay-ag.de/payment/gqaymbtaduzc7420193"
}

Crowd funding data

Returns a crowd funding summary for the given merchant. It contains the transaction amounts, counts and payout data for each payment method ("product").

Authorizations:
oauth_token
path Parameters
generalMerchantId
required
string
Example: MRC_LTV1LATRBD58BGUMMN2HTA1S8G17P9

General Merchant ID (MRC_...)

Responses

Response samples

Content type
application/json
{
  • "project": {
    },
  • "deposited_amount": 544000,
  • "paid_out": 590000,
  • "deducted_amount": 46000,
  • "open": {
    }
}

Add shipping information

Adds shipping information.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID (PCI_...) or Flex.API transaction hash

Request Body schema: application/json

Shipping information

carrier
string

Shipping provider name

tracking_id
string

Tracking code

invoice_number
string

Merchant's invoice number

shipped_at
string

Shipping date and time, if not in the very moment; ISO 8601 date and time including timezone, like "2023-02-28T10:55:27+02:00"

order_id
string

Merchant's order number

Responses

Request samples

Content type
application/json
Example
{
  • "carrier": "ACME Parcel, Inc.",
  • "tracking_id": "a12bc345d67ef8g90"
}

Response samples

Content type
application/json
{
  • "result": true
}

Assign payment

Assign incoming payment to Payment Transaction

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

accountingId
required
integer

Accounting ID

Responses

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_JWF8YC9HC5TAD9603J4SPT5Q7E48NW",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [ ],
  • "trans_id": 74771101,
  • "product_id": 36,
  • "product": "Payment in advance",
  • "product_raw": "Vorkasse",
  • "zahlungsmittel_id": 0,
  • "contract_id": 49760,
  • "amount": 14000,
  • "currency": "EUR",
  • "created": "2023-08-31T08:41:23+02:00",
  • "updated": "2023-08-31T08:41:43+02:00",
  • "description": "Bestellung am 31.08.2023 via secupay bei Secupay Test-Shop (264748)",
  • "description_raw": "Bestellung am 31.08.2023 via secupay bei Secupay Test-Shop (264748)",
  • "status": 25,
  • "status_text": "Vorkasse wartend",
  • "details": {
    },
  • "customer": {
    },
  • "transaction_hash": "jrxctjrwwxqz7644869",
  • "accrual": false,
  • "order_id": "50002345"
}

Increase amount

Increases the amount of the given Payment Transaction. Currently, this only works for prepayment, and only before the payment has been received by secupay.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Request Body schema: application/json

increase amount input params

amount
integer

New amount of the transaction, in the smallest currency unit (e. g. Euro Cent)

Responses

Request samples

Content type
application/json
{
  • "amount": 14000
}

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_JWF8YC9HC5TAD9603J4SPT5Q7E48NW",
  • "merchant": {
    },
  • "platform": {
    },
  • "contract": {
    },
  • "related_transactions": [ ],
  • "trans_id": 74771101,
  • "product_id": 36,
  • "product": "Payment in advance",
  • "product_raw": "Vorkasse",
  • "zahlungsmittel_id": 0,
  • "contract_id": 49760,
  • "amount": 14000,
  • "currency": "EUR",
  • "created": "2023-08-31T08:41:23+02:00",
  • "updated": "2023-08-31T08:41:43+02:00",
  • "description": "Bestellung am 31.08.2023 via secupay bei Secupay Test-Shop (264748)",
  • "description_raw": "Bestellung am 31.08.2023 via secupay bei Secupay Test-Shop (264748)",
  • "status": 25,
  • "status_text": "Vorkasse wartend",
  • "details": {
    },
  • "customer": {
    },
  • "transaction_hash": "jrxctjrwwxqz7644869",
  • "accrual": false,
  • "order_id": "50002345"
}

Check payment status

Returns the current status and amount still in effect. The amount considers open and completed refunds. The amount is zero if the transaction was fully cancelled.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Responses

Response samples

Content type
application/json
{
  • "status": 9,
  • "status_text": "vorautorisiert",
  • "status_simple": 2,
  • "status_simple_text": "authorized",
  • "amount": 1995,
  • "currency": "EUR"
}

Assign transferred balance

Assigns balance to a Payment Transaction for payout. The merchant must have sent the balance by bank transfer, before it can be assigned and paid out.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Responses

Response samples

Content type
application/json
{
  • "object": "payment.transactions",
  • "id": "PCI_WM7Z28CR5CJV79EB9UWWMK5Q7E48NH",
  • "merchant": {
    },
  • "contract": {
    },
  • "related_transactions": [
    ],
  • "trans_id": 74771111,
  • "product_id": 402,
  • "product": "API initiierte Auszahlung",
  • "product_raw": "API initiierte Auszahlung",
  • "zahlungsmittel_id": 0,
  • "contract_id": 49760,
  • "amount": 94892,
  • "currency": "EUR",
  • "created": "2023-08-31T09:03:22+02:00",
  • "completion_date": "2023-08-24T00:00:00+02:00",
  • "updated": "2023-08-31T09:03:40+02:00",
  • "description": "Payout UPLOAD 2023-08-31",
  • "description_raw": "Payout UPLOAD 2023-08-31",
  • "status": 6,
  • "status_text": "abgeschlossen",
  • "details": {
    }
}

Refund bank account

Returns the bank account details for refund payments

Authorizations:
oauth_token
Request Body schema: application/json

Transaction ID

trans_id
integer

Transaction ID

Responses

Request samples

Content type
application/json
{
  • "trans_id": 55873127
}

Response samples

Content type
application/json
{
  • "trans_id": 55873127,
  • "bank_account": {
    }
}

Payment Customers

A Payment Customer holds the details of a private person or a business, including postal address and other contact details. It is used as invoice or shipping address. The Payment Customer can be created implicitly from the Smart Transaction or explicitly using POST /Payment/Customers. Payment Customers are used for payment operations, while Loyalty Customers are for customer loyalty programmes (secuaction).

Find Payment Customers

Returns the Payment Customers matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 70,
  • "data": [
    ]
}

Create Payment Customer

Creates a new Payment Customer with the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Details of the new Payment Customer

object (Contact)

Contact details

Responses

Request samples

Content type
application/json
Example
{
  • "contact": {
    }
}

Response samples

Content type
application/json
Example
{
  • "object": "payment.customers",
  • "id": "PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ",
  • "merchant": {
    },
  • "contact": {
    },
  • "created": "2023-07-11T13:20:06+02:00"
}

Read Payment Customer

Returns the specified Payment Customer.

Authorizations:
oauth_token
path Parameters
paymentCustomerId
required
string
Example: PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ

Payment Customer ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.customers",
  • "id": "PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ",
  • "merchant": {
    },
  • "contact": {
    },
  • "created": "2023-07-11T13:20:06+02:00"
}

Update Payment Customer

Updates the specified Payment Customer with the given data.

Authorizations:
oauth_token
path Parameters
paymentCustomerId
required
string
Example: PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ

Payment Customer ID

Request Body schema: application/json

Payment customer properties

object (Contact)

Contact details

Responses

Request samples

Content type
application/json
Example
{
  • "contact": {
    }
}

Response samples

Content type
application/json
Example
{
  • "object": "payment.customers",
  • "id": "PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ",
  • "merchant": {
    },
  • "contact": {
    },
  • "created": "2023-07-11T13:20:06+02:00",
  • "updated": "2023-07-11T13:21:17+02:00"
}

Delete Payment Customer

Deletes the specified Payment Customer.

Authorizations:
oauth_token
path Parameters
paymentCustomerId
required
string
Example: PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ

Payment Customer ID

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.customers",
  • "id": "PCU_3V7SC84922P5D7BJ73VCZ8S70XAMAJ",
  • "merchant": {
    },
  • "contact": {
    },
  • "created": "2023-07-11T13:20:06+02:00"
}

Payment Containers

Payment Containers hold reusable payment instruments for SEPA direct debit or for credit card payment. They can be created implicitly with POST /Smart/Transactions/{id}/prepare. Some subtypes can also be created with POST /Payment/Containers. Every Payment Container is restricted to the merchant who has created it.

Find Payment Containers

Returns the Payment Containers matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "data": [
    ]
}

Create Payment Container

Creates a new Payment Container from the given data.

Important note: As of end of April 2024 you cannot create Payment Containers with type credit_card anymore. Your application needs to create these Payment Containers implicitly with POST /Smart/Transactions/{id}/prepare/{method}.

If your application uses the deprecated way, you are demanded to revise your integration.

With the sole exception of bank account details for payouts (outgoing bank transfers), we recommend to use the implicit creation as described above everywhere in your application.

Authorizations:
oauth_token
Request Body schema: application/json

Payment Container properties

merchant_id
string or null

General Merchant ID

object or null
Deprecated

The customer the Payment Container belongs to

customer_id
string or null

Payment Customer ID

type
string

Container type:

  • "bank_account"
  • "credit_card" (read-only)
  • "googlepay"
  • "applepay"
  • "paypal" (read-only)
request_token
boolean
Default: false

Request token

notification_url
string

Shop URL for failed external authorization or payment

object (OneOfPaymentContainersDTOModelPrivate)

Payment instrument data

  • BankAccountDescriptor
  • CreditCardDescriptor
  • GooglePayDescriptor
  • ApplePayDescriptor
  • PayPalDescriptor

Responses

Request samples

Content type
application/json
Example
{
  • "type": "bank_account",
  • "private": {
    }
}

Response samples

Content type
application/json
Example
{
  • "object": "payment.containers",
  • "id": "PCT_2Q03MEZ6X2P5BVRXN7FEVTWP0JC2A2",
  • "merchant": {
    },
  • "type": "bank_account",
  • "private": {
    },
  • "public": {
    },
  • "mandate": {
    },
  • "created": "2023-07-10T14:52:01+02:00"
}

Read Payment Containers

Returns the specified Payment Container.

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.containers",
  • "id": "PCT_2Q03MEZ6X2P5BVRXN7FEVTWP0JC2A2",
  • "merchant": {
    },
  • "type": "bank_account",
  • "private": {
    },
  • "public": {
    },
  • "mandate": {
    },
  • "created": "2023-07-10T14:52:01+02:00"
}

Update Payment Container

Updates the specified Payment Container with the given data.

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

Request Body schema: application/json

Payment Container properties

merchant_id
string or null

General Merchant ID

object or null
Deprecated

The customer the Payment Container belongs to

customer_id
string or null

Payment Customer ID

type
string

Container type:

  • "bank_account"
  • "credit_card" (read-only)
  • "googlepay"
  • "applepay"
  • "paypal" (read-only)
request_token
boolean
Default: false

Request token

notification_url
string

Shop URL for failed external authorization or payment

object (OneOfPaymentContainersDTOModelPrivate)

Payment instrument data

  • BankAccountDescriptor
  • CreditCardDescriptor
  • GooglePayDescriptor
  • ApplePayDescriptor
  • PayPalDescriptor

Responses

Request samples

Content type
application/json
Example
{
  • "type": "bank_account",
  • "private": {
    }
}

Response samples

Content type
application/json
Example
{
  • "object": "payment.containers",
  • "id": "PCT_2Q03MEZ6X2P5BVRXN7FEVTWP0JC2A2",
  • "merchant": {
    },
  • "type": "bank_account",
  • "private": {
    },
  • "public": {
    },
  • "mandate": {
    },
  • "created": "2023-07-10T14:52:01+02:00",
  • "updated": "2023-07-10T14:53:24+02:00"
}

Delete Payment Container

Deletes a Payment Container.

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

Responses

Response samples

Content type
application/json
Example
{
  • "object": "payment.containers",
  • "id": "PCT_2Q03MEZ6X2P5BVRXN7FEVTWP0JC2A2",
  • "merchant": {
    },
  • "type": "bank_account",
  • "private": {
    },
  • "public": {
    },
  • "mandate": {
    },
  • "created": "2023-07-10T14:52:01+02:00"
}

Obtain SEPA Mandate Form

Returns the URL of the B2B mandate form for this Payment Container. The form is a one-page PDF document. It must be signed by an authorised person and then uploaded again.

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

Request Body schema: application/json

B2B mandate form properties

customer_id
string

Payment Customer ID the SEPA mandate belongs to

type
string

SEPA mandate type (must be "B2B")

Responses

Request samples

Content type
application/json
{
  • "customer_id": "PCU_R2K5GTBAR2P5D8S76678M6XS0FYMAJ",
  • "type": "B2B"
}

Response samples

Content type
application/json
{}

Process Signed SEPA Mandate

Processes the signed B2B mandate for this Payment Container. The PDF must have been uploaded shortly before with POST /Document/Uploads. Now it is assigned to the Payment Container and a service case is created to carry out the activation.

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

Request Body schema: application/json

Signed B2B mandate properties

document_id
string

Document ID to assign

Responses

Request samples

Content type
application/json
{
  • "document_id": "DUP_E59X474K1P83O7K516ETYWUBSWDUJB"
}

Response samples

Content type
application/json
{
  • "service_issue_id": 2875433
}

Archive Payment Container

Archive a Payment Container

Authorizations:
oauth_token
path Parameters
paymentContainerId
required
string
Example: PCT_RAXFW5O5HHTZL1PJ4QQQJYF2NEJ9AD

Payment Container ID

Responses

Response samples

Content type
application/json
{
  • "result": true
}

Validate IBAN

Validate one or several IBANs.

Note: For large numbers of records please use the batch mechanism described in the API integration guide.

Authorizations:
oauth_token
Request Body schema: application/json

IBAN(s) to validate

id
integer

Reference ID to match the response values

iban
string

International Bank Account Number (IBAN)

Responses

Request samples

Content type
application/json
Example
{
  • "id": 1,
  • "iban": "DE02120300000000202051"
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "valid": true,
  • "iban": "DE02120300000000202051",
  • "bic": "BYLADEM1001",
  • "bankname": "Deutsche Kreditbank Berlin"
}

Payment Contracts

Payment contracts offer a view to a merchant's contracts, and are used to create payment transactions. S. a. General Contracts.

Find Payment Contracts Deprecated

Returns the Payment Contracts matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 48,
  • "data": [
    ]
}

Read Payment Contract Deprecated

Returns the specified Payment Contract.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string
Example: GCR_396SQXIC78HXZ3TKL2FN4G9NJ2WJZR

Payment Contract ID (PCR_...) or General Contract ID (GCR_...)

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_396SQXIC78HXZ3TKL2FN4G9NJ2WJZR",
  • "id_old": 1142838,
  • "approved": true,
  • "created": "2023-09-18T09:47:35+02:00",
  • "merchant": {
    }
}

Get available payment methods Deprecated

Get available payment methods for the Payment Contract for the given ID.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string

Contract identifier

Responses

Response samples

Content type
application/json
[
  • "string"
]

Clone contract

Clones a contract without identification process. This is used to onboard new projects for known merchants of your platform or marketplace.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string
Example: GCR_FD6EDRONTEHWBFVTOZE034XBXIIJN4

Payment Contract ID (PCR_...) or General Contract ID (GCR_...) of master contract

Request Body schema: application/json

New Payment Contract

contract_id
string

General Contract ID of the parent contract

project
string

Project name (must be unique)

object (PaymentInformation)

Bank details

payin_account
boolean
Default: "false"

Pay-in account

url_push
string

Default URL for push notifications; this is where your service listens for callbacks of the secuconnect service

Responses

Request samples

Content type
application/json
{
  • "project": "Erlebnis-Bauernhof Musterdorf",
  • "payout_account": {
    }
}

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_OVSMN0U1XJTW0GWRL9J8WXSLJFGHW3",
  • "id_old": 1559238,
  • "parent": {
    },
  • "approved": false,
  • "created": "2023-09-18T13:18:15+02:00",
  • "pay_in_account": {
    },
  • "merchant": {
    },
  • "apikey": "q32afazxcg7rxln6c289ri56o5xal40r951rylj5"
}

Request identification

Clones a contract and starts the identification process. This is used to onboard entirely new merchants to your platform or marketplace.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string
Example: GCR_FD6EDRONTEHWBFVTOZE034XBXIIJN4

Payment Contract ID (PCR_...) or General Contract ID (GCR_...) of master contract

Request Body schema: application/json

Payment contract request id properties

contract_id
string

General Contract ID of the parent contract

object (Contact)

Contact details

project
string

Project name (must be unique per platform or marketplace)

object (PaymentInformation)

Bank details

object (PaymentInformation)

Bank details

object (PaymentContractsDTOIFrameOpts)

PaymentContractsDTOIFrameOpts

url_push
string

Default URL for push notifications; this is where your service listens for callbacks of the secuconnect service

payin_account
boolean
Default: "false"

Whether to assign an account for incoming payments; please pass true if you intent to use invoice payment or prepayment

create_first_store
boolean
Default: "false"

Whether to create a first store at the same location

store_name
string

Store name of the first store

payout_purpose
string/[^0-9a-zA-Z .,+\-:?()\/\']{1,100}}/

Purpose for payouts that appears at the bank statement

identrequest
string

Object ID of Services Identrequest (SIR_...)

signed_contract
string

The document ID of of uploaded signed contract; s. Document service (DUP_...)

object (PaymentContractsDTORequestIdAdditionalData)

Additional data input

notes
string

Additional notes

invoice_reference
string

Reference text from user input

tid
string

Third party terminal ID

merchant_category
integer

Merchant category

This is not the ISO Merchant Category Code (MCC). The list can be obtained at `GET /api/v2/General/Merchants/me/MerchantCategories.

account_statement_text
string

Descriptor that appears at the credit card statements

Array of objects (PaymentContractsDTORequestIdPricing)

Pricing

funding_threshold
integer

Funding threshold in the minor currency unit, e. g. Euro Cents

funding_end
string

Funding end as ISO 8601 date

project_url
string

Project URL at the platform or marketplace

url_website
string

Optional website URL of the project or merchant

project_brochure
string

Ephemeral Document Upload ID (DUP_xyz) of project brochure

project_factsheet
string

Ephemeral Document Upload ID (DUP_xyz) of project factsheet

project_duration
integer

Project duration in months

account_verification
string

Ephemeral Document Upload ID (DUP_xyz) of account verification document by the bank institute of the merchant or project

interest_payment_interval
string

Interest payment interval:

  • "monthly"
  • "quarterly"
  • "half-yearly"
  • "yearly"
  • "different"
merchant_id
string or null
Default: null

General Merchant ID where the contract should be created (can be only used with 'event_details').

object or null (GeneralContractsEventDetails)

Event Details

Responses

Request samples

Content type
application/json
Example
{
  • "contact": {
    },
  • "project": "Erlebnis-Bauernhof Musterdorf",
  • "payout_account": {
    }
}

Response samples

Content type
application/json
{
  • "object": "general.contracts",
  • "id": "GCR_OVSMN0U1XJTW0GWRL9J8WXSLJFGHW3",
  • "id_old": 1559230,
  • "parent": {
    },
  • "merchant": {
    },
  • "approved": false,
  • "created": "2023-09-18T13:10:12+02:00",
  • "payin_account": {
    },
  • "apikey": "q32afazxcg7rxln6c289ri56o5xal40r951rylj5",
  • "contract": {
    }
}

Revoke all accruals Deprecated

Revoke accrual flag for all transactions of the specified Payment Contract.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string

Contract identifier

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "error": "ProductUnauthorizedException",
  • "error_details": "Invalid token",
  • "error_user": "ungültiger Token",
  • "code": 0,
  • "supportId": "s4l2y7oyr10p7wjtg8o6gnq2esly6r3v"
}

Change bank account Deprecated

Changes the payout bank account of a contract.

Authorizations:
oauth_token
path Parameters
paymentContractId
required
string

Contract identifier

Request Body schema: application/json
iban
string

International Bank Account Number (IBAN)

bic
string

Bank Identifier Code (BIC)

owner
string

Account owner name (personal name or company name)

bankname
string or null

Bank name

Responses

Request samples

Content type
application/json
{
  • "iban": "DE02120300000000202051",
  • "bic": "BYLADEM1001",
  • "owner": "Max Mustermann",
  • "bankname": "Deutsche Kreditbank Berlin"
}

Response samples

Content type
application/json
{
  • "result": true
}

Payment Secupay Payout

A convenient way to create a payout transaction. Payouts are payments paid by a merchant and received by his customers. S. a. Payment Transactions.

Read payout transaction

Returns the specified Payment Secupaypayout.

Authorizations:
oauth_token
path Parameters
paymentPayoutId
required
string

Payment Transaction ID

Responses

Response samples

Content type
application/json
{
  • "object": "payment.secupaypayout",
  • "id": "6hbx1e1e9l6997y6mb0b",
  • "trans_id": 49999999,
  • "status": "pending",
  • "amount": 400,
  • "currency": "EUR",
  • "purpose": "Auszahlung für Erlebnis-Bauernhof Musterdorf",
  • "order_id": "12345",
  • "transaction_status": 25,
  • "transaction_list": [
    ],
  • "transfer_purpose": "TA 49999999",
  • "transfer_account": {
    }
}

Create payout transaction with Payment Customer

Creates a new Payment Secupaypayout from the given data. It can be used to start a payout transaction.

This needs an additional Payment Customer. You should prefer POST /Payment/Secupaypayout/me/PayoutWithoutCustomer.

Authorizations:
oauth_token
Request Body schema: application/json

Payout transaction details

object (SecupayRedirectUrl)

SecupayRedirectUrl

contract
string

General Contract ID

object (PaymentCustomersProductModel)
Default: {}

Customer details

object

Options for customizing the checkout page

amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

purpose
string^[A-Za-zÄÖÜäöüß0-9\'?:,()\-+.\/&*$%\\\\ ]*$

The purpose of the payment. It appears at the bank statement of the payee.

order_id
string

Order number. Depending on the contract setting, it must be unique for each payment.

Array of objects (SecupayTransactionListItem)

Payout items

Responses

Request samples

Content type
application/json
{
  • "demo": "0",
  • "redirect_url": {},
  • "customer": "PCU_WRPBSDH3W2XB00575EK6AF393XR8AH",
  • "amount": 400,
  • "currency": "EUR",
  • "purpose": "Auszahlung für Erlebnis-Bauernhof Musterdorf",
  • "order_id": "12345",
  • "opt_data": {
    },
  • "transaction_list": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "payment.secupaypayout",
  • "id": "6hbx1e1e9l6997y6mb0b",
  • "trans_id": 49999999,
  • "status": "pending",
  • "amount": 400,
  • "currency": "EUR",
  • "purpose": "Payout",
  • "order_id": "12345",
  • "transaction_status": 25,
  • "transaction_list": [
    ],
  • "transfer_purpose": "TA 49999999",
  • "transfer_account": {
    }
}

Create payout transaction without Payment Customer

Creates a new Payment Secupaypayout from the given data. It can be used to start a payout transaction.

Authorizations:
oauth_token
Request Body schema: application/json

Payout transaction details

amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

contract_id
string

General Contract ID

Array of objects (SecupayPayoutListItem)

Payout items

purpose
string^[A-Za-zÄÖÜäöüß0-9\'?:,()\-+.\/&*$%\\\\ ]*$

The purpose of the payment. It appears at the bank statement of the payee.

execution_date
string

Date when the payout should be started (ISO 8601 date, or date and time)

Responses

Request samples

Content type
application/json
{
  • "contract_id": "GCR_8VQ6NM20NHF6PZH1VNHJ7XXBU0QQ34",
  • "amount": 300,
  • "currency": "EUR",
  • "purpose": "Auszahlung von Erlebnis-Bauernhof Musterdorf",
  • "payout_list": [
    ]
}

Response samples

Content type
application/json
{
  • "amount": 300,
  • "currency": "EUR",
  • "contract_id": "GCR_8VQ6NM20NHF6PZH1VNHJ7XXBU0QQ34",
  • "payout_list": [
    ],
  • "purpose": "Auszahlung für Erlebnis-Bauernhof Musterdorf",
  • "trans_id": 49999997,
  • "transfer_account": {
    }
}

Payment Payouts

Find Payment Payout

Returns the Payment Payout matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{}

Read Payment Payout

Returns the specified Payment Payout.

Authorizations:
oauth_token
path Parameters
paymentPayoutId
required
string

Payment Payout ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{}

Payment Invoices

A Payment Invoices describes an invoice for payment services by secupay. Directly cleared POS payments are not included (s. Cardprocessing Invoices).

Find Payment Invoices

Returns the Payment Invoices matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 132,
  • "data": [
    ]
}

Read Payment Invoice

Returns the specified Payment Invoice.

Authorizations:
oauth_token
path Parameters
paymentInvoiceId
required
string

Payment invoice id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "cardprocessing.invoices",
  • "id": "POI_C0HKABT933JQYPA84P8B3F48H802OK",
  • "merchant": {
    },
  • "store_name": null,
  • "id_old": 1999123,
  • "tid": "99999999",
  • "invoice_number": "29999321",
  • "net_amount": 61500,
  • "tax_amount": 11685,
  • "amount": 73185,
  • "currency": "EUR",
  • "document_url": "https://connect.secucard.com/document/GetCardprocessingInvoice?invoice_id=POI_C0HKABT933JQYPA84P8B3F48H802OK",
  • "type": "invoice",
  • "created": "2023-09-06T12:00:00+02:00",
  • "updated": "2023-09-06T15:14:32+02:00"
}

Payment Plans

The Payment Plan holds the plan details for subscriptions derived from it. Such details include, for example, the type of product, billing cycles and tariffs.

Find Payment Plans

Returns the Payment Plans matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 23,
  • "data": [
    ]
}

Create Payment Plan

Creates a new Payment Plan from the given data.

Note: Please care to have the PayPal Subscription Plan in sync!

Authorizations:
oauth_token
Request Body schema: application/json

Plan details

description
string <= 50 characters

Short description of the subscription plan

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

paypal_plan_id
string

PayPal Subscription Plan ID; needed for PayPal payment

status
string

Status:

  • "created"
  • "active"
  • "inactive"
payment_methods
Array of strings

Payment methods:

  • "creditcard"
  • "debit"
  • "paypal"
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

Array of objects (BillingCyclesItem)

Billing cycles

Responses

Request samples

Content type
application/json
{
  • "description": "Basis-Abo Probemonat 1,99 €, danach mtl. 7,99 €",
  • "product_type": "physical",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-2WIL62NC8CUGMM123KK49OWE",
  • "payment_methods": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "payment.plans",
  • "id": "PLN_PKM0AS06Z8IKB2UXU01TPY5Q0WMDY8",
  • "description": "Basis-Abo Probemonat 1,99 €, danach mtl. 7,99 €",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-C19L1VYIQUGZ5AK61Y8WP9IF",
  • "payment_methods": [
    ],
  • "status": "active",
  • "product_type": "physical",
  • "created": "2023-09-18T15:58:37+02:00",
  • "updated": "2023-09-18T15:58:37+02:00"
}

Read Payment Plan

Returns the specified Payment Plan.

Authorizations:
oauth_token
path Parameters
paymentPlanId
required
string

Payment Plan ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "payment.plans",
  • "id": "PLN_PKM0AS06Z8IKB2UXU01TPY5Q0WMDY8",
  • "description": "Basis-Abo Probemonat 1,99 €, danach mtl. 7,99 €",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-C19L1VYIQUGZ5AK61Y8WP9IF",
  • "payment_methods": [
    ],
  • "status": "active",
  • "product_type": "physical",
  • "created": "2023-09-18T15:58:37+02:00",
  • "updated": "2023-09-18T15:58:37+02:00"
}

Update Payment Plan

Updates the specified Payment Plan with the given data.

Note: Please keep the PayPal Subscription Plan in sync!

Authorizations:
oauth_token
path Parameters
paymentPlanId
required
string

Payment Plan ID

Request Body schema: application/json

Plans details

description
string <= 50 characters

Short description of the subscription plan

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

paypal_plan_id
string

PayPal Subscription Plan ID; needed for PayPal payment

status
string

Status:

  • "created"
  • "active"
  • "inactive"
payment_methods
Array of strings

Payment methods:

  • "creditcard"
  • "debit"
  • "paypal"
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

Array of objects (BillingCyclesItem)

Billing cycles

Responses

Request samples

Content type
application/json
{
  • "description": "Basis-Abo Probemonat 2,99 €, danach mtl. 9,95 €",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-2WIL62NC8CUGMM123KK49OWE",
  • "payment_methods": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "payment.plans",
  • "id": "PLN_PKM0AS06Z8IKB2UXU01TPY5Q0WMDY8",
  • "description": "Basis-Abo Probemonat 2,99 €, danach mtl. 9,95 €",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-2WIL62NC8CUGMM123KK49OWE",
  • "payment_methods": [
    ],
  • "status": "active",
  • "product_type": "digital",
  • "created": "2023-09-18T16:27:43+02:00",
  • "updated": "2023-09-18T16:34:40+02:00"
}

Update Payment Plan partially

Updates an existing Payment Plan with the given partial data.

Note: Please keep the PayPal Subscription Plan in sync!

Authorizations:
oauth_token
path Parameters
paymentPlanId
required
string

Payment Plan ID

Request Body schema: application/json

Plans details

description
string <= 50 characters

Short description of the subscription plan

currency
string (Currency) ^[A-Z]{3}$
Default: "EUR"

ISO-4217 alpha-3 currency code

paypal_plan_id
string

PayPal Subscription Plan ID; needed for PayPal payment

status
string

Status:

  • "created"
  • "active"
  • "inactive"
payment_methods
Array of strings

Payment methods:

  • "creditcard"
  • "debit"
  • "paypal"
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

Array of objects (BillingCyclesItem)

Billing cycles

Responses

Request samples

Content type
application/json
{
  • "description": "Basis-Abo Probemonat 2,99 €, danach mtl. 9,95 €",
  • "billing_cycles": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "payment.plans",
  • "id": "PLN_PKM0AS06Z8IKB2UXU01TPY5Q0WMDY8",
  • "description": "Basis-Abo Probemonat 2,99 €, danach mtl. 9,95 €",
  • "merchant": {
    },
  • "currency": "EUR",
  • "billing_cycles": [
    ],
  • "paypal_plan_id": "P-2WIL62NC8CUGMM123KK49OWE",
  • "payment_methods": [
    ],
  • "status": "active",
  • "product_type": "digital",
  • "created": "2023-09-18T16:27:43+02:00",
  • "updated": "2023-09-18T16:34:40+02:00"
}

Payment Subscriptions

The payment subscription controls the payments for a specific subscription. It is created with a Smart Transaction and is derived from, and is connected to, a Subscription Plan. If the original payment instrument no longer works, it can be re-authorised with a Smart Transaction.

Find Payment Subscriptions

Returns the Payment Subscriptions matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 567,
  • "data": [
    ]
}

Read Payment Subscription

Returns the specified Payment Subscription.

Authorizations:
oauth_token
path Parameters
paymentSubscriptionId
required
string

Payment Subscription ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "payment.subscriptions",
  • "id": "SUB_QCQ7EST28E9WT89LPL5TBXKQ8ZPM36I0",
  • "smart_transaction": {
    },
  • "merchant": {
    },
  • "contract": {
    },
  • "customer": {
    },
  • "container": {
    },
  • "plan": {
    },
  • "start_at": "2023-09-17T21:03:33+02:00",
  • "status": "active",
  • "paypal_subscription_id": "I-0TB4QR6UIQ7T",
  • "billing_info": {
    },
  • "created": "2023-09-17T20:03:37+02:00",
  • "updated": "2023-09-17T20:04:39+02:00",
  • "demo": false
}

Loyalty Transactions

A loyalty transaction can be a charge of monetary credit or bonus credit, which can be spent (discharge) in another transaction. Furthermore loyalty transactions track revenues related to loyalty programmes.

Find Loyalty Transactions

Returns the Loyalty Transactions matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 103,
  • "data": [
    ]
}

Read Loyalty Transaction

Returns the specified Loyalty Transaction.

Authorizations:
oauth_token
path Parameters
loyaltyTransactionId
required
string

Loyalty Transaction ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.transactions",
  • "id": "LTX_9FDWJ2TERFBUV2MVFIID9FOGONTJ4V",
  • "trans_id": 34567890,
  • "merchant": {
    },
  • "store": {
    },
  • "tid": "VT003456",
  • "card": {
    },
  • "cardgroup": {
    },
  • "merchantcard": {
    },
  • "currency": "EUR",
  • "balance": 1000,
  • "amount": 1000,
  • "status": "accepted",
  • "description": "Aufladung",
  • "parents": [ ],
  • "children": [ ],
  • "created": "2021-08-20T10:19:00+02:00",
  • "last_change": "2021-08-20T10:19:00+02:00",
  • "is_cancelling": 0,
  • "receipt": {
    },
  • "additional_data": {
    }
}

Loyalty Customers

A Loyalty Customer holds the customer details for a Loyalty Card used as customer card. It can be created and associated with the card at a later point in time, for instance in combination with changing the Loyalty Card Group.

Find Loyalty Customers

Returns the Loyalty Customers matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "data": [
    ]
}

Create Loyalty Customer

Creates a new Loyalty Customer using the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Loyalty Customer details

merchant
string

Merchant ID

object (Contact)

Contact details

customernumber
string

Customer number in the merchant's system

note
string

Note from the merchant

consent_for_communication
string

Whether the customer has given consent for communication or not:

  • "accepted"
  • "declined"
  • "not_set"
additional_data
object

Additional data properties

anonymize
boolean or null

Anonymize customer data (only valid on update requests)

Responses

Request samples

Content type
application/json
{
  • "merchant": "MRC_FVIOF8INPJODEQS14B9AAIVBSQI59U",
  • "merchant_contact": {
    },
  • "consent_for_communication": "accepted"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.customers",
  • "id": "CUS_GGCQX7M3D6VL2AM7VVLMJ1RDITHY7T",
  • "merchant": {
    },
  • "merchant_contact": {
    },
  • "contact": {
    },
  • "created": "2024-02-23T17:42:20+01:00",
  • "consent_for_communication": "accepted"
}

Read Loyalty Customer

Returns the specified Loyalty Customer.

Authorizations:
oauth_token
path Parameters
loyaltyCustomerId
required
string

Loyalty Customer ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.customers",
  • "id": "CUS_GGCQX7M3D6VL2AM7VVLMJ1RDITHY7T",
  • "merchant": {
    },
  • "merchant_contact": {
    },
  • "contact": {
    },
  • "created": "2024-02-23T17:54:45+01:00",
  • "consent_for_communication": "accepted"
}

Update Loyalty Customer

Updates the specified Loyalty Customer using the given data.

Authorizations:
oauth_token
path Parameters
loyaltyCustomerId
required
string

Loyalty Customer ID

Request Body schema: application/json

Loyalty Customer details

merchant
string

Merchant ID

object (Contact)

Contact details

customernumber
string

Customer number in the merchant's system

note
string

Note from the merchant

consent_for_communication
string

Whether the customer has given consent for communication or not:

  • "accepted"
  • "declined"
  • "not_set"
additional_data
object

Additional data properties

anonymize
boolean or null

Anonymize customer data (only valid on update requests)

Responses

Request samples

Content type
application/json
{
  • "merchant_contact": {
    },
  • "consent_for_communication": "accepted"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.customers",
  • "id": "CUS_GGCQX7M3D6VL2AM7VVLMJ1RDITHY7T",
  • "merchant": {
    },
  • "merchant_contact": {
    },
  • "contact": {
    },
  • "created": "2024-02-23T17:42:20+01:00",
  • "consent_for_communication": "accepted"
}

Assign payment container to customer

Assigns the specified Loyalty Payment Container to the specified Loyalty Customer.

Authorizations:
oauth_token
path Parameters
loyaltyCustomerId
required
string

Loyalty Customer ID

loyaltyPaymentContainerId
required
string

Loyalty Payment Container ID

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.customers",
  • "id": "CUS_TBASD3CC162O4H792AELTJDDJZI45T",
  • "merchant": {
    },
  • "payment_container": [
    ],
  • "merchant_contact": {
    },
  • "contact": {
    },
  • "created": "2024-02-26T11:13:09+01:00",
  • "consent_for_communication": "declined"
}

Detach payment container from customer

Detaches the specified Loyalty Payment Container from the specified Loyalty Customer.

Authorizations:
oauth_token
path Parameters
loyaltyCustomerId
required
string

Loyalty Customer ID

loyaltyPaymentContainerId
required
string

Loyalty Payment Container ID

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.customers",
  • "id": "CUS_TBASD3CC162O4H792AELTJDDJZI45T",
  • "merchant": {
    },
  • "merchant_contact": {
    },
  • "contact": {
    },
  • "created": "2024-02-26T11:13:09+01:00",
  • "consent_for_communication": "declined"
}

Loyalty Cards

Loyalty Cards represent physical or virtual secucard cards, identified by their card numbers. This is the card holder's view on the card.

Each secucard card can be used for one or more merchants. The merchant's perspective is covered by the associated Merchant Cards (see there).

Find Loyalty Cards

Returns the Loyalty Cards matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 1234567,
  • "data": [
    ]
}

Read Loyalty Card

Returns the specified Loyalty Card.

Authorizations:
oauth_token
path Parameters
loyaltyCardId
required
string

Search one loyalty card by provided id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.cards",
  • "id": "CRD_M4SBA579N0JHDJGAFJ229PZJO0I243",
  • "cardnumber": "9276001234567891",
  • "account": {
    },
  • "created": "2021-11-30T16:33:50+01:00"
}

Assign card to user

Assigns the specified Loyalty Card to the specified General Account.

Authorizations:
oauth_token
path Parameters
loyaltyCardId
required
string

Loyalty Card ID

generalAccountId
required
string

General Account ID

Request Body schema: application/json

Card PIN of the specific Loyalty Card

pin
string

Card PIN (four decimal digits)

The card PIN must not be mixed with the Card Security Code (CSC) on the card.

Responses

Request samples

Content type
application/json
{
  • "pin": "9867"
}

Response samples

Content type
application/json
{
  • "result": true
}

Unassign card from user

Detaches the specified Loyalty Card from the specified General Account.

Authorizations:
oauth_token
path Parameters
loyaltyCardId
required
string

Loyalty Card ID

generalAccountId
required
string

General Account ID

Responses

Response samples

Content type
application/json
{
  • "result": true
}

Loyalty Card Groups

Card Groups define different loyalty programmes offered by a merchant. Every Merchant Card can be assigned to only one Card Group at a time. But the Card Group can be changed, for instance to lift a customer card on a higher level. The card balances are then taken unchanged to the new programme.

Find Loyalty Card Groups

Returns the Loyalty Card Groups matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 21,
  • "data": [
    ]
}

Create Loyalty Card Group

Creates a new Loyalty Cardgroup using the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Loyalty Card Group details

display_name
required
string

Display name (programme name)

picture
string or null

Document Upload ID of symbol image

merchant
required
string

General Merchant ID

Responses

Request samples

Content type
application/json
{
  • "display_name": "Geschenkkarte",
  • "picture": "DUP_FJFV41MV78Y1VLS9CNQQ04LKJCDHVZ",
  • "merchant": "MRC_S2WN3JRQH4DPSBN5DD548GVD7A5NQF"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.cardgroups",
  • "id": "CRG_6XWQO0DNJXFECCYFNXFWRWDUAB69UD",
  • "display_name": "Geschenkkarte",
  • "display_name_raw": "Geschenkkarte",
  • "stock_warn_limit": 0,
  • "picture": "https://connect-testing.secupay-ag.de/ds_g/ckdj0a7fbazglepnlu4xnnq2rg0ih2m6",
  • "merchant": {
    },
  • "balance_limit": 2000000,
  • "balance_expiry": false,
  • "cancel_selected": false,
  • "description": null
}

Read Loyalty Card Group

Returns the specified Loyalty Card Group.

Authorizations:
oauth_token
path Parameters
loyaltyCardGroupId
required
string

Loyalty Card Group ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.cardgroups",
  • "id": "CRG_6XWQO0DNJXFECCYFNXFWRWDUAB69UD",
  • "display_name": "Geschenkkarte",
  • "display_name_raw": "Geschenkkarte",
  • "stock_warn_limit": 0,
  • "picture": "https://connect-testing.secupay-ag.de/ds_g/ckdj0a7fbazglepnlu4xnnq2rg0ih2m6",
  • "merchant": {
    },
  • "balance_limit": 2000000,
  • "balance_expiry": false,
  • "cancel_selected": false,
  • "description": null
}

Update Loyalty Card Group

Updates the specified Loyalty Card Group using the given data.

Authorizations:
oauth_token
path Parameters
loyaltyCardGroupId
required
string

Loyalty Card Group ID

Request Body schema: application/json

Loyalty Card Group details

display_name
required
string

Display name (programme name)

picture
string or null

Document Upload ID of symbol image

Responses

Request samples

Content type
application/json
{
  • "display_name": "Geschenkkarte",
  • "picture": "DUP_GX7UBYOZUBUPHV8R271D3UQLOSHKIE"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.cardgroups",
  • "id": "CRG_6XWQO0DNJXFECCYFNXFWRWDUAB69UD",
  • "display_name": "Geschenkkarte",
  • "display_name_raw": "Geschenkkarte",
  • "stock_warn_limit": 0,
  • "picture": "https://connect-testing.secupay-ag.de/ds_g/ect9bfnv9uc3cmn468693lmwuazr3n1f",
  • "merchant": {
    },
  • "balance_limit": 2000000,
  • "balance_expiry": false,
  • "cancel_selected": false,
  • "description": null
}

Check need for passcode check

Checks whether the passcode check is enabled, and therefore required, for a specific action.

Authorizations:
oauth_token
path Parameters
loyaltyCardGroupId
required
string

Loyalty Card Group ID

Request Body schema: application/json

Check passcode details

action
string

Action type:

  • "charge"
  • "discharge"
  • "sale_revenue"
  • "charge_points"
  • "discharge_points"
  • "cashreport"
cardnumber
string

Loyalty card number

Responses

Request samples

Content type
application/json
{
  • "action": "charge",
  • "cardnumber": "9276001234567890"
}

Response samples

Content type
application/json
{
  • "result": true
}

Loyalty Merchant Cards

A Loyalty Merchant Card is a per-merchant view on a Loyalty Card. So you can use one card for more multiple merchants with separate accounting.

The card can have two different forms of balance at the same time, monetary credit and bonus balance, one for money paid in and the other as reward for revenues. They have different origins and must be handled differently in book-keeping. When spent they make no difference.

A card can be secured by either the card security code (CSC) printed on card, or a configurable passcode. Please don't mix them up!

Find Loyalty Merchant Cards

Returns the Loyalty Merchant Cards matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 104,
  • "data": [
    ]
}

Read Loyalty Merchant Card

Returns the specified Loyalty Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "payment_container": {
    },
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-26T13:44:05+02:00",
  • "last_charge": "2021-08-26T13:44:05+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Update Loyalty Merchant Card

Updates the specified Loyalty Merchant Card with the given data.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Merchant Card details

expiry_date
string

Card expiry date in ISO 8601 format

payment_container
string

Loyalty Payment Container ID

additional_data
object

Custom additional data

Responses

Request samples

Content type
application/json
{
  • "payment_container": "LPC_GZI08RBBLUA4MI3JT079PTW04LPJHI"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "payment_container": {
    },
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-26T13:44:05+02:00",
  • "last_charge": "2021-08-26T13:44:05+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Set card group

Sets the Loyalty Card Group, and returns the updated Loyalty Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

loyaltyCardGroupId
required
string

Loyalty Card Group ID

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "payment_container": {
    },
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-26T13:44:05+02:00",
  • "last_charge": "2021-08-26T13:44:05+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Register customer

Creates a new Loyalty Customer, and assigns it to the specified Loyalty Merchant Card.

This can only be done once per Merchant Card. But you can update it using the Loyalty Customer operations.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Loyalty Customer details

merchant
string

Merchant ID

object (Contact)

Contact details

customernumber
string

Customer number in the merchant's system

note
string

Note from the merchant

consent_for_communication
string

Whether the customer has given consent for communication or not:

  • "accepted"
  • "declined"
  • "not_set"
additional_data
object

Additional data properties

anonymize
boolean or null

Anonymize customer data (only valid on update requests)

Responses

Request samples

Content type
application/json
{
  • "merchant": "MRC_RU12NA3BCWT7B4557NOJIKC6S1Z1TO",
  • "merchant_contact": {
    },
  • "customernumber": "K765",
  • "consent_for_communication": "accepted"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "customer": {
    },
  • "customer_assignment_date": "2024-03-15T09:46:47+01:00",
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-25T11:45:17+02:00",
  • "last_charge": "2021-08-25T11:45:17+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Set customer

Assigns an existing Loyalty Customer to the specified Loyalty Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

loyaltyCustomerId
required
string

Loyalty Customer ID

Responses

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "customer": {
    },
  • "customer_assignment_date": "2024-03-15T09:46:47+01:00",
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-25T11:45:17+02:00",
  • "last_charge": "2021-08-25T11:45:17+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Read lock reasons

Returns the lock reasons.

Authorizations:
oauth_token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Read lock details

Returns the lock details of the specified Loyalty Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Responses

Response samples

Content type
application/json
Example
{
  • "lock_status": "locked",
  • "reason": 1,
  • "note": "Anruf von Herrn M., Karte verloren"
}

Lock card

Locks the specified Loyalty Merchant Card, so that it cannot be used.

Works only for Merchant Cards not being locked.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Lock details

reason
integer

Lock reason:

  • 1 = Lost
  • 2 = Defect
  • 3 = Claims,
  • 6 = Expired
  • 8 = Not activated
note
string

Human readable note

csc
string

Card Security Code (optional in the most cases)

Responses

Request samples

Content type
application/json
{
  • "reason": 1,
  • "note": "Anruf von Herrn M., Karte verloren"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_F2FLOVCAUGH1EA36C1SK7KIXO0VT6W",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "payment_container": {
    },
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-26T13:44:05+02:00",
  • "last_charge": "2021-08-26T13:44:05+02:00",
  • "stock_status": "active",
  • "lock_status": "locked",
  • "passcode": 2,
  • "expiry_date": null
}

Unlock card

Unlocks the specified Loyalty Merchant Card, so that it can be used again.

Works only for Merchant Cards being locked.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Unlock details

reason
integer

Lock reason:

  • 1 = Lost
  • 2 = Defect
  • 3 = Claims,
  • 6 = Expired
  • 8 = Not activated
note
string

Human readable note

csc
string

Card Security Code (optional in the most cases)

Responses

Request samples

Content type
application/json
{
  • "note": "Anruf von Frau M., Kartenaktivierung"
}

Response samples

Content type
application/json
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "payment_container": {
    },
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 1000,
  • "bonus_balance": 0,
  • "balance": 1000,
  • "last_usage": "2021-08-26T13:44:05+02:00",
  • "last_charge": "2021-08-26T13:44:05+02:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null
}

Get virtual terminal data

Returns the virtual terminal data for the merchant.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

loyaltyMerchantId
required
string

Loyalty Merchant ID

Responses

Response samples

Content type
application/json
{
  • "disabled": 1
}

Execute Transaction

Carries out a Loyalty Transaction. Intended to be used by SDK

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

targetMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Transaction details

action
string

Action:

  • "charge"
  • "discharge"
  • "sale_revenue"
  • "charge_points"
  • "discharge_points"
  • "cancel_last"
  • "immediate_bonus"
terminal_id
string

Terminal ID

amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

tid
string

Terminal TID

store
string

General Store ID

cardnumber
string

Number on card

bonus_amount
integer

Bonus amount

amount_split_allowed
string

Whether amount split is allowed

merchant_id
string

General Merchant ID

additional_data
object

Responses

Request samples

Content type
application/json
Example
{
  • "action": "charge",
  • "amount": 100,
  • "bonus_amount": 100,
  • "tid": "VT003456"
}

Response samples

Content type
application/json
Example
{
  • "object": "loyalty.merchantcards",
  • "id": "MCD_KWESAHFOA0HUZAAPASWQ2T6I4J23HV",
  • "merchant": {
    },
  • "created_for_merchant": {
    },
  • "card": {
    },
  • "cardgroup": {},
  • "created_for_store": {
    },
  • "customer": {
    },
  • "customer_assignment_date": "2023-03-14T14:46:10+01:00",
  • "is_base_card": true,
  • "points": 0,
  • "cash_balance": 7600,
  • "bonus_balance": 0,
  • "balance": 7600,
  • "last_usage": "2023-03-16T16:02:59+01:00",
  • "last_charge": "2023-03-16T16:02:59+01:00",
  • "stock_status": "active",
  • "lock_status": "unlocked",
  • "passcode": 2,
  • "expiry_date": null,
  • "receipt_header": [
    ],
  • "receipt": [
    ],
  • "trans_id": 234567890,
  • "amount": 100
}

Check security code

Checks the Card Security Code (CSC).

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Card number and security code

cardnumber
string

Number on card

csc
string

Entered Card Security Code

Responses

Request samples

Content type
application/json
{
  • "cardnumber": 9276001234567890,
  • "csc": "3645"
}

Response samples

Content type
application/json
{
  • "result": true
}

Validate merchant card

Returns whether it is a Merchant Card for the given Merchant and number on card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Merchant ID and card number

merchant
string

General Merchant ID

cardnumber
string

Number on card

Responses

Request samples

Content type
application/json
{
  • "cardnumber": 9276001234567890,
  • "merchant": "MRC_RU12NA3BCWT7B4557NOJIKC6S1Z1TO"
}

Response samples

Content type
application/json
{
  • "isValid": false
}

Set new passcode

Sets a passcode for the given Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Card number and new passcode

merchant
string

General Merchant ID

cardnumber
string

Number on card

passcode
integer

Passcode

Responses

Request samples

Content type
application/json
{
  • "merchant": "MRC_RU12NA3BCWT7B4557NOJIKC6S1Z1TO",
  • "cardnumber": 9276001234567890,
  • "passcode": 435687
}

Response samples

Content type
application/json
{
  • "result": true
}

Reset passcode

Requests to set a new passcode for the given Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Card number and current passcode

cardnumber
string

Number on card

passcode
integer

Old passcode

Responses

Request samples

Content type
application/json
{
  • "cardnumber": 9276001234567890,
  • "passcode": 435687
}

Response samples

Content type
application/json
{
  • "result": true
}

Check passcode

Checks the passcode for the given Merchant Card.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Information about card

cardnumber
string

Number on card

pin
integer

Entered passcode

Responses

Request samples

Content type
application/json
{
  • "cardnumber": 9276001234567890,
  • "pin": 435687
}

Response samples

Content type
application/json
{
  • "result": true
}

Create multiple cards

Creates multiple Merchant Cards for the given merchant having the given card group.

You can either create one card with customer details, or multiple cards without it.

Authorizations:
oauth_token
path Parameters
generalMerchantId
required
string

General Merchant ID

loyaltyCardgroupId
required
string

Loyalty Card Group ID

Request Body schema: application/json

Number of cards and customer details

cards_amount
integer [ 1 .. 1000 ]

Number of cards to create

object (LoyaltyMerchantcardsDTOCustomer)

LoyaltyMerchantcardsDTOCustomer

Responses

Request samples

Content type
application/json
Example
{
  • "cards_amount": 1,
  • "customer": {
    }
}

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get balance receipt

Returns a receipt about the card balance. Returns also some more card details in additional fields.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
required
string

Loyalty Merchant Card ID

Request Body schema: application/json

Card number and terminal ID

cardnumber
string

Number on card

terminal_id
string

Terminal ID

Responses

Request samples

Content type
application/json
{
  • "cardnumber": "9276004524764102",
  • "terminal_id": 0
}

Response samples

Content type
application/json
{
  • "cardnumber": "9276004524764102",
  • "valid": true,
  • "balance": 500,
  • "cash_balance": 500,
  • "bonus_balance": 0,
  • "zvt_cardgroup": "00",
  • "points": 0,
  • "new_passcode": false,
  • "receipt_header": [
    ],
  • "receipt": [
    ],
  • "amount_split_enabled": true,
  • "limit_allowed": false,
  • "limit_str": " ",
  • "limit": 0
}

Prepaid Contracts

Get Prepaid Item ID

Returns the Prepaid Item with the given product ID and amount that is configured for this contract.

Authorizations:
oauth_token
path Parameters
prepaidContractId
required
string
Default: "me"

Prepaid contract id

Request Body schema: application/json

Product ID and amount

amount
integer (MoneyAmount)

Amount in smallest currency unit (e. g. Euro Cent)

product_id
string^[0-9]{1,13}$

Product ID of the cash register (ECR); can be padded with leading zeros

Responses

Request samples

Content type
application/json
{
  • "amount": 1500,
  • "product_id": "0000000123456789"
}

Response samples

Content type
application/json
Example
{
  • "item": {
    },
  • "productId": "0000000123456789"
}

Prepaid Items

Manages the available e-goods products, either PIN printing or POS activation (POSA). Examples for such products are phone charge, or vouchers for an online shop.

Find Prepaid Items

Returns the Prepaid Items matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 267,
  • "data": [
    ]
}

Read Prepaid Item

Returns the specified Prepaid Item.

Authorizations:
oauth_token
path Parameters
prepaidItemId
required
string

Prepaid Item ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "prepaid.items",
  • "id": "PIT_T4ENPVUS43H5GT8HH7L7VJ6LRUAJIT",
  • "itemgroup": {
    },
  • "retail_price": 2500,
  • "description": "Mustergutschein 25 EUR",
  • "displaytext": "25,00 EUR",
  • "vtc_config": [
    ],
  • "taxable": false,
  • "type": "POSA",
  • "enabled": true
}

Prepaid Reports

Report of prepaid transactions

Find Prepaid Reports

Returns the Prepaid Reports matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 135,
  • "data": [
    ]
}

Create Prepaid Report

Generates and returns a new Prepaid Report.

Authorizations:
oauth_token
Request Body schema: application/json

Reporting details

merchant
required
string

General Merchant ID

store
required
string

General Store ID

smart_device
required
string

Smart Device ID

vtc_tid
required
integer

Terminal ID for VTC Virtual Terminal Client (received during onboarding)

report_from
string

Report start date (ISO-8601 formatted date and time, incl. timezone)

report_to
string

Report end date (ISO-8601 formatted date and time, incl. timezone)

Responses

Request samples

Content type
application/json
{
  • "merchant": "MRC_1GUZD3W43JKAH8X4F9EMBR6GWP0T3I",
  • "store": "STO_OUMRB9KB523H1JHBEK8JDL119AT4IS",
  • "smart_device": "SDV_1EW8KVKXX68X90XKAXA9FXGZK63O9N",
  • "vtc_id": "12346578",
  • "report_from": "2024-01-01T00:00:00",
  • "report_to": "2024-02-01T:00:00"
}

Response samples

Content type
application/json
{
  • "object": "prepaid.reports",
  • "id": "PRE_N9INA5MD8P7EX7KGW7EIA9VSV8GP94",
  • "merchant": {
    },
  • "store": {
    },
  • "device": {
    },
  • "amount": 1500,
  • "vtc_tid": "12346578",
  • "receipt": [
    ],
  • "receipt_header": [
    ],
  • "report_from": "2024-02-09T22:53:11+01:00",
  • "report_to": "2024-02-11T23:37:32+01:00",
  • "created": "2024-02-11T23:37:32+01:00"
}

Read Prepaid Report

Returns the specified Prepaid Report.

Authorizations:
oauth_token
path Parameters
required
object (ProductInstanceUID)

Prepaid Reports ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "prepaid.reports",
  • "id": "PRE_N9INA5MD8P7EX7KGW7EIA9VSV8GP94",
  • "merchant": {
    },
  • "store": {
    },
  • "device": {
    },
  • "amount": 1500,
  • "vtc_tid": "12346578",
  • "receipt": [
    ],
  • "receipt_header": [
    ],
  • "report_from": "2024-02-09T22:53:11+01:00",
  • "report_to": "2024-02-11T23:37:32+01:00",
  • "created": "2024-02-11T23:37:32+01:00"
}

Prepaid Sales

Transaction for selling e-goods (s. Prepaid Items)

Find Prepaid Sales

Returns the Prepaid Sales matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 12345678,
  • "data": [
    ]
}

Create Prepaid Sale

Creates a new Prepaid Sale from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Sale details

item
string

Prepaid Sales Transaction ID

Responses

Request samples

Content type
application/json
{
  • "item": "12345678"
}

Response samples

Content type
application/json
{
  • "object": "prepaid.sales",
  • "id": "PSL_BI7GB94UL1YVE9POJ9TZW6F1AETHOV",
  • "stock": {
    },
  • "item": {
    },
  • "itemgroup": {},
  • "smart_device": {
    },
  • "merchant": {
    },
  • "contract": {
    },
  • "store": {
    },
  • "demo": false,
  • "description": "Mustermarke 10 EUR",
  • "amount": 1000,
  • "currency": "EUR",
  • "code": "5501234567890",
  • "serial": "500087654321",
  • "provider_delivery_number": "123456789012345678",
  • "status": "delivered",
  • "type": "sale_item",
  • "receipt_header": [
    ],
  • "receipt_customer": [
    ],
  • "receipt_zvt": [
    ],
  • "created": "2019-08-11T09:49:18+02:00",
  • "expire_date": "2023-08-01T00:00:00+02:00",
  • "vtc_tid": "23456789",
  • "vtc_id": "4012345678901"
}

Read Prepaid Sale

Returns the specified Prepaid Sale.

Authorizations:
oauth_token
path Parameters
prepaidSaleId
required
string <id> (ObjectId)
Example: OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G

Prepaid Sale ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "prepaid.sales",
  • "id": "PSL_BI7GB94UL1YVE9POJ9TZW6F1AETHOV",
  • "stock": {
    },
  • "item": {
    },
  • "itemgroup": {},
  • "smart_device": {
    },
  • "merchant": {
    },
  • "contract": {
    },
  • "store": {
    },
  • "demo": false,
  • "description": "Mustermarke 10 EUR",
  • "amount": 1000,
  • "currency": "EUR",
  • "code": "5501234567890",
  • "serial": "500087654321",
  • "provider_delivery_number": "123456789012345678",
  • "status": "delivered",
  • "type": "sale_item",
  • "receipt_header": [
    ],
  • "receipt_customer": [
    ],
  • "receipt_zvt": [
    ],
  • "created": "2019-08-11T09:49:18+02:00",
  • "expire_date": "2023-08-01T00:00:00+02:00",
  • "vtc_tid": "23456789",
  • "vtc_id": "4012345678901"
}

Confirm sale

Confirms and executes the specified Prepaid Sale.

Authorizations:
oauth_token
path Parameters
prepaidSaleId
required
string <id> (ObjectId)
Example: OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G

Prepaid Sale ID

Responses

Response samples

Content type
application/json
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "status": "string",
  • "type": "string",
  • "stock": {
    },
  • "item": {
    },
  • "itemgroup": {
    },
  • "smart_device": {
    },
  • "merchant": {
    },
  • "store": {
    },
  • "contract": {
    },
  • "demo": true,
  • "description": "string",
  • "amount": 1995,
  • "currency": "EUR",
  • "commission": 0,
  • "commission_currency": "string",
  • "code": "string",
  • "serial": "string",
  • "cardnumber": "string",
  • "expire_date": "string",
  • "provider_delivery_number": "string",
  • "receipt_header": "string",
  • "receipt_customer": "string",
  • "receipt_zvt": "string",
  • "receipt_dealer": "string",
  • "vtc_tid": "string",
  • "vtc_id": "string",
  • "password": "string"
}

Smart Devices

A Smart Device is a device like a POS payment terminal, or an electronic cash register (ECR). You can interconnect such devices with each other (s. Smart Routings), with our systems acting as intermediaries. Every Smart Device belongs to a store (s. General Stores). There are also virtual devices for specific tasks.

Find Smart Devices

Returns the Smart Devices matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 8734,
  • "data": [
    ]
}

Create Smart Device

Creates a new Smart Device from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Smart Device details

merchant
string

Merchant

store
string

Store

device
string

Device

contract
string

Contract

vendor
string

Vendor, examples:

  • ingenico
  • nodis
  • ccv
  • 3pos
  • flour
  • pios
  • shopware
  • loyalty_webterminal
  • android
vendor_uid
string

Vendor uid

type
string

Type:

  • cashier
  • zvt
  • shopmodule
  • webterminal
description
string

Device description

tid
string

TID

object (SmartDevicesProducts)

SmartDevicesProducts

terminal_type
string

Terminal type

base_version
string

Base version

status
string (DeviceStatus)
Enum: "active" "inactive" "deleted" "replaced"

Device status

Responses

Request samples

Content type
application/json
Example
{
  • "merchant_id": "MRC_FMP885SKMIQ6LTZ014C9GA7NKQIP2K",
  • "store": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5",
  • "vendor": "apidevices",
  • "vendor_uid": "/uuid/xxxxxxxxxxxx",
  • "type": "cashier"
}

Response samples

Content type
application/json
Example
{
  • "object": "smart.devices",
  • "id": "SDV_F7T8R23B2P7RVAR5WQWVNP689Z9QTH",
  • "merchant": {
    },
  • "store": {
    },
  • "vendor": "apidevices",
  • "vendor_uid": "/uuid/xxxxxxxxxxxx",
  • "type": "cashier",
  • "description": null,
  • "status": "active",
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "refresh": 0,
  • "connection_type": null
}

Read Smart Device

Returns the specified Smart Device.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart device id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "smart.devices",
  • "id": "SDV_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "merchant": {
    },
  • "store": {
    },
  • "vendor": "shopware",
  • "vendor_uid": "/uuid/xxxxxxxxxxxx",
  • "type": "cashier",
  • "description": "Shopware Shop",
  • "device": {
    },
  • "user_pin": "XXXXXXXX",
  • "products": {
    },
  • "status": "active",
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "refresh": 0,
  • "connection_type": null,
  • "online": false
}

Update Smart Device

Updates the specified Smart Device with the given data.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID

Request Body schema: application/json

Smart device properties

merchant
string

Merchant

store
string

Store

device
string

Device

contract
string

Contract

vendor
string

Vendor, examples:

  • ingenico
  • nodis
  • ccv
  • 3pos
  • flour
  • pios
  • shopware
  • loyalty_webterminal
  • android
vendor_uid
string

Vendor uid

type
string

Type:

  • cashier
  • zvt
  • shopmodule
  • webterminal
description
string

Device description

tid
string

TID

object (SmartDevicesProducts)

SmartDevicesProducts

terminal_type
string

Terminal type

base_version
string

Base version

status
string (DeviceStatus)
Enum: "active" "inactive" "deleted" "replaced"

Device status

Responses

Request samples

Content type
application/json
Example
{
  • "products": {
    }
}

Response samples

Content type
application/json
Example
{
  • "object": "smart.devices",
  • "id": "SDV_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "merchant": {
    },
  • "store": {
    },
  • "vendor": "apidevices",
  • "vendor_uid": "/uuid/xxxxxxxxxxxx",
  • "type": "cashier",
  • "description": "Kasse Store XYZ",
  • "products": {
    },
  • "status": "active",
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "refresh": 0,
  • "connection_type": null
}

Get with routing

Returns the specified Smart Device if it is assigned to a routing.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID

type
required
string

Smart Device type:

  • cashier
  • zvt
  • shopmodule
  • webterminal

Responses

Response samples

Content type
application/json
{
  • "object": "smart.devices",
  • "id": "SDV_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "merchant": {
    },
  • "store": {
    },
  • "vendor": "ingenico",
  • "vendor_uid": "/serial/xxxxxxxxxxxx",
  • "type": "zvt",
  • "description": "Terminal Filiale XY",
  • "device": {
    },
  • "user_pin": "XXXXXXXX",
  • "products": {
    },
  • "status": "active",
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "routing": {
    },
  • "refresh": 0,
  • "connection_type": null,
  • "online": false
}

Set device PIN

Sets the PIN that needs to be passed to authenticate the Smart Device.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID

Request Body schema: application/json
user_pin
string

PIN / user code from authentication response

Responses

Request samples

Content type
application/json
{
  • "user_pin": "6vfgr9qz"
}

Response samples

Content type
application/json
{
  • "object": "smart.devices",
  • "id": "SDV_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "merchant": {
    },
  • "store": {
    },
  • "vendor": "ingenico",
  • "vendor_uid": "/serial/xxxxxxxxxxxx",
  • "type": "zvt",
  • "description": "Terminal Filiale XY",
  • "device": {
    },
  • "user_pin": "XXXXXXXX",
  • "products": {
    },
  • "status": "active",
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "refresh": 0,
  • "connection_type": null
}

Update device PIN

Sets the device PIN at merchant, store or device level. The device PIN must be passed to authenticate the Smart Device.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID, or any other value when the PIN is set at store or merchant level

Request Body schema: application/json
store_id
string or null

General Stores ID

merchant_id
required
string

General Merchants ID

pin
required
string

The pin to store

Responses

Request samples

Content type
application/json
{
  • "merchant_id": "MRC_FMP885SKMIQ6LTZ014C9GA7NKQIP2K",
  • "store_id": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5",
  • "pin": "zoj8AosJgfgLi1o7BD1M74cWhkn8K5"
}

Response samples

Content type
application/json
{
  • "result": true
}

Get device PIN settings

Returns the device PIN settings. This is not the actual PIN, but whether it must be passed on merchant, store or device level.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID

Responses

Response samples

Content type
application/json
{
  • "merchant": {
    },
  • "store": {
    },
  • "smart_device": {
    }
}

Get Smart Device Secubase Config

Returns the Secubase config of the Smart Device.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart Device ID

Request Body schema: application/json

Smart Device properties

secubase_version
string

Secubase version of the Ingenico terminal (C part)

secudroid_version
string

Version of the Android app (Java part)

base_version
string

Lua base app version

terminal_type
string

Terminal model

terminal_id
string

Terminal ID

object (SmartDevicesProductModel)
Default: {}

Smart Device

Responses

Request samples

Content type
application/json
Example
{
  • "base_version": "0.2.5",
  • "secubase_version": "3.0.1-pre.2",
  • "terminal_type": "MOVE5000",
  • "terminal_id": "75352828"
}

Response samples

Content type
application/json
Example
{}

Smart Routings

A routing defines a connection between two Smart ZVT eligible devices (s. Smart Devices). For instance you can flexibly connect electronic cash registers (ECR) with POS payment terminals. Our server can use the same link to trigger ZVT functions for a different purpose, for instance to integrate e-commerce with your point of sale (POS), which is commonly known as cross-channel, omni-channel, or multi-channel.

Find Smart Routings

Returns the Smart Routings matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 148,
  • "data": [
    ]
}

Create Smart Routing

Creates a new Smart Routing from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Smart Routing details

store
string

General Store ID

description
string

Route description

Responses

Request samples

Content type
application/json
{
  • "store": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5",
  • "description": "Kasse 3"
}

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "description": "Kasse 3"
}

Read Smart Routing

Returns the specified Smart Routing.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart Routing ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "description": "Kasse 3"
}

Update Smart Routing

Updates the specified Smart Routing with the given data.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart Routing ID

Request Body schema: application/json

Smart Routing details

store
string

General Store ID

description
string

Route description

Responses

Request samples

Content type
application/json
{
  • "store": "STO_HLNVCU8510FYS1TLUBETKMER3ITZ5C",
  • "description": "Kasse 7"
}

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-16T10:00:00+01:00",
  • "description": "Kasse 7"
}

Delete Smart Routing

Deletes the specified Smart Routing.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart Routing ID

Responses

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-16T10:00:00+01:00",
  • "description": "Kasse 7"
}

Assign Smart Device

Assigns the specified Smart Device to the specified Smart Routing.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart Routing ID

smartDeviceId
required
string

Smart Device ID

Responses

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "description": "Kasse 3",
  • "assign": [
    ]
}

Unassign Smart Device

Unassigns the specified Smart Device from the specified Smart Routing.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart Routing ID

smartDeviceId
required
string

Smart Device ID

Responses

Response samples

Content type
application/json
{
  • "object": "smart.routings",
  • "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO",
  • "merchant": {
    },
  • "store": {
    },
  • "created": "2024-03-15T10:00:00+01:00",
  • "updated": "2024-03-15T10:00:00+01:00",
  • "description": "Kasse 3"
}

Document Uploads

Upload files like logo images, PDFs with legal information, and so on.

Upload File / multipart MIME

Creates a new Docuemt Upload from the given data.

Authorizations:
oauth_token
query Parameters
multipart
string
Request Body schema: application/json

Input data format

file
string <binary>

Responses

Request samples

Content type
application/json
{
  • "file": "/path/to/file.txt"
}

Response samples

Content type
application/json
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "type": "text/plain",
  • "name": "hello.txt",
  • "size": 13
}

Upload File / JSON

Creates a new Document Upload from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Content

content
string

File content as Base64 encoded string

Responses

Request samples

Content type
application/json
{
  • "content": "SGVsbG8sIFdvcmxkIQ=="
}

Response samples

Content type
application/json
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00"
}

Read Document Upload

Returns the specified Document Upload.

Authorizations:
oauth_token
path Parameters
documentUploadsId
required
string
Example: DUP_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH

Document Uploads ID

Responses

Response samples

Content type
application/json
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "type": "text/plain",
  • "name": "hello.txt",
  • "size": 13,
  • "content": "SGVsbG8sIFdvcmxkIQ=="
}

Download uploaded file

Downloads the contents of the specified Document Upload.

Authorizations:
oauth_token
path Parameters
documentUploadsId
required
string
Example: DUP_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH

Document Uploads ID

Responses

Response samples

Content type
"Hello, World!"

Services Upload Idents

Creates an Ident Request, connected with a particular Payment Transaction for payout.

Create Upload Ident

Creates a new Upload Ident from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Upload Ident details

merchant_id
string

Merchant ID

payment_id
string

Payment ID

contract_id
string

Contract ID

apikey
string

Api Key

service_issue_id
integer

Service issue id

document_ids
Array of strings

List of documents ids

Responses

Request samples

Content type
application/json
{
  • "contract_id": "GCR_7GDYFMMJ9SK75P2BJRRN6JA8Y0DSOJ",
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "service_issue_id": 12345678
}

Services Ident Requests

Customer identification request (for KYC checks)

Find Ident Requests

Returns the Ident Requests matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "data": [
    ]
}

Create new Ident Request

Creates a new Ident Request from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Ident Request details

provider
string (IdentProviderValue)

Third party Identification provider:

  • "post_ident",
  • "bank_ident",
  • "webid",
  • "idnow",
  • "post_ident_extern",
  • "3rdParty"
type
string (IdentTypeValue)

Ident type (mostly person)

demo
boolean

Demo Flag

Array of objects (IdentrequestPersonDTO)

The person which should be identified by third party provider

owner_transaction_id
string

Arbitrary ID to identify identrequest on merchant

object or null (IdentrequestRedirectUrls)

Ident Request redirect URLs

Responses

Request samples

Content type
application/json
{
  • "type": "person",
  • "demo": "true",
  • "owner_transaction_id": "tx_1234567890",
  • "person": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "services.identrequests",
  • "id": "SIR_ANP0CG8Z5FVWE5DNH1ZYIPPLD2G09L",
  • "contract": {
    },
  • "type": "person",
  • "provider": "idnow",
  • "status": "requested",
  • "demo": true,
  • "owner_transaction_id": "tx_1234567890",
  • "person": [
    ],
  • "created": "2017-01-26T12:29:27+00:00"
}

Read Ident Request

Returns the specified Ident Request.

Authorizations:
oauth_token
path Parameters
identrequestId
required
string

Ident Request ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "services.identrequests",
  • "id": "SIR_ANP0CG8Z5FVWE5DNH1ZYIPPLD2G09L",
  • "contract": {
    },
  • "type": "person",
  • "provider": "idnow",
  • "status": "requested",
  • "demo": true,
  • "owner_transaction_id": "tx_1234567890",
  • "person": [
    ],
  • "created": "2017-01-26T12:29:27+00:00"
}

Services Ident Results

Detailed results for an Ident Request (ID document, stills or videos, corrected spellings, etc.)

Find Ident Results

Returns the Ident Results matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{}

Read Ident Result

Returns the specified Ident Result.

Authorizations:
oauth_token
path Parameters
identrequestId
required
string

Identresult Id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{}

Cardprocessing Invoices

Card Processing Transactions

Find Card Processing Transactions

Returns the Card Processing Transactions matching the given criteria.

Authorizations:
oauth_token
query Parameters
count
integer
Example: count=20

The maximum number of items to return

offset
integer
Example: offset=0

The position within the whole result set to start returning items (zero-based)

fields
string
Example: fields=prop3,prop1.prop2

List of fields to include in the result, all others will be filtered out. Nested properties can be accessed with this notation: prop1.prop2.

q
string
Example: q=card.cardnumber:92760044

A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. Property names can be nested like property.property.

Example: customer.name:Meier

A condition may contain:

  • ? as wildcard for one character;
  • * as wildcard for any number of characters.

You can also use value ranges in the form [min TO max].

Example: customer.age:[30 TO 40]

You can combine expressions logically by expr AND expr and {expr} OR {expr}. You can also negate an expression using NOT {expr}. Parenthesis (...) can be used to control precedence.

Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])

sort
string
Example: sort=contact.surname:asc,contact.companyname:desc

String with comma separated pairs of field:order.

Options for order:

  • asc ascending;
  • desc descending.
object (Aggregate)

Aggregation summarizes your data.

meta
any
Enum: "true" "only"

return field definitions

validate
any
Value: 1

Check syntax of a query string

scroll_expire
string
Example: scroll_expire=1m

How long it should keep the “search context” alive?

scroll_id
string
Example: scroll_id=DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==

Identifier of a previous search context.

preset
string
Example: preset=own

Query presets

expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "count": 10000,
  • "data": [
    ]
}

Read Card Processing Transaction

Returns the specified Card Processing Transaction.

Authorizations:
oauth_token
path Parameters
cardprocessingTransactionId
required
string

Card Processing Transaction ID

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

Response samples

Content type
application/json
{
  • "object": "cardprocessing.transactions",
  • "id": "PTX_R0AW78IGZB5G6UQNCI9FU15KYDEULB",
  • "merchant": {
    },
  • "store": {
    },
  • "store_name": "Mustershop",
  • "trans_id": 123456789,
  • "tid": "99999999",
  • "end_of_day_date": "2021-05-31T00:00:00+02:00",
  • "end_of_day_id": "09999999999",
  • "amount": 9900,
  • "trace": 999,
  • "receipt_number": "12345",
  • "product": "girocard",
  • "ref_report_id": 99999999,
  • "ref_report_type": 4,
  • "created": "2021-05-30T12:34:56+02:00",
  • "updated": "2021-06-01T12:00:00+02:00"
}

Public Website

Public website details

Get available countries

Returns the available countries.

Authorizations:
oauth_token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]