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