secuconnect logo
Documentation Powered by ReDoc

Secuconnect API (2.0.0)

Download OpenAPI specification:Download

Authentication

oauth_token

Authorization header with Bearer token

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

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.

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

200

Matching Smart Transactions

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Smart/Transactions

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

provider_contract
object (ProductInstanceUID)

Object type and ID

transactionRef
string

Transaction reference, e.g. merchant order ID

merchantRef
string

Merchant reference, e.g. merchant customer ID

basket
object (SmartTransactionsBasket)

Basket items, several sub-baskets or subscription details

basket_info
object (SmartTransactionsBasketInfo)

Basket information

idents
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

device_source
object (ProductInstanceUID)

Object type and ID

trans_id
integer

Transaction ID (TA code)

contract
object (ProductInstanceID)

Object ID

last_visited_page
string

Last visited page

customer
object (SmartTransactionPaymentCustomerDTO)

Customer details

shipping_address
object (SmartTransactionPaymentCustomerDTO)

Customer details

container
object (SmartTransactionPaymentContainerDTO)

Payment instrument

checkin
object (SmartTransactionsCheckin)

Check-in

is_demo
boolean

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

intent
string

Intent:

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

Checkout URLs

delivery_options
object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

communications
object (SmartTransactionsCommunication)

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

application_context
object (SmartTransactionsApplicationContext)

Controls the integration between Smart Checkout and the shop.

payment_context
object (PaymentContext)

Controls some payment details

Responses

200

Newly created Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions

Request samples

Content type
application/json
Example
Simplistic
Copy
 Expand all Collapse all
{
  • "is_demo": true,
  • "contract":
    {
    },
  • "customer":
    {
    },
  • "basket_info":
    {
    },
  • "application_context":
    {
    }
}

Response samples

Content type
application/json
Example
Simplistic
Copy
 Expand all Collapse all
{}

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

200

Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Smart/Transactions/{smartTransactionId}

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}

Response samples

Content type
application/json
Example
Typical
Copy
 Expand all Collapse all
{}

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

provider_contract
object (ProductInstanceUID)

Object type and ID

transactionRef
string

Transaction reference, e.g. merchant order ID

merchantRef
string

Merchant reference, e.g. merchant customer ID

basket
object (SmartTransactionsBasket)

Basket items, several sub-baskets or subscription details

basket_info
object (SmartTransactionsBasketInfo)

Basket information

idents
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

device_source
object (ProductInstanceUID)

Object type and ID

trans_id
integer

Transaction ID (TA code)

contract
object (ProductInstanceID)

Object ID

last_visited_page
string

Last visited page

customer
object (SmartTransactionPaymentCustomerDTO)

Customer details

shipping_address
object (SmartTransactionPaymentCustomerDTO)

Customer details

container
object (SmartTransactionPaymentContainerDTO)

Payment instrument

checkin
object (SmartTransactionsCheckin)

Check-in

is_demo
boolean

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

intent
string

Intent:

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

Checkout URLs

delivery_options
object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

communications
object (SmartTransactionsCommunication)

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

application_context
object (SmartTransactionsApplicationContext)

Controls the integration between Smart Checkout and the shop.

payment_context
object (PaymentContext)

Controls some payment details

Responses

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Smart/Transactions/{smartTransactionId}

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}

Request samples

Content type
application/json
Example
Customer
Copy
 Expand all Collapse all
{
  • "is_demo": true,
  • "contract":
    {
    },
  • "customer":
    {
    },
  • "basket_info":
    {
    }
}

Response samples

Content type
application/json
Example
Customer
Copy
 Expand all Collapse all
{}

Cancel payment

Cancels the Smart Transaction.

Authorizations:
oauth_token
path Parameters
smartTransactionId
required
string
Example: STX_2ZVEFT7YV2P6BNCP8QNQ66N4GEA0AK

Smart Transaction ID

Responses

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/cancel

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/cancel

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/cancel

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/cancel

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

customer
object (SmartTransactionPaymentCustomerDTO)

Customer details

container
object (SmartTransactionPaymentContainerDTO)

Payment instrument

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

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

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

405

Payment method not available, or capture not possible or failed

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/start/{paymentMethod}

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/start/{paymentMethod}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/start/{paymentMethod}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/start/{paymentMethod}

Request samples

Content type
application/json
Example
Already authorized
Copy
 Expand all Collapse all
{ }

Response samples

Content type
application/json
Example
Credit card
Copy
 Expand all Collapse all
{
  • "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",
  • "intent": "sale",
  • "basket_info":
    {
    },
  • "payment_method": "creditcard",
  • "trans_id": 73323994,
  • "is_demo": true,
  • "application_context":
    {},
  • "payment_context":
    {
    }
}

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

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/canceltrx

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/canceltrx

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/canceltrx

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/canceltrx

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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",
  • "intent": "sale",
  • "basket":
    {
    },
  • "basket_info":
    {
    },
  • "payment_method": "cash",
  • "trans_id": 55679607,
  • "is_demo": true,
  • "receipt_number": 3,
  • "payment_context":
    {
    }
}

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

200

Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartDeviceId}/diagnosis

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartDeviceId}/diagnosis

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartDeviceId}/diagnosis

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartDeviceId}/diagnosis

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
    [
    ]
}

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

200

Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartDeviceId}/endOfDay

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartDeviceId}/endOfDay

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartDeviceId}/endOfDay

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartDeviceId}/endOfDay

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
    [
    ]
}

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

200

Missing sum and bonus items

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/preTransaction

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/preTransaction

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/preTransaction

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/preTransaction

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

customer
object (SmartTransactionPaymentCustomerDTO)

Customer details

container
object (SmartTransactionPaymentContainerDTO)

Payment instrument

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

email
string

Email address

Responses

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

405

Payment method not available, approval failed, or auto-capture failed

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/prepare/{paymentMethod}

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/prepare/{paymentMethod}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/prepare/{paymentMethod}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/prepare/{paymentMethod}

Request samples

Content type
application/json
Example
Credit card
Copy
 Expand all Collapse all
{
  • "container":
    {
    },
  • "callback_urls":
    {}
}

Response samples

Content type
application/json
Example
Credit card
Copy
 Expand all Collapse all
{}

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

delivery_options
object (OneOfSmartTransactionsDeliveryOptionsModel)

Delivery options, either for shipping or collection

Responses

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/setDelivery

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/setDelivery

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/setDelivery

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/setDelivery

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "delivery_options":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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",
  • "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

200

Updated Smart Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{smartTransactionId}/abort

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{smartTransactionId}/abort

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/abort

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{smartTransactionId}/abort

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Newly created Smart Transaction for the new authorization

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Transactions/{subscriptionId}/updatePaymentContainer

Production environment

https://connect.secucard.com/api/v2/Smart/Transactions/{subscriptionId}/updatePaymentContainer

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Transactions/{subscriptionId}/updatePaymentContainer

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Transactions/{subscriptionId}/updatePaymentContainer

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Matching General Merchants

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/General/Merchants

Production environment

https://connect.secucard.com/api/v2/General/Merchants

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Merchants

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Merchants

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

General Merchant

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Merchants/{generalMerchantId}

Production environment

https://connect.secucard.com/api/v2/General/Merchants/{generalMerchantId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

legal_details
Array of objects (GeneralMerchantsLegalDetailsDTO) Nullable

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

urls
Array of objects (GeneralMerchantsUrls) Nullable

Return URLs

Responses

200

Updated General Merchant

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/General/Merchants/{generalMerchantId}

Production environment

https://connect.secucard.com/api/v2/General/Merchants/{generalMerchantId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "legal_details":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

General Merchant's public data

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Merchants/{generalMerchantId}/getPublicData/{generalContractId}

Production environment

https://connect.secucard.com/api/v2/General/Merchants/{generalMerchantId}/getPublicData/{generalContractId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}/getPublicData/{generalContractId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Merchants/{generalMerchantId}/getPublicData/{generalContractId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Available Merchants Categories

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Merchants/me/MerchantCategories

Production environment

https://connect.secucard.com/api/v2/General/Merchants/me/MerchantCategories

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Merchants/me/MerchantCategories

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Merchants/me/MerchantCategories

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

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

200

Matching General Contracts

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/General/Contracts

Production environment

https://connect.secucard.com/api/v2/General/Contracts

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

General Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Contracts/{generalContractId}

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

checkout_configuration
object (CheckoutConfiguration)

General checkout settings

Responses

200

Updated General Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/General/Contracts/{generalContractId}

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "checkout_configuration":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

checkout_configuration
object (CheckoutConfiguration)

General checkout settings

Responses

200

Updated General Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

patch/General/Contracts/{generalContractId}

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "checkout_configuration":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Balance for each currency

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Contracts/{generalContractId}/transferBalance

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/transferBalance

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/transferBalance

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/transferBalance

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable

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

Responses

200

Payment methods for particular Smart Transactions

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/getAvailablePaymentMethods/{smartTransactionId}

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods/{smartTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods/{smartTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods/{smartTransactionId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_demo": true,
  • "currency": "EUR"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "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

200

Third party configuration

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

paypal
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

easycredit
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

saferpay
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

Responses

200

Third party configuration

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "paypal":
    {
    },
  • "easycredit":
    {
    },
  • "saferpay":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

paypal
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

easycredit
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

saferpay
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

Responses

200

Third party configuration

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "paypal":
    {
    },
  • "easycredit":
    {
    },
  • "saferpay":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

paypal
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

easycredit
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

saferpay
object (ThirdPartyEnvironmentDTO) Nullable

Third-Party environment settings

Responses

200

Third party configuration

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

patch/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "paypal":
    {
    },
  • "easycredit":
    {
    },
  • "saferpay":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable
Default: null
Example: paypal

Third party name:

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

Responses

200

Third party configuration

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/General/Contracts/{generalContractId}/ThirdPartyConfiguration/{thirdPartyName}

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration/{thirdPartyName}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration/{thirdPartyName}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/ThirdPartyConfiguration/{thirdPartyName}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable

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

Responses

200

Payment methods for contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/getAvailablePaymentMethods

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/getAvailablePaymentMethods

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_demo": true,
  • "currency": "EUR"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "$ref": "#/components/examples/GeneralContractsGetAvailablePaymentMethodsResponse/value"
}

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

202

Request accepted

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/revokeAccrual

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/revokeAccrual

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/revokeAccrual

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/revokeAccrual

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Success

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/terminate

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/terminate

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/terminate

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/terminate

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

background
object (BackgroundImageOption)

BackgroundImageOption

Responses

200

Updated General Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/savePaymentLinkConfiguration

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/savePaymentLinkConfiguration

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/savePaymentLinkConfiguration

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/savePaymentLinkConfiguration

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Iframe options

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Contracts/{generalContractId}/IframeOptions

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/IframeOptions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/IframeOptions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/IframeOptions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Available currencies

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Contracts/{generalContractId}/AvailableCurrencies

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/AvailableCurrencies

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/AvailableCurrencies

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/AvailableCurrencies

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "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 Nullable

Bank name

Responses

200

Whether successful or not

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Contracts/{generalContractId}/updateBankAccount

Production environment

https://connect.secucard.com/api/v2/General/Contracts/{generalContractId}/updateBankAccount

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/updateBankAccount

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Contracts/{generalContractId}/updateBankAccount

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching General Stores

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/General/Stores

Production environment

https://connect.secucard.com/api/v2/General/Stores

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Stores

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Stores

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

address
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

open_hours
Array of objects (OpenHours)

Opening hours per weekday

Responses

200

Newly created General Store

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/General/Stores

Production environment

https://connect.secucard.com/api/v2/General/Stores

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Stores

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Stores

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

General Store

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/General/Stores/{generalStoreId}

Production environment

https://connect.secucard.com/api/v2/General/Stores/{generalStoreId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Stores/{generalStoreId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Stores/{generalStoreId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

address
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

open_hours
Array of objects (OpenHours)

Opening hours per weekday

Responses

200

Updated General Store

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/General/Stores/{generalStoreId}

Production environment

https://connect.secucard.com/api/v2/General/Stores/{generalStoreId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Stores/{generalStoreId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Stores/{generalStoreId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Musterstadt Muster-Center"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Whether it was successful

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/General/Stores/{generalStoreId}/setDefault

Production environment

https://connect.secucard.com/api/v2/General/Stores/{generalStoreId}/setDefault

Testing environment

https://connect-testing.secupay-ag.de/api/v2/General/Stores/{generalStoreId}/setDefault

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/General/Stores/{generalStoreId}/setDefault

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "reason": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "result": true
}

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

200

Matching Payment Transactions

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable

Payment methods.

  • "twint"
order_id
string

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

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

customer
object (PaymentCustomersProductModel)
Default: {}

Customer details

redirect_url
object (SecupayRedirectUrl)

SecupayRedirectUrl

contract
string

Contract ID

container
string

Container ID

opt_data
object

Options for customizing the checkout page

subscription
object (SecupayTransactionProductDTOSubscription)

Recurring payments

demo
boolean

Demo mode

experience
object

Customer experience score

Responses

200

Newly created Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
Copy
 Expand all Collapse all
{
  • "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

200

Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions/{paymentTransactionId}

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}

Response samples

Content type
application/json
Example
Debit with a partial refund
Copy
 Expand all Collapse all
{
  • "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

Capture an open Payment Transaction

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.

shipping_information
object (SecupayTransactionSetShippingInformationDTO)

SecupayTransactionSetShippingInformationDTO

Responses

200

Updated Payment Transaction

default

Response related to the error

post/Payment/Transactions/{paymentTransactionId}/capture

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/capture

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/capture

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/capture

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "platform":
    {
    },
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "trans_id": 0,
  • "parents":
    [
    ],
  • "related_transactions":
    [
    ],
  • "subscription":
    {
    },
  • "product_id": 0,
  • "product": "string",
  • "product_raw": "string",
  • "zahlungsmittel_id": 0,
  • "contract_id": 0,
  • "amount": 1995,
  • "currency": "EUR",
  • "completion_date": "2020-09-04T18:09:51+02:00",
  • "description": "string",
  • "description_raw": "string",
  • "status": 0,
  • "status_text": "string",
  • "incoming_payment_date": "string",
  • "details":
    {
    },
  • "customer":
    {
    },
  • "tid": "string",
  • "payment_data": "string",
  • "store_name": "string",
  • "payout_date": "string",
  • "invoice_number": "string",
  • "transaction_hash": "string",
  • "reference_id": "string",
  • "incoming_payment_purpose": "string",
  • "incoming_payment_iban": "string",
  • "incoming_payment_bic": "string",
  • "account_owner": "string",
  • "accrual": true,
  • "order_id": "string",
  • "transmitted_to_bank": true,
  • "documents":
    [
    ]
}

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

200

Updated Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions/{paymentTransactionId}/cancel

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/cancel

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/cancel

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/cancel

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

Shipping URL

Returns the URL to file the shipping information. This works only with invoice payment, and requires the Payment Transaction has status 85, "Kauf auf Rechnung genehmigt".

See also PUT /Payment/Transactions/{id}/ShippingInformation, Add shipping information, to add the data programmatically.

Authorizations:
oauth_token
path Parameters
paymentTransactionId
required
string

Payment Transaction ID

Responses

200

URL of shipping information form

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions/{paymentTransactionId}/shippingUrl

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/shippingUrl

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/shippingUrl

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/shippingUrl

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Updated Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

405

Accrual change not allowed

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions/{paymentTransactionId}/revokeAccrual

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/revokeAccrual

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/revokeAccrual

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/revokeAccrual

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Instructions

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions/{paymentTransactionId}/getPaymentInstructions

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/getPaymentInstructions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/getPaymentInstructions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/getPaymentInstructions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Instructions

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

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

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/me/getPaymentInstructions/{smartTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/me/getPaymentInstructions/{smartTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/me/getPaymentInstructions/{smartTransactionId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Transaction in old format

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions/{paymentTransactionId}/OldFormat

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/OldFormat

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/OldFormat

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/OldFormat

Response samples

Content type
application/json
Example
Credit card
Copy
 Expand all Collapse all
{
  • "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

200

Crowd funding summary

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions/me/CrowdFundingData/{generalMerchantId}

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/me/CrowdFundingData/{generalMerchantId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/me/CrowdFundingData/{generalMerchantId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/me/CrowdFundingData/{generalMerchantId}

Response samples

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

Add shipping information

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

200

Whether it was successful

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

405

Shipping information update not allowed

500

Validation errors, etc.

default

Other errors

put/Payment/Transactions/{paymentTransactionId}/ShippingInformation

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/ShippingInformation

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/ShippingInformation

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/ShippingInformation

Request samples

Content type
application/json
Example
Minimal
Copy
 Expand all Collapse all
{
  • "order_id": "ORD-56324"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "result": true
}

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

200

Updated Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions/{paymentTransactionId}/IncreaseAmount

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/IncreaseAmount

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/IncreaseAmount

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/IncreaseAmount

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 14000
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Status and actual amount

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Transactions/{paymentTransactionId}/checkStatus

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/checkStatus

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/checkStatus

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/checkStatus

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Updated Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Transactions/{paymentTransactionId}/assignTransferBalance

Production environment

https://connect.secucard.com/api/v2/Payment/Transactions/{paymentTransactionId}/assignTransferBalance

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/assignTransferBalance

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Transactions/{paymentTransactionId}/assignTransferBalance

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
    {
    }
}

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

200

Matching Payment Customers

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Customers

Production environment

https://connect.secucard.com/api/v2/Payment/Customers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Customers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Customers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

contact
object (Contact)

Contact details

Responses

200

Newly created Payment Customer

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Payment/Customers

Production environment

https://connect.secucard.com/api/v2/Payment/Customers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Customers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Customers

Request samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "contact":
    {
    }
}

Response samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "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

200

Payment Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Customers/{paymentCustomerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Customers/{paymentCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Response samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "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

contact
object (Contact)

Contact details

Responses

200

Updated Payment Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Payment/Customers/{paymentCustomerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Customers/{paymentCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Request samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "contact":
    {
    }
}

Response samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "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

200

Deleted Payment Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Payment/Customers/{paymentCustomerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Customers/{paymentCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Customers/{paymentCustomerId}

Response samples

Content type
application/json
Example
Personal address
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Payment Containers

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Containers

Production environment

https://connect.secucard.com/api/v2/Payment/Containers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable

General Merchant ID

customer
object Nullable
Deprecated

The customer the Payment Container belongs to

customer_id
string Nullable

Payment Customer ID

type
string

Container type:

  • "bank_account"
  • "credit_card" (read-only)
  • "googlepay"
  • "applepay"
  • "paypal" (read-only)
private
object (OneOfPaymentContainersDTOModelPrivate)

Payment instrument data

  • BankAccountDescriptor
  • CreditCardDescriptor
  • GooglePayDescriptor
  • ApplePayDescriptor
  • PayPalDescriptor

Responses

200

Newly created Payment Container

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Payment/Containers

Production environment

https://connect.secucard.com/api/v2/Payment/Containers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers

Request samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "type": "bank_account",
  • "private":
    {
    }
}

Response samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "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

200

Payment Container

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Containers/{paymentContainerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Containers/{paymentContainerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Response samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "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 Nullable

General Merchant ID

customer
object Nullable
Deprecated

The customer the Payment Container belongs to

customer_id
string Nullable

Payment Customer ID

type
string

Container type:

  • "bank_account"
  • "credit_card" (read-only)
  • "googlepay"
  • "applepay"
  • "paypal" (read-only)
private
object (OneOfPaymentContainersDTOModelPrivate)

Payment instrument data

  • BankAccountDescriptor
  • CreditCardDescriptor
  • GooglePayDescriptor
  • ApplePayDescriptor
  • PayPalDescriptor

Responses

200

Updated Payment Container

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Payment/Containers/{paymentContainerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Containers/{paymentContainerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Request samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "type": "bank_account",
  • "private":
    {
    }
}

Response samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "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

200

Deleted Payment Container

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Payment/Containers/{paymentContainerId}

Production environment

https://connect.secucard.com/api/v2/Payment/Containers/{paymentContainerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}

Response samples

Content type
application/json
Example
Bank account
Copy
 Expand all Collapse all
{
  • "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

200

Mandate form URL

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Containers/{paymentContainerId}/mandate

Production environment

https://connect.secucard.com/api/v2/Payment/Containers/{paymentContainerId}/mandate

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}/mandate

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}/mandate

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "customer_id": "PCU_R2K5GTBAR2P5D8S76678M6XS0FYMAJ",
  • "type": "B2B"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Service case number

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Containers/{paymentContainerId}/Uploadmandate

Production environment

https://connect.secucard.com/api/v2/Payment/Containers/{paymentContainerId}/Uploadmandate

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}/Uploadmandate

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Containers/{paymentContainerId}/Uploadmandate

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "document_id": "DUP_E59X474K1P83O7K516ETYWUBSWDUJB"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "service_issue_id": 2875433
}

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

200

Matching Payment Contracts

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Contracts

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Contracts/{paymentContractId}

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment methods possible for given contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Contracts/{paymentContractId}/paymentMethods

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}/paymentMethods

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/paymentMethods

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/paymentMethods

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "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)

payment_data
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

200

Updated payment contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Contracts/{paymentContractId}/clone

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}/clone

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/clone

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/clone

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

Clone contract and 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

contact
object (Contact)

Contact details

project
string

Project name (must be unique)

payout_account
object (PaymentInformation)

Bank details

payment_data
object (PaymentInformation)

Bank details

iframe_opts
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"

Pay-in account

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 .,+\-:?()\/\']+/

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_...)

additional_data
object (PaymentContractsDTORequestIdAdditionalData)

Additional data input

notes
string

Additional notes

invoice_reference
string

Reference-Text from Inputfield

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 /pai/v2/General/Merchants/me/MerchantCategories.

account_statement_text
string

Descriptor that appears at the credit card statements

Responses

200

New Payment Contract

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Contracts/{paymentContractId}/requestId

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}/requestId

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/requestId

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/requestId

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

202

Payload accepted, revoke accrual flag is done in background

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Contracts/{paymentContractId}/revokeAccrual

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}/revokeAccrual

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/revokeAccrual

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/revokeAccrual

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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 Nullable

Bank name

Responses

200

Returns that the request was successful

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Contracts/{paymentContractId}/updateBankAccount

Production environment

https://connect.secucard.com/api/v2/Payment/Contracts/{paymentContractId}/updateBankAccount

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/updateBankAccount

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Contracts/{paymentContractId}/updateBankAccount

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Secupaypayout/{paymentPayoutId}

Production environment

https://connect.secucard.com/api/v2/Payment/Secupaypayout/{paymentPayoutId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Secupaypayout/{paymentPayoutId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Secupaypayout/{paymentPayoutId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

redirect_url
object (SecupayRedirectUrl)

SecupayRedirectUrl

contract
string

General Contract ID

customer
object (PaymentCustomersProductModel)
Default: {}

Customer details

opt_data
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

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.

transaction_list
Array of objects (SecupayTransactionListItem)

Payout items

Responses

200

Newly created payout transaction

401

Missing or invalid token

403

Not logged in or no contract

405

Payment method not available

500

Validation errors, etc.

default

Other errors

post/Payment/Secupaypayout

Production environment

https://connect.secucard.com/api/v2/Payment/Secupaypayout

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Secupaypayout

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Secupaypayout

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
Copy
 Expand all Collapse all
{
  • "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

payout_list
Array of objects (SecupayPayoutListItem)

Payout items

purpose
string

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

200

Newly created payout transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Payment/Secupaypayout/me/PayoutWithoutCustomer

Production environment

https://connect.secucard.com/api/v2/Payment/Secupaypayout/me/PayoutWithoutCustomer

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Secupaypayout/me/PayoutWithoutCustomer

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Secupaypayout/me/PayoutWithoutCustomer

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Payment Payouts

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Payouts

Production environment

https://connect.secucard.com/api/v2/Payment/Payouts

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Payouts

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Payouts

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Payment Payout

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Payouts/{paymentPayoutId}

Production environment

https://connect.secucard.com/api/v2/Payment/Payouts/{paymentPayoutId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Payouts/{paymentPayoutId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Payouts/{paymentPayoutId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Matching Payment Invoices

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Invoices

Production environment

https://connect.secucard.com/api/v2/Payment/Invoices

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Invoices

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Invoices

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Invoice

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Invoices/{paymentInvoiceId}

Production environment

https://connect.secucard.com/api/v2/Payment/Invoices/{paymentInvoiceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Invoices/{paymentInvoiceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Invoices/{paymentInvoiceId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Payment Plans

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Plans

Production environment

https://connect.secucard.com/api/v2/Payment/Plans

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Plans

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Plans

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
merchant
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

billing_cycles
Array of objects (BillingCyclesItem)

Billing cycles

Responses

200

Newly created Payment Plan

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Payment/Plans

Production environment

https://connect.secucard.com/api/v2/Payment/Plans

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Plans

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Plans

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
Copy
 Expand all Collapse all
{
  • "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

200

Payment Plan

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Plans/{paymentPlanId}

Production environment

https://connect.secucard.com/api/v2/Payment/Plans/{paymentPlanId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
merchant
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

billing_cycles
Array of objects (BillingCyclesItem)

Billing cycles

Responses

200

Updated Payment Plan

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Payment/Plans/{paymentPlanId}

Production environment

https://connect.secucard.com/api/v2/Payment/Plans/{paymentPlanId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
Copy
 Expand all Collapse all
{
  • "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"
merchant
object (GeneralMerchantsProductModel)
Default: {}

GeneralMerchantsProductModel

merchant_id
string

General Merchant ID

billing_cycles
Array of objects (BillingCyclesItem)

Billing cycles

Responses

200

Updated Payment Plan

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

patch/Payment/Plans/{paymentPlanId}

Production environment

https://connect.secucard.com/api/v2/Payment/Plans/{paymentPlanId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Plans/{paymentPlanId}

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Payment Subscriptions

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Payment/Subscriptions

Production environment

https://connect.secucard.com/api/v2/Payment/Subscriptions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Subscriptions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Subscriptions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Payment Subscription

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Payment/Subscriptions/{paymentSubscriptionId}

Production environment

https://connect.secucard.com/api/v2/Payment/Subscriptions/{paymentSubscriptionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Payment/Subscriptions/{paymentSubscriptionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Payment/Subscriptions/{paymentSubscriptionId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Loyalty Transactions

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Loyalty/Transactions

Production environment

https://connect.secucard.com/api/v2/Loyalty/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Transactions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Loyalty Transaction

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/Transactions/{loyaltyTransactionId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Transactions/{loyaltyTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Transactions/{loyaltyTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Transactions/{loyaltyTransactionId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Loyalty Customers

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Loyalty/Customers

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

merchant_contact
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

Responses

200

Newly created Loyalty Customer

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Loyalty/Customers

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Loyalty Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/Customers/{loyaltyCustomerId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

merchant_contact
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

Responses

200

Updated Loyalty Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Loyalty/Customers/{loyaltyCustomerId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "merchant_contact":
    {
    },
  • "consent_for_communication": "accepted"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Updated Loyalty Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Updated Loyalty Customer

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Customers/{loyaltyCustomerId}/assignPaymentContainer/{loyaltyPaymentContainerId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Loyalty Cards

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Loyalty/Cards

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cards

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cards

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cards

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Loyalty Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/Cards/{loyaltyCardId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cards/{loyaltyCardId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Whether it was successfully assigned

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "pin": "9867"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Whether it was successfully detached

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cards/{loyaltyCardId}/assignUser/{generalAccountId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Loyalty Card Groups

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Loyalty/Cardgroups

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cardgroups

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cardgroups

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cardgroups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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 Nullable

Document Upload ID of symbol image

merchant
required
string

General Merchant ID

Responses

200

Newly created Loyalty Card Group

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Loyalty/Cardgroups

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cardgroups

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cardgroups

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cardgroups

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Loyalty Card Group

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/Cardgroups/{loyaltyCardGroupId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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 Nullable

Document Upload ID of symbol image

Responses

200

Updated Loyalty Card Group

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Loyalty/Cardgroups/{loyaltyCardGroupId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Whether passcode is needed (true) or not (false)

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/Cardgroups/{loyaltyCardGroupId}/checkPasscodeEnabled

Production environment

https://connect.secucard.com/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}/checkPasscodeEnabled

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}/checkPasscodeEnabled

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/Cardgroups/{loyaltyCardGroupId}/checkPasscodeEnabled

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Loyalty Merchant Cards

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Loyalty/MerchantCards

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

merchant
string

General merchant id

card
string

Loyalty Card ID

payment_container
string

Loyalty Payment Container ID

created_by_merchant
boolean

Whether the card was created by the merchant

used_by_merchant
boolean

Whether the card was used by the merchant

Responses

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Loyalty/MerchantCards/{loyaltyMerchantCardId}/cardgroup/{loyaltyCardGroupId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/cardgroup/{loyaltyCardGroupId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/cardgroup/{loyaltyCardGroupId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/cardgroup/{loyaltyCardGroupId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

merchant_contact
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

Responses

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/registerCustomer

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/registerCustomer

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/registerCustomer

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/registerCustomer

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/setCustomer/{loyaltyCustomerId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/setCustomer/{loyaltyCustomerId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/setCustomer/{loyaltyCustomerId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/setCustomer/{loyaltyCustomerId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Lock details

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Response samples

Content type
application/json
Example
Locked
Copy
 Expand all Collapse all
{
  • "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

lock_status
string

Lock status:

  • "locked"
  • "unlocked"
reason
integer

Lock reason:

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

Human readable note

Responses

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/lock

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

Responses

200

Updated Loyalty Merchant Card

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/unlock

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/unlock

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/unlock

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/unlock

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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

200

Virtual terminal details

201

Disabled

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Loyalty/MerchantCards/{loyaltyMerchantCardId}/virtualTerminalData/{loyaltyMerchantId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/virtualTerminalData/{loyaltyMerchantId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/virtualTerminalData/{loyaltyMerchantId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/virtualTerminalData/{loyaltyMerchantId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Execute transaction

Executes a loyalty transaction. Intended to by used from SDK.

Authorizations:
oauth_token
path Parameters
loyaltyMerchantCardId
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
integer

Number on card

bonus_amount
integer

Bonus amount

amount_split_allowed
string

Whether amount split is allowed

merchant_id
string

General Merchant ID

Responses

200

Merchant Card details incl. receipt

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/transaction

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/transaction

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/transaction

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/transaction

Request samples

Content type
application/json
Example
Charge
Copy
 Expand all Collapse all
{
  • "action": "charge",
  • "amount": 100,
  • "bonus_amount": 100,
  • "tid": "VT003456"
}

Response samples

Content type
application/json
Example
Charge
Copy
 Expand all Collapse all
{
  • "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": 1,
  • "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
integer

Number on card

csc
integer

Entered Card Security Code

Responses

200

Whether the CSC is good (true) or not (false)

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkCsc

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkCsc

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkCsc

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkCsc

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
integer

Number on card

Responses

200

Card validation details

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/validateMerchantcard

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/validateMerchantcard

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/validateMerchantcard

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/validateMerchantcard

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

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
integer

Number on card

passcode
integer

Passcode

Responses

200

Whether the new passcode was saved

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/newPasscode

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/newPasscode

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/newPasscode

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/newPasscode

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
integer

Number on card

passcode
integer

Old passcode

Responses

200

Whether the passcode restore has been started (true) or not (false)

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/resetPasscode

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/resetPasscode

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/resetPasscode

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/resetPasscode

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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
integer

Number on card

pin
integer

Entered passcode

Responses

200

Whether the passcode matches (true) or not (false)

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkPasscode

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkPasscode

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkPasscode

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/checkPasscode

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "value":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

customer
object (LoyaltyMerchantcardsDTOCustomer)

LoyaltyMerchantcardsDTOCustomer

Responses

200

Loyalty Merchant Cards

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{generalMerchantId}/createMerchantcards/{loyaltyCardgroupId}

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{generalMerchantId}/createMerchantcards/{loyaltyCardgroupId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{generalMerchantId}/createMerchantcards/{loyaltyCardgroupId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{generalMerchantId}/createMerchantcards/{loyaltyCardgroupId}

Request samples

Content type
application/json
Example
One personal card
Copy
 Expand all Collapse all
{
  • "cards_amount": 1,
  • "customer":
    {
    }
}

Response samples

Content type
application/json
Example
One personal card
Copy
 Expand all Collapse all
[
  • {
    }
]

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
integer

Number on card

terminal_id
string

Terminal ID

Responses

200

Balance receipt and some card details

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Loyalty/MerchantCards/{loyaltyMerchantCardId}/getCardBalanceReceipt

Production environment

https://connect.secucard.com/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/getCardBalanceReceipt

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/getCardBalanceReceipt

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Loyalty/MerchantCards/{loyaltyMerchantCardId}/getCardBalanceReceipt

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "cardnumber": 0,
  • "terminal_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "valid": true,
  • "balance": 0,
  • "points": 0,
  • "new_passcode": true,
  • "receipt_header":
    [
    ],
  • "receipt":
    [
    ],
  • "amount_split_enabled": true,
  • "limit_allowed": true,
  • "limit_str": "string",
  • "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

200

Prepaid item, or result false

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Prepaid/Contracts/{prepaidContractId}/mappingZvt

Production environment

https://connect.secucard.com/api/v2/Prepaid/Contracts/{prepaidContractId}/mappingZvt

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Contracts/{prepaidContractId}/mappingZvt

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Contracts/{prepaidContractId}/mappingZvt

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 1500,
  • "product_id": "0000000123456789"
}

Response samples

Content type
application/json
Example
Match
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Prepaid Items

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Prepaid/Items

Production environment

https://connect.secucard.com/api/v2/Prepaid/Items

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Items

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Items

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Prepaid Item

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Prepaid/Items/{prepaidItemId}

Production environment

https://connect.secucard.com/api/v2/Prepaid/Items/{prepaidItemId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Items/{prepaidItemId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Items/{prepaidItemId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Returns a list of prepaid Reports

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Prepaid/Reports

Production environment

https://connect.secucard.com/api/v2/Prepaid/Reports

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Reports

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Reports

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 45,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Create Prepaid Report

Creates a new Prepaid Report from the given data.

Authorizations:
oauth_token
Request Body schema: application/json
merchant
required
string

General Merchants ID

store
required
string

General Stores ID

smart_device
required
string

Smart Devices ID

vtc_tid
required
integer

VTC TID

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

200

Returns generated Prepaid Report

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Prepaid/Reports

Production environment

https://connect.secucard.com/api/v2/Prepaid/Reports

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Reports

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Reports

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "merchant": "MRC_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "store": "STO_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "smart_device": "SDV_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "vtc_tid": 0,
  • "report_from": "2020-09-04T18:09:51+02:00",
  • "report_to": "2020-09-04T18:09:51+02:00"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "string",
  • "id": "string",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "device":
    {
    },
  • "amount": 1995,
  • "vtc_tid": 0,
  • "report_from": "string",
  • "report_to": "string",
  • "receipt":
    [
    ],
  • "receipt_header":
    [
    ]
}

Read Prepaid Report

Returns the specified Prepaid Report.

Authorizations:
oauth_token
path Parameters
prepaidReportsId
required
object (ProductInstanceUID)

Prepaid Reports id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

200

Returns prepaid Report for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Prepaid/Reports/{prepaidReportsId}

Production environment

https://connect.secucard.com/api/v2/Prepaid/Reports/{prepaidReportsId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Reports/{prepaidReportsId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Reports/{prepaidReportsId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "string",
  • "id": "string",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "device":
    {
    },
  • "amount": 1995,
  • "vtc_tid": 0,
  • "report_from": "string",
  • "report_to": "string",
  • "receipt":
    [
    ],
  • "receipt_header":
    [
    ]
}

Prepaid Sales

Prepaid transactions

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

200

Returns a list of prepaid sales

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Prepaid/Sales

Production environment

https://connect.secucard.com/api/v2/Prepaid/Sales

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Sales

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Sales

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 45,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Create Prepaid Sale

Creates a new Prepaid Sale from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Prepaid transaction input properties

item
string

prepaid sales transaction id

Responses

200

Created new prepaid transaction

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Prepaid/Sales

Production environment

https://connect.secucard.com/api/v2/Prepaid/Sales

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Sales

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Sales

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "item": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

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

200

Returns prepaid sale for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Prepaid/Sales/{prepaidSaleId}

Production environment

https://connect.secucard.com/api/v2/Prepaid/Sales/{prepaidSaleId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Sales/{prepaidSaleId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Sales/{prepaidSaleId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

Confirm sale

Confirm one prepaid sale

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

Prepaid Sale ID

Responses

200

Confirmed prepaid sale

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Prepaid/Sales/{prepaidSaleId}/Confirm

Production environment

https://connect.secucard.com/api/v2/Prepaid/Sales/{prepaidSaleId}/Confirm

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Prepaid/Sales/{prepaidSaleId}/Confirm

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Prepaid/Sales/{prepaidSaleId}/Confirm

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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), but they are also connected with our system. Every 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.
aggregate
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

200

Returns a list of smart devices

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Smart/Devices

Production environment

https://connect.secucard.com/api/v2/Smart/Devices

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Create Smart Device

Creates a new Smart Device from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Smart device properties

merchant
string

Merchant

store
string

Store

device
string

Device

contract
string

Contract

vendor
string

Vendor

vendor_uid
string

Vendor uid

type
string

Type

description
string

Description

tid
string

TID

products
object (SmartDevicesProducts)

SmartDevicesProducts

terminal_type
string

Terminal type

base_version
string

Base version

Responses

200

Newly created smart device

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Smart/Devices

Production environment

https://connect.secucard.com/api/v2/Smart/Devices

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "merchant": "string",
  • "store": "string",
  • "device": "string",
  • "contract": "string",
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "description": "string",
  • "tid": "string",
  • "products":
    {
    },
  • "terminal_type": "string",
  • "base_version": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "device":
    {
    },
  • "routing":
    {
    },
  • "user_pin": "string",
  • "products":
    {
    },
  • "description": "string",
  • "tid": "string",
  • "idle_screen_register": "string",
  • "idle_screen_terminal": "string",
  • "online": true,
  • "refresh": 0,
  • "connection_type": "string",
  • "terminal_type": "string",
  • "base_version": "string"
}

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

200

Returns smart device for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Smart/Devices/{smartDeviceId}

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "device":
    {
    },
  • "routing":
    {
    },
  • "user_pin": "string",
  • "products":
    {
    },
  • "description": "string",
  • "tid": "string",
  • "idle_screen_register": "string",
  • "idle_screen_terminal": "string",
  • "online": true,
  • "refresh": 0,
  • "connection_type": "string",
  • "terminal_type": "string",
  • "base_version": "string"
}

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

vendor_uid
string

Vendor uid

type
string

Type

description
string

Description

tid
string

TID

products
object (SmartDevicesProducts)

SmartDevicesProducts

terminal_type
string

Terminal type

base_version
string

Base version

Responses

200

Updated smart device

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Smart/Devices/{smartDeviceId}

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "merchant": "string",
  • "store": "string",
  • "device": "string",
  • "contract": "string",
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "description": "string",
  • "tid": "string",
  • "products":
    {
    },
  • "terminal_type": "string",
  • "base_version": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "device":
    {
    },
  • "routing":
    {
    },
  • "user_pin": "string",
  • "products":
    {
    },
  • "description": "string",
  • "tid": "string",
  • "idle_screen_register": "string",
  • "idle_screen_terminal": "string",
  • "online": true,
  • "refresh": 0,
  • "connection_type": "string",
  • "terminal_type": "string",
  • "base_version": "string"
}

Get with routing

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

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart device id

type
required
string

Smart Device Type

Responses

200

The requested smart device which is assigned to a routing

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Smart/Devices/{smartDeviceId}/routing/{type}

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}/routing/{type}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/routing/{type}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/routing/{type}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "device":
    {
    },
  • "routing":
    {
    },
  • "user_pin": "string",
  • "products":
    {
    },
  • "description": "string",
  • "tid": "string",
  • "idle_screen_register": "string",
  • "idle_screen_terminal": "string",
  • "online": true,
  • "refresh": 0,
  • "connection_type": "string",
  • "terminal_type": "string",
  • "base_version": "string"
}

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

Smart device properties

user_pin
string

user code from authentication response

Responses

200

current smart device object

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Smart/Devices/{smartDeviceId}/pin

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}/pin

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/pin

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/pin

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_pin": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "contract":
    {
    },
  • "vendor": "string",
  • "vendor_uid": "string",
  • "type": "string",
  • "device":
    {
    },
  • "routing":
    {
    },
  • "user_pin": "string",
  • "products":
    {
    },
  • "description": "string",
  • "tid": "string",
  • "idle_screen_register": "string",
  • "idle_screen_terminal": "string",
  • "online": true,
  • "refresh": 0,
  • "connection_type": "string",
  • "terminal_type": "string",
  • "base_version": "string"
}

Update device PIN

Sets the device PIN on merchant, store or device level which needs to be passed to authenticate the Smart Device.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart device id (or any other value if the PIN should be set on store or merchant level)

Request Body schema: application/json

Smart device Pin properties

store_id
string Nullable

General Stores ID

merchant_id
required
string

General Merchants ID

pin
required
string

The pin to store

Responses

200

weather the operation was successful or not

500

Validation errors, etc.

default

Other errors

put/Smart/Devices/{smartDeviceId}/devicePin

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}/devicePin

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/devicePin

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/devicePin

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "store_id": "STO_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "merchant_id": "MRC_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH",
  • "pin": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "result": true
}

Get device PIN settings

Get the settings for the device PIN (which needs to be passed to authenticate the Smart Device) to know if a PIN is set on merchant, store or device level.

Authorizations:
oauth_token
path Parameters
smartDeviceId
required
string

Smart device id

Responses

200

Smart device Pin settings

500

Validation errors, etc.

default

Other errors

get/Smart/Devices/{smartDeviceId}/devicePinConfig

Production environment

https://connect.secucard.com/api/v2/Smart/Devices/{smartDeviceId}/devicePinConfig

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/devicePinConfig

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Devices/{smartDeviceId}/devicePinConfig

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "smart_device":
    {
    }
}

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

200

Returns a list of smart routings

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Smart/Routings

Production environment

https://connect.secucard.com/api/v2/Smart/Routings

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Create Smart Routing

Creates a new Smart Routing from the given data.

Authorizations:
oauth_token
Request Body schema: application/json

Smart routing properties

store
string

General store ID

description
string

Description

Responses

200

Newly created smart routing

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Routings

Production environment

https://connect.secucard.com/api/v2/Smart/Routings

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "store": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "assign":
    [
    ]
}

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

200

Returns smart routing for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Smart/Routings/{smartRoutingId}

Production environment

https://connect.secucard.com/api/v2/Smart/Routings/{smartRoutingId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "assign":
    [
    ]
}

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 properties

store
string

General store ID

description
string

Description

Responses

200

Updated smart routing object

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

put/Smart/Routings/{smartRoutingId}

Production environment

https://connect.secucard.com/api/v2/Smart/Routings/{smartRoutingId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "store": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "assign":
    [
    ]
}

Delete Smart Routing

Deletes the specified Smart Routing.

Authorizations:
oauth_token
path Parameters
smartRoutingId
required
string

Smart routing id

Responses

200

Returns deleted smart routing for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Smart/Routings/{smartRoutingId}

Production environment

https://connect.secucard.com/api/v2/Smart/Routings/{smartRoutingId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "assign":
    [
    ]
}

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

Request Body schema: application/json

Smart routing assignment properties

priority
integer

Priority

Responses

200

Newly created smart routing

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

post/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Production environment

https://connect.secucard.com/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "priority": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "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

200

Smart routing with an updated list of assigned smart devices

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

delete/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Production environment

https://connect.secucard.com/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Smart/Routings/{smartRoutingId}/assign/{smartDeviceId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "description": "string",
  • "assign":
    [
    ]
}

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

200

Document uploaded

default

Response related to the error

post/Document/Uploads?multipart

Production environment

https://connect.secucard.com/api/v2/Document/Uploads?multipart

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Document/Uploads?multipart

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Document/Uploads?multipart

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "file": "/path/to/file.txt"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Document uploaded

default

Response related to the error

post/Document/Uploads

Production environment

https://connect.secucard.com/api/v2/Document/Uploads

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Document/Uploads

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Document/Uploads

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "content": "SGVsbG8sIFdvcmxkIQ=="
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Returns the document info

default

Response related to the error

get/Document/Uploads/{documentUploadsId}

Production environment

https://connect.secucard.com/api/v2/Document/Uploads/{documentUploadsId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Document/Uploads/{documentUploadsId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Document/Uploads/{documentUploadsId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Returns the uploaded document

default

Response related to the error

get/Document/Uploads/{documentUploadsId}/Download

Production environment

https://connect.secucard.com/api/v2/Document/Uploads/{documentUploadsId}/Download

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Document/Uploads/{documentUploadsId}/Download

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Document/Uploads/{documentUploadsId}/Download

Response samples

Content type
application/json
Copy
 Expand all Collapse all
"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

200

Newly created Upload Ident

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Services/Uploadidents

Production environment

https://connect.secucard.com/api/v2/Services/Uploadidents

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Uploadidents

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Uploadidents

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Ident Requests

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Services/Identrequests

Production environment

https://connect.secucard.com/api/v2/Services/Identrequests

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Identrequests

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Identrequests

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

person
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

redirect_urls
object (IdentrequestRedirectUrls) Nullable

Ident Request redirect URLs

Responses

200

Newly created Ident Request

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

post/Services/Identrequests

Production environment

https://connect.secucard.com/api/v2/Services/Identrequests

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Identrequests

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Identrequests

Request samples

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

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

Ident Request

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Services/Identrequests/{identrequestId}

Production environment

https://connect.secucard.com/api/v2/Services/Identrequests/{identrequestId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Identrequests/{identrequestId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Identrequests/{identrequestId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.
aggregate
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

200

Matching Ident Results

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Services/Identresults

Production environment

https://connect.secucard.com/api/v2/Services/Identresults

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Identresults

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Identresults

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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

200

Ident Result

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Services/Identresults/{identrequestId}

Production environment

https://connect.secucard.com/api/v2/Services/Identresults/{identrequestId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Services/Identresults/{identrequestId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Services/Identresults/{identrequestId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Cardprocessing Invoices

Find Cardprocessing Invoices

Returns the Cardprocessing 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.
aggregate
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

200

Returns a list of cardprocessing invoices

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Cardprocessing/Invoices

Production environment

https://connect.secucard.com/api/v2/Cardprocessing/Invoices

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Cardprocessing/Invoices

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Cardprocessing/Invoices

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Read Cardprocessing Invoice

Returns the specified Cardprocessing Invoice.

Authorizations:
oauth_token
path Parameters
cardprocessingInvoiceId
required
string

Cardprocessing invoice id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

200

Returns cardprocessing invoice for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Cardprocessing/Invoices/{cardprocessingInvoiceId}

Production environment

https://connect.secucard.com/api/v2/Cardprocessing/Invoices/{cardprocessingInvoiceId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Cardprocessing/Invoices/{cardprocessingInvoiceId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Cardprocessing/Invoices/{cardprocessingInvoiceId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "module.type",
  • "id": "OBJ_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "store":
    {
    },
  • "store_name": "string",
  • "id_old": 0,
  • "tid": "string",
  • "invoice_number": "string",
  • "net_amount": 1995,
  • "tax_amount": 1995,
  • "amount": 1995,
  • "document_url": "string",
  • "type": "invoice"
}

Cardprocessing Transactions

Find Cardprocessing Transactions

Returns the Cardprocessing 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.
aggregate
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

200

Returns a list of cardprocessing transactions

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Cardprocessing/Transactions

Production environment

https://connect.secucard.com/api/v2/Cardprocessing/Transactions

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Cardprocessing/Transactions

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Cardprocessing/Transactions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "count": 0,
  • "data":
    [
    ],
  • "scroll_id": "string",
  • "result": true,
  • "meta": { },
  • "type": "term",
  • "sum": true,
  • "lookup":
    [
    ]
}

Read Cardprocessing Transaction

Returns the specified Cardprocessing Transaction.

Authorizations:
oauth_token
path Parameters
cardprocessingTransactionId
required
string

Cardprocessing transaction id

query Parameters
expand
string
Example: expand=true

Expand fields (all or a specific one)

Responses

200

Returns cardprocessing transaction for a specific id

401

Missing or invalid token

403

Not logged in or no contract

404

Resource not found or no permission

500

Validation errors, etc.

default

Other errors

get/Cardprocessing/Transactions/{cardprocessingTransactionId}

Production environment

https://connect.secucard.com/api/v2/Cardprocessing/Transactions/{cardprocessingTransactionId}

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Cardprocessing/Transactions/{cardprocessingTransactionId}

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Cardprocessing/Transactions/{cardprocessingTransactionId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "object": "cardprocessing.transactions",
  • "id": "PTX_MNTPQ9IFD3V482Y6VMHJXERBYS4J1G",
  • "created": "2020-09-04T18:09:51+02:00",
  • "updated": "2020-09-04T18:09:51+02:00",
  • "merchant":
    {
    },
  • "trans_id": 155862442,
  • "tid": "69123123",
  • "end_of_day_date": "2020-09-04T18:09:51+02:00",
  • "end_of_day_id": "10446230300",
  • "amount": 1995,
  • "trace": 1901,
  • "receipt_number": "0",
  • "product": "Kassenschnitt",
  • "ref_report_id": 84950000,
  • "ref_report_type": 4
}

Public Website

Collection of Public available Endpoints.

Get available countries

Returns the available countries.

Authorizations:
oauth_token

Responses

200

Returns a list of available Countries

401

Missing or invalid token

403

Not logged in or no contract

500

Validation errors, etc.

default

Other errors

get/Public/Website/me/availableCountries

Production environment

https://connect.secucard.com/api/v2/Public/Website/me/availableCountries

Testing environment

https://connect-testing.secupay-ag.de/api/v2/Public/Website/me/availableCountries

Staging environment

https://connect-showcase.secupay-ag.de/api/v2/Public/Website/me/availableCountries

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]