Subscription

It is possible to reuse payments in two ways: The first and preferred method it is to define an initial payment transaction to be a recurring payment. Alternatively, this can be done at a later point (needs an active contract option). A successfully completed payment is required to perform a second payment, otherwise, the payer needs enter their payment data again. After submitting the first transaction, the response returns a "Subscription ID". The ID has to be stored in your system and passed on to each further payment transaction. It's not possible to change the currency of recurring payment. A new payment must be submitted for each (new) currency.

Possible actions

  • Create a new payment transaction with subscription

  • Reuse a subscription to create a second payment transaction

The model

This is the model definition to create a subscription ID.

Mandatory properties

The following parameter SHOULD be transmitted on every create or reuse:

  • customer

  • amount

  • currency

  • purpose

  • basket

    • basket_item_type

    • basket_name

    • basket_total

    • basket_apikey

Create new transaction with subscription

To create a new transaction with subscription the model SecupayTransactionProductDTO needs to be passed to the method paymentSecupaycreditcardPost of the class PaymentSecupaycreditcardsApi.

A (successful) response will return the model SecupayTransactionProductModel.

Use the following request to issue a transaction with subscription via API:

Endpoints
POST https://connect-testing.secupay-ag.de/api/v2/Payment/Secupaycreditcards
or for live:
POST https://connect.secucard.com/api/v2/Payment/Secupaycreditcards
Header
Accept:application/json
Content-Type:application/json
Accept-Charset:utf-8
Authorization:Bearer {{access_token}}
Request Body create new payment with subscription (creditcards)
{
"customer": {
"object": "payment.customers",
"id": "PCU_2QHB4DGM92NAMDXU70ZAV547W9T0AH",
},
"subscription": {
"purpose": "Abo 12/2019"
},
"amount": "1000",
"purpose": "for what text",
"basket": [
{
"item_type": "article",
"article_number": 24,
"name": "Adults",
"price": 1000,
"quantity": 1,
"tax": 0,
"total": 1000
},
{
"item_type": "stakeholder_payment",
"name": "Platform Fee",
"total": 139,
"apikey": "37373c132df0299c5bdcf7c7638dd47aa41a2fe2"
}
]
}

Properties

Name

Type

Description

Sample

Notes

demo

boolean

Decides whether this transaction is handled as demo or live.

false

default: false

redirect_url

\Model\SecupayRedirectUrl




redirect_url.url_push

string

Push-URL for status changes.

Format: RFC 1738

https://api.example.com/secuconnect/push


customer

Model\PaymentCustomersProductModel

Payment-Customer-ID of the initiator of the payment.
See Payment Customer for more details.


mandatory

subscription

\Secuconnect\Client\Model\

SecupayTransactionProductDTOSubscription




subscription.purpose

string

Purpose of the subscription transaction.

Abo 12/2019

mandatory for subscription

amount

integer

Sum in the smallest unit, e.g. Euro-Cent (must match the sum of individual amounts).

1000

mandatory, must match the sum of individual amounts

purpose

string

Purpose of the transaction.

for what text

mandatory

basket

Model\SecupayBasketItem[]




basket.item_type

string

Item Category.

article

mandatory

basket.article_number

string

Descriptive name of item.

24


basket.name

string

Descriptive name of item.

Adults

mandatory

basket.price

integer

Total price

1000


basket.quantity

integer

Quantity of articles in item.

1


basket.tax

integer

taxes

0


basket.total

integer

Total price

1000

mandatory

basket.item_type

string

Item Category

stakeholder_payment


basket.name

string

Descriptive name of item.

Platform Fee


basket.total

integer

Total price

139


basket.apikey

string

apikey

37373c132df0299c5bdcf7c7638dd47aa41a2fe2

mandatory

Response of create new payment with subscription (creditcards)
{
"object": "payment.secupaycreditcards",
"id": "drvgqwmtkstu3481653",
"trans_id": "14254952",
"status": "internal_server_status",
"amount": "1000",
"currency": "EUR",
"purpose": "for what text",
"order_id": null,
"transaction_status": "1",
"basket": [
{
"item_type": "article",
"name": "Adults",
"total": "1000",
"quantity": "1",
"price": "1000",
"article_number": "24"
},
{
"item_type": "stakeholder_payment",
"name": "Platform Fee",
"total": "139"
}
],
"payment_action": "sale",
"customer": {
"object": "payment.customers",
"id": "PCU_2QHB4DGM92NAMDXU70ZAV547W9T0AH",
"contract": {
"object": "payment.contracts",
"id": "PCR_M32SCZ98Q2N3U4GW70ZAVWWE47XPAH"
},
"merchant": {
"object": "general.merchants",
"id": "MRC_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8"
},
"contact": {
"forename": "John",
"surname": "Doe",
"companyname": "Example Inc.",
"name": "John Doe",
"salutation": "Mr.",
"title": "Dr.",
"address": {
"street": "Example Street",
"street_number": "6a",
"postal_code": "01234",
"city": "Examplecity",
"country": "Germany"
},
"email": "example@example.com",
"mobile": "0049-987-654321",
"phone": "0049-123-456789",
"dob": "1901-02-03T00:00:00+01:00"
},
"created": "2019-08-16T10:50:04+02:00"
},
"redirect_url": {
"iframe_url": "https://api-testing.secupay-ag.de/payment/drvgqwmtkstu3481653",
"url_success": "http://example.com",
"url_failure": "http://example.com",
"url_push": "https://example.com"
},
"iframe_url": "https://api-testing.secupay-ag.de/payment/drvgqwmtkstu3481653",
"subscription": {
"id": 1351,
"purpose": "ABO Monatlich"
}
}

Properties

Name

Type

Description

Sample

Notes

object

string

Object of payment transaction.

payment.secupaycreditcards


id

string

Id of payment transaction.

drvgqwmtkstu3481653


trans_id

int

Transaction identifier.

14254952


status

int

Transaction status ID.

internal_server_status


amount

int

Total amount of payment in cents (or the smallest cash unit of the relevant currency).

1000


currency

string

ISO 4217 code of currency, e.g. EUR for Euro.

EUR


purpose

string

Purpose of the transaction.

for what text

mandatory

order_id

string

Your reference-number (optional).

null


transaction_status

integer

Is the ID of the transaction status. For description see the followed Link:
https://developer.secuconnect.com/API-Reference/API-Services/Payment/Transaction_States.html

1


basket

Model\SecupayBasketItem[]




basket.item_type

string

Item Category.

article


basket.name

string

Descriptive name of item.

Adults


basket.total

int

Total price

1000


basket.quantity

int

Quantity of articles in item.

1


basket.price

int

Price of single article, if item is of article category.

1000


basket.article_number

string

Article number of item.

24


basket.item_type

string

Item Category

stakeholder_payment


basket.name

string

Descriptive name of item.

Platform Fee


basket.total

int

Total price

139


payment_action

string

Specifies whether a pre-authorization (authorization) or instant payment (sale) is to be performed.
Default value: sale. The collection of the pre-authorized payment is made with the capture command.

sale


customer

Model\PaymentCustomersProductModel

See Payment Customer for more details.



customer.object

string

Object of payment customer.

payment.customers


customer.id

string

Id of payment customer.

PCU_2QHB4DGM92NAMDXU70ZAV547W9T0AH


redirect_url

Model\SecupayRedirectUrl

A list of redirect urls used for the payment checkout page.



redirect_url.iframe_url

string

The url of the payment checkout iframe.

https://api-testing.secupay-ag.de/payment/fxhagkxzrahu3481659


redirect_url.url_success

string

After successfully entering the cash data of the payer is returned to this page.

http://example.com


redirect_url.url_failure

string

Redirect page in case of errors or user cancellation. The payer is redirected and can select a different payment method.

http://example.com


redirect_url.url_push

string

The secupay system will send status change notifications to this URL.

https://example.com


iframe_url

sting


https://api-testing.secupay-ag.de/payment/fxhagkxzrahu3481659


subscription

Model\SecupayTransactionProductDTOSubscription




subscription.id

int

Id of subscription

1351


subscription.purpose

string

Purpose of the subscription.

Abo 12/2019


Forward the Payer to Enter Payment Data

After transmitting the data of the payer and the amount of the basket, it is necessary to forward the customer (payer) to a provided URL of the secupay system. This can be done either via direct routing (redirect) or by display it into an iFrame. This step is necessary to ensure safe entry of the payment data. This is needed to entering credit card data, for example. Some areas of this site can be customized. This is done in the contract settings and can be defined when creating a sub-contract / project through the API. Additional changes are currently only possible by the secupay support team.

if (!empty($payment->redirect_url->iframe_url)) {
$redirect_url = $payment->redirect_url->iframe_url;
header('Location: ' . $redirect_url);
exit;
}

Example 1

Example Code php SDK create new payment with subscription (creditcards)
<?php
 
namespace Secuconnect\Demo;
 
require __DIR__ . '/../../../vendor/autoload.php';
 
use Exception;
use Secuconnect\Client\Api\PaymentSecupayCreditcardsApi;
use Secuconnect\Client\ApiException;
use Secuconnect\Client\Authentication\Authenticator;
use Secuconnect\Client\Model\PaymentCustomersProductModel;
use Secuconnect\Client\Model\SecupayBasketItem;
use Secuconnect\Client\Model\SecupayRedirectUrl;
use Secuconnect\Client\Model\SecupayTransactionProductDTO;
use Secuconnect\Client\Model\SecupayTransactionProductDTOOptData;
use Secuconnect\Client\Model\SecupayTransactionProductDTOSubscription;
 
try {
Authenticator::authenticateByClientCredentials(
'...',
'...'
);
 
$transaction = new SecupayTransactionProductDTO();
$transaction->setOptData(new SecupayTransactionProductDTOOptData());
$transaction->getOptData()->setLanguage('de_DE'); // or 'en_US'
 
$transaction->setAmount(3324); // in euro-cent
$transaction->setCurrency('EUR');
$transaction->setDemo(true);
 
$transaction->setRedirectUrl(new SecupayRedirectUrl());
 
// See src/payment/customer/createCustomer.php for details
$transaction->setCustomer(new PaymentCustomersProductModel([
'id' => 'PCU_3J2ZD5H8S2N4BCYCN0ZAV3W80X4YAH'
]));
 
// Activate the option to reuse the payment transaction (subscription / recurring payment)
$transaction->setSubscription(new SecupayTransactionProductDTOSubscription([
'purpose' => 'Payment for www.example.com'
]));
 
$api_instance = new PaymentSecupayCreditcardsApi();
$response = $api_instance->paymentSecupaycreditcardsPost($transaction);
 
print_r($response);

Example 2

Request for create new payment transaction with subscription (debits)
{
"amount": "1000",
"currency": "EUR",
"purpose": "for what text",
"order_id": "123",
"basket": [
{
"item_type": "article",
"article_number": 24,
"name": "Adults",
"price": 1000,
"quantity": 1,
"tax": 0,
"total": 1000
}
],
"accrual": "1",
"payment_action": "sale",
"customer": "PCU_2G68MTN7G2N48QE4N0ZAVFJH6NM8A2",
"redirect_url": {
"iframe_url": "",
"url_success": "http://example.com",
"url_failure": "http://example.com",
"url_push": "http://example.com"
},
"contract": "",
"container": "",
"opt_data": {
"has_accepted_disclaimer": "",
"language": "de_DE"
},
"subscription": {
"purpose": "Abo 01/2020"
},
"demo": "0",
"experience": ""
}

Response:

Response for create new payment transaction with subscription (debits)
{
"object": "payment.secupaydebits",
"id": "kzdbpcahtccl3481669",
"trans_id": "14254968",
"status": "internal_server_status",
"amount": "1000",
"currency": "EUR",
"purpose": "for what text",
"order_id": "123",
"transaction_status": "1",
"basket": [
{
"item_type": "article",
"name": "Adults",
"total": "1000",
"quantity": "1",
"price": "1000",
"article_number": "24"
}
],
"accrual": true,
"payment_action": "sale",
"customer": {
"object": "payment.customers",
"id": "PCU_2G68MTN7G2N48QE4N0ZAVFJH6NM8A2",
"contract": {
"object": "payment.contracts",
"id": "PCR_M32SCZ98Q2N3U4GW70ZAVWWE47XPAH"
},
"merchant": {
"object": "general.merchants",
"id": "MRC_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8"
},
"contact": {
"forename": "Dominik",
"surname": "Kleindienst",
"name": "Dominik Kleindienst",
"address": {
"street": "Straße",
"street_number": "1",
"postal_code": "84030",
"city": "Mainhausen"
},
"email": "mustermann@xpecto.com"
},
"created": "2019-03-13T10:55:21+01:00"
},
"redirect_url": {
"iframe_url": "https://api-testing.secupay-ag.de/payment/kzdbpcahtccl3481669",
"url_success": "http://example.com",
"url_failure": "http://example.com",
"url_push": "http://example.com"
},
"iframe_url": "https://api-testing.secupay-ag.de/payment/kzdbpcahtccl3481669",
"subscription": {
"id": 1356,
"purpose": "Abo 01/2020"
}
}

Store the Subscription-ID

After creating the first payment a Subscription-ID will be returned in the response object. The ID has be stored and can then be reused for recurring payments:

Example Code php SDK
$subscription_id = (int)$payment->subscription->id;

Reuse subscription

As soon as a customer has successfully completed a payment, the subscription ID can be used so the customer does not have to re-enter their payment data again. The parameters amount and purpose can be changed for subsequent payments. However, the currency can not be changed. A new transaction has to be submitted for each (new) currency.

Example Code php SDK reuse subsciption ID php SDK
$subscription_id = 737;
$payment = new \SecucardConnect\Product\Payment\Model\SecupayCreditcard();
$payment->amount = 1234;
$payment->currency = 'EUR'; // The ISO-4217 code of the currency
$payment->purpose = 'Your support for project XY';
$payment->order_id = '201700125'; // The shop order id
// Add the customer (id) which you have created before
$payment->customer = new \SecucardConnect\Product\Payment\Model\Customer();
$payment->customer->id = 'PCU_WMTTCSTJS2M80MHX875XUHDHNM8UA6';
// Activate the option to reuse the payment transaction
$payment->subscription = new \SecucardConnect\Product\Payment\Model\Subscription();
$payment->subscription->id = $subscription_id;
// Optional: Define the contract (to which merchant belongs the payment transaction) using the ID:
// $payment->contract = 'PCR_3AYQR6T272M83WTYX75XU8CZNM8UA7';
// or by using the (loaded) contract object:
// $payment->contract = new \SecucardConnect\Product\Payment\Model\Contract();
// $payment->contract->id = 'PCR_3AYQR6T272M83WTYX75XU8CZNM8UA7';
// Block the payout unit the flag will be removed
$payment->accrual = true;
$payment = $service->save($payment);


Response of reuse subscription
Created recurring secupay creditcard transaction with id: ehmnurskkfrq2052176
Payment data: SecucardConnect\Product\Payment\Model\SecupayCreditcard Object
(
[contract] =>
[customer] => SecucardConnect\Product\Payment\Model\Customer Object
(
[created] => DateTime Object
(
[date] => 2017-04-26 16:53:36.000000
[timezone_type] => 1
[timezone] => +02:00
)
[updated] =>
[contract] => SecucardConnect\Product\Payment\Model\Contract Object
(
[created] =>
[updated] =>
[parent] =>
[allow_cloning] =>
[id] => PCR_2BKJSSECG2M80HUB875XUPXV7M8UA6
[object] => payment.contracts
)
[contact] => SecucardConnect\Product\Common\Model\Contact Object
(
[salutation] => Mr.
[title] => Dr.
[forename] => John
[surname] => Doe
[name] => John Doe
[companyname] => Example Inc.
[dob] => DateTime Object
(
[date] => 1901-02-03 00:00:00.000000
[timezone_type] => 1
[timezone] => +01:00
)
[birthplace] =>
[nationality] =>
[gender] =>
[phone] => 0049-123-456789
[mobile] => 0049-987-654321
[email] => example@example.com
[picture] =>
[pictureObject] =>
[url_website] =>
[address] => SecucardConnect\Product\Common\Model\Address Object
(
[street] => Example Street
[street_number] => 6a
[city] => Examplecity
[postal_code] => 01234
[country] => Germany
[id] =>
[object] =>
)
)
[merchant] =>
[merchant_customer_id] =>
[id] => PCU_WMTTCSTJS2M80MHX875XUHDHNM8UA6
[object] => payment.customers
)
[recipient] =>
[amount] => 3795
[currency] => EUR
[purpose] => Your support for project XY
[order_id] => 1493218455
[trans_id] => 9568703
[status] => internal_server_status
[transaction_status] => 1
[basket] => Array
(
[0] => SecucardConnect\Product\Payment\Model\Basket Object
(
[quantity] => 2
[name] => Super fancy product
[ean] =>
[tax] => 19
[total] => 3000
[price] => 1500
[contract_id] =>
[model] =>
[article_number] =>
[item_type] => article
[apikey] =>
[id] =>
[object] =>
)
[1] => SecucardConnect\Product\Payment\Model\Basket Object
(
[quantity] => 0
[name] => Deutsche Post Warensendung
[ean] =>
[tax] => 19
[total] => 145
[price] => 0
[contract_id] =>
[model] =>
[article_number] =>
[item_type] => shipping
[apikey] =>
[id] =>
[object] =>
)
[2] => SecucardConnect\Product\Payment\Model\Basket Object
(
[quantity] => 0
[name] => platform fee
[ean] =>
[tax] => 0
[total] => 450
[price] => 0
[contract_id] => PCR_MEK2DFR9T2M80MEU875XUQTH7M8UA7
[model] =>
[article_number] =>
[item_type] => stakeholder_payment
[apikey] =>
[id] =>
[object] =>
)
[3] => SecucardConnect\Product\Payment\Model\Basket Object
(
[quantity] => 0
[name] => PayWhatYouWant
[ean] =>
[tax] => 0
[total] => 200
[price] => 0
[contract_id] => PCR_3PSWDHWZN2M80MGNX75XU5HHNM8UA7
[model] =>
[article_number] =>
[item_type] => stakeholder_payment
[apikey] =>
[id] =>
[object] =>
)
)
[experience] =>
[accrual] =>
[subscription] => SecucardConnect\Product\Payment\Model\Subscription Object
(
[purpose] =>
[id] => 737
[object] =>
)
[redirect_url] => SecucardConnect\Product\Payment\Model\RedirectUrl Object
(
[url_success] => http://shop.example.com/success.php
[url_failure] => http://shop.example.com/failure.php
[iframe_url] => https://api-testing.secupay-ag.de/payment/ehmnurskkfrq2052176
)
[url_success] =>
[url_failure] =>
[iframe_url] => https://api-testing.secupay-ag.de/payment/ehmnurskkfrq2052176
[opt_data] =>
[payment_action] => sale
[used_payment_instrument] =>
[id] => ehmnurskkfrq2052176
[object] => payment.secupaycreditcards
)