Create a payment transaction

General parameters

Payment method: invoice

PHP SDK

Request
use SecucardConnect\Product\Payment\Model\SecupayInvoice;

/**
 * @var \SecucardConnect\Product\Payment\SecupayInvoicesService $service
 */
$service = $secucard->payment->secupayinvoices;

$invoice = new SecupayInvoice();
$invoice->amount = 100; // Amount in cents (or in the smallest unit of the given currency)
$invoice->currency = 'EUR'; // The ISO-4217 code of the currency
$invoice->purpose = 'Your purpose from TestShopName';
$invoice->order_id = '201600123'; // The shop order id
$invoice->customer = $customer;

$invoice = $service->save($invoice);
Response
Created secupay invoice transaction with id: hcbjqubbeeyw1647097
Invoice data: SecucardConnect\Product\Payment\Model\SecupayInvoice Object
(
    [customer] => SecucardConnect\Product\Payment\Model\Customer Object
        (
            [created] => DateTime Object
                (
                    [date] => 2016-11-28 11:44:47.000000
                    [timezone_type] => 1
                    [timezone] => +01:00
                )
            [updated] =>
            [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                (
                    [created] =>
                    [updated] =>
                    [parent] =>
                    [allow_cloning] =>
                    [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                    [object] => payment.contracts
                )
            [contact] => SecucardConnect\Product\Common\Model\Contact Object
                (
                    [salutation] => Mr.
                    [title] => Dr.
                    [forename] => John
                    [surname] => Doe
                    [name] => John Doe
                    [companyname] => Testfirma
                    [dob] => DateTime Object
                        (
                            [date] => 1971-02-03 00:00:00.000000
                            [timezone_type] => 1
                            [timezone] => +01:00
                        )
                    [birthplace] => MyBirthplace
                    [nationality] => DE
                    [gender] =>
                    [phone] => 0049-123456789
                    [mobile] =>
                    [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] => Deutschland
                            [id] =>
                            [object] =>
                        )
                )
            [merchant] =>
            [id] => PCU_2NXJMDCWV2MWSWAFX75XURW7V9NJAN
            [object] => payment.customers
        )
    [contract] =>
    [amount] => 100
    [currency] => EUR
    [purpose] => Your purpose from TestShopName
    [order_id] => 201600123
    [trans_id] => 8475282
    [status] => accepted
    [transaction_status] => 85
    [basket] =>
    [id] => hcbjqubbeeyw1647097
    [object] => payment.secupayinvoices
)

Payment method: direct debit

PHP SDK

Create payment container:
Request
use SecucardConnect\Product\Payment\Model\Container;
use SecucardConnect\Product\Payment\Model\Data;

/**
 * @var \SecucardConnect\Product\Payment\ContainersService $service
 */
$service = $secucard->payment->containers;

// You may obtain a global list of available containers
$containers = $service->getList();
if ($containers === null) {
    throw new Exception("No Containers found.");
}


// create new Data subobject for contrainer
$container_data = new Data();
$container_data->iban = 'DE62100208900001317270';
$container_data->owner = 'Max Mustermann';

$container = new Container();
$container->private = $container_data;
$container->customer = $customer;
$logger->debug('object data initialized');

try {
    $container = $service->save($container);
} catch (\Exception $e) {
    echo 'Error message: ' . $e->getMessage() . "\n";
}
Response
[container] => SecucardConnect\Product\Payment\Model\Container Object
    (
        [customer] => SecucardConnect\Product\Payment\Model\Customer Object
            (
                [created] => DateTime Object
                    (
                        [date] => 2016-11-23 11:55:58.000000
                        [timezone_type] => 1
                        [timezone] => +01:00
                    )
                [updated] =>
                [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                    (
                        [created] =>
                        [updated] =>
                        [parent] =>
                        [allow_cloning] =>
                        [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                        [object] => payment.contracts
                    )
                [contact] => SecucardConnect\Product\Common\Model\Contact Object
                    (
                        [salutation] => Mr.
                        [title] => Dr.
                        [forename] => John
                        [surname] => Doe
                        [name] => John Doe
                        [companyname] => Testfirma
                        [dob] => DateTime Object
                            (
                                [date] => 1971-02-03 00:00:00.000000
                                [timezone_type] => 1
                                [timezone] => +01:00
                            )
                        [birthplace] => MyBirthplace
                        [nationality] => DE
                        [gender] =>
                        [phone] => 0049-123456789
                        [mobile] =>
                        [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] => Deutschland
                                [id] =>
                                [object] =>
                            )
                    )
                [merchant] =>
                [id] => PCU_2XCPZ6EGY2MWYEMV875XUVDZ7M8UA6
                [object] => payment.customers
            )
        [public] => SecucardConnect\Product\Payment\Model\Data Object
            (
                [owner] => Max Mustermann
                [iban] => DE62100208900001317270
                [bic] => HYVEDEMM488
                [bankname] => UniCredit Bank - HypoVereinsbank
            )
        [private] => SecucardConnect\Product\Payment\Model\Data Object
            (
                [owner] => Max Mustermann
                [iban] => DE62100208900001317270
                [bic] => HYVEDEMM488
                [bankname] => UniCredit Bank - HypoVereinsbank
            )
        [type] =>
        [created] => DateTime Object
            (
                [date] => 2016-11-23 11:55:58.000000
                [timezone_type] => 1
                [timezone] => +01:00
            )
        [updated] =>
        [contract] => SecucardConnect\Product\Payment\Model\Contract Object
            (
                [created] =>
                [updated] =>
                [parent] =>
                [allow_cloning] =>
                [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                [object] => payment.contracts
            )
        [mandate] => SecucardConnect\Product\Payment\Model\Mandate Object
            (
                [iban] => DE62100208900001317270
                [bic] => HYVEDEMM488
                [type] => COR1
                [identification] => PAM/ACSQ42PH82PO4660K
                [status] => 1
                [sepa_mandate_id] => 431814
            )
        [id] => PCT_WYH0YXDB52MWYEMV875XUVDZ7M8UA7
        [object] => payment.containers
    )
Create payment transaction with container:
Request
use SecucardConnect\Product\Payment\Model\SecupayDebit;

/**
 * @var \SecucardConnect\Product\Payment\SecupayDebitsService $service
 */
$service = $secucard->payment->secupaydebits;

$debit = new SecupayDebit();
$debit->amount = 245; // Amount in cents (or in the smallest unit of the given currency)
$debit->currency = 'EUR'; // The ISO-4217 code of the currency
$debit->purpose = 'Your purpose from TestShopName';
$debit->order_id = '201600123'; // The shop order id
$debit->customer = $customer;
$debit->container = $container;

$debit = $service->save($debit);
Response
Created secupay debit transaction with id: yetymazqrhqd1647092
Debit data: SecucardConnect\Product\Payment\Model\SecupayDebit Object
(
    [container] => SecucardConnect\Product\Payment\Model\Container Object
        (
            [customer] => SecucardConnect\Product\Payment\Model\Customer Object
                (
                    [created] => DateTime Object
                        (
                            [date] => 2016-11-23 11:55:58.000000
                            [timezone_type] => 1
                            [timezone] => +01:00
                        )
                    [updated] =>
                    [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                        (
                            [created] =>
                            [updated] =>
                            [parent] =>
                            [allow_cloning] =>
                            [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                            [object] => payment.contracts
                        )
                    [contact] => SecucardConnect\Product\Common\Model\Contact Object
                        (
                            [salutation] => Mr.
                            [title] => Dr.
                            [forename] => John
                            [surname] => Doe
                            [name] => John Doe
                            [companyname] => Testfirma
                            [dob] => DateTime Object
                                (
                                    [date] => 1971-02-03 00:00:00.000000
                                    [timezone_type] => 1
                                    [timezone] => +01:00
                                )
                            [birthplace] => MyBirthplace
                            [nationality] => DE
                            [gender] =>
                            [phone] => 0049-123456789
                            [mobile] =>
                            [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] => Deutschland
                                    [id] =>
                                    [object] =>
                                )
                        )
                    [merchant] =>
                    [id] => PCU_2XCPZ6EGY2MWYEMV875XUVDZ7M8UA6
                    [object] => payment.customers
                )
            [public] => SecucardConnect\Product\Payment\Model\Data Object
                (
                    [owner] => Max Mustermann
                    [iban] => DE62100208900001317270
                    [bic] => HYVEDEMM488
                    [bankname] => UniCredit Bank - HypoVereinsbank
                )
            [private] => SecucardConnect\Product\Payment\Model\Data Object
                (
                    [owner] => Max Mustermann
                    [iban] => DE62100208900001317270
                    [bic] => HYVEDEMM488
                    [bankname] => UniCredit Bank - HypoVereinsbank
                )
            [type] =>
            [created] => DateTime Object
                (
                    [date] => 2016-11-23 11:55:58.000000
                    [timezone_type] => 1
                    [timezone] => +01:00
                )
            [updated] =>
            [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                (
                    [created] =>
                    [updated] =>
                    [parent] =>
                    [allow_cloning] =>
                    [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                    [object] => payment.contracts
                )
            [mandate] => SecucardConnect\Product\Payment\Model\Mandate Object
                (
                    [iban] => DE62100208900001317270
                    [bic] => HYVEDEMM488
                    [type] => COR1
                    [identification] => PAM/ACSQ42PH82PO4660K
                    [status] => 1
                    [sepa_mandate_id] => 431814
                )
            [id] => PCT_WYH0YXDB52MWYEMV875XUVDZ7M8UA7
            [object] => payment.containers
        )
    [contract] =>
    [amount] => 245
    [currency] => EUR
    [purpose] => Your purpose from TestShopName
    [order_id] => 201600123
    [trans_id] => 0
    [status] => internal_server_status
    [transaction_status] =>
    [basket] =>
    [id] => yetymazqrhqd1647092
    [object] => payment.secupaydebits
)

Payment method: prepay

PHP SDK

Request
use SecucardConnect\Product\Payment\Model\SecupayPrepay;

/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

$prepay = new SecupayPrepay();
$prepay->amount = 100; // Amount in cents (or in the smallest unit of the given currency)
$prepay->currency = 'EUR'; // The ISO-4217 code of the currency
$prepay->purpose = 'Your purpose from TestShopName';
$prepay->order_id = '201600123'; // The shop order id
$prepay->customer = $customer;

$prepay = $service->save($prepay);
Response
Created secupay prepay transaction with id: ufgjjwdfmwph1468032
Prepay data: SecucardConnect\Product\Payment\Model\SecupayPrepay Object
(
    [customer] => SecucardConnect\Product\Payment\Model\Customer Object
        (
            [created] => DateTime Object
                (
                    [date] => 2016-10-14 11:49:29.000000
                    [timezone_type] => 1
                    [timezone] => +02:00
                )
            [updated] =>
            [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                (
                    [created] =>
                    [updated] =>
                    [parent] =>
                    [merchant] =>
                    [allow_cloning] =>
                    [sepa_mandate_inform] =>
                    [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                    [object] => payment.contracts
                )
            [contact] => SecucardConnect\Product\Common\Model\Contact Object
                (
                    [salutation] => Mr.
                    [title] => Dr.
                    [forename] => John
                    [surname] => Doe
                    [name] => John Doe
                    [companyname] => Testfirma
                    [dob] => DateTime Object
                        (
                            [date] => 1971-02-03 00:00:00.000000
                            [timezone_type] => 1
                            [timezone] => +01:00
                        )
                    [birthplace] => MyBirthplace
                    [nationality] => DE
                    [gender] =>
                    [phone] => 0049-123456789
                    [mobile] =>
                    [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] => Deutschland
                            [id] =>
                            [object] =>
                        )
                )
            [merchant] =>
            [id] => PCU_M0PSEHCWK2M00Y8KX75XUMGS6W8XAQ
            [object] => payment.customers
        )
    [transfer_purpose] => TA 7867851
    [transfer_account] => SecucardConnect\Product\Payment\Model\TransferAccount Object
        (
            [account_owner] => secupay AG
            [accountnumber] => 1747013
            [iban] => DE88300500000001747013
            [bic] => WELADEDDXXX
            [bankcode] => 30050000
        )
    [contract] =>
    [amount] => 100
    [currency] => EUR
    [purpose] => Your purpose from TestShopName
    [order_id] => 201600123
    [trans_id] => 7867851
    [status] => authorized
    [transaction_status] => 25
    [id] => ufgjjwdfmwph1468032
    [object] => payment.secupayprepays
)

Payment method: credit card

PHP SDK

Request
use SecucardConnect\Product\Payment\Model\SecupayCreditcard;

/**
 * @var \SecucardConnect\Product\Payment\SecupayCreditcardsService $service
 */
$service = $secucard->payment->secupaycreditcards;

$creditcard = new SecupayCreditcard();
$creditcard->amount = 100; // Amount in cents (or in the smallest unit of the given currency)
$creditcard->currency = 'EUR'; // The ISO-4217 code of the currency
$creditcard->purpose = 'Your purpose from TestShopName';
$creditcard->order_id = '201600123'; // The shop order id
$creditcard->customer = $customer;
$creditcard->url_success = 'http://shop.example.com/success.php';
$creditcard->url_failure = 'http://shop.example.com/failure.php';

$creditcard = $service->save($creditcard);
Response
Created secupay creditcard transaction with id: tjftokgadmln1647246
Creditcard data: SecucardConnect\Product\Payment\Model\SecupayCreditcard Object
(
    [customer] => SecucardConnect\Product\Payment\Model\Customer Object
        (
            [created] => DateTime Object
                (
                    [date] => 2016-12-01 09:24:22.000000
                    [timezone_type] => 1
                    [timezone] => +01:00
                )
            [updated] =>
            [contract] => SecucardConnect\Product\Payment\Model\Contract Object
                (
                    [created] =>
                    [updated] =>
                    [parent] =>
                    [allow_cloning] =>
                    [id] => PCR_W6AV7JJUJ2YS6WHFR5GQGS99ABZDAP
                    [object] => payment.contracts
                )
            [contact] => SecucardConnect\Product\Common\Model\Contact Object
                (
                    [salutation] => Mr.
                    [title] => Dr.
                    [forename] => John
                    [surname] => Doe
                    [name] => John Doe
                    [companyname] => Testfirma
                    [dob] => DateTime Object
                        (
                            [date] => 1971-02-03 00:00:00.000000
                            [timezone_type] => 1
                            [timezone] => +01:00
                        )
                    [birthplace] => MyBirthplace
                    [nationality] => DE
                    [gender] =>
                    [phone] => 0049-123456789
                    [mobile] =>
                    [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] => Deutschland
                            [id] =>
                            [object] =>
                        )
                )
            [merchant] =>
            [id] => PCU_3RTDR52JG2MWVRXR875XU808V9NJAN
            [object] => payment.customers
        )
    [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/tjftokgadmln1647246
    [contract] =>
    [amount] => 100
    [currency] => EUR
    [purpose] => Your purpose from TestShopName
    [order_id] => 201600123
    [trans_id] => 0
    [status] => internal_server_status
    [transaction_status] =>
    [basket] =>
    [id] => tjftokgadmln1647246
    [object] => payment.secupaycreditcards
)

Basket

The correct transmission of the basket helps us support the customers and for the risk assessment of the order. In the basket happens also the assignment or splitting of the intended recipient of the payment. The sum of all basket positions with the types "article", "shipping" and "donation" must corresponds to the value of the parameter "amount" of the transaction. The type "stakeholder_payment" is not included into the summation of this parameter.

// Create basket
$payment->basket = [];

// Add the first item
$item_1 = new \SecucardConnect\Product\Payment\Model\Basket();
$item_1->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_ARTICLE;
$item_1->name = 'Super fancy product';
$item_1->price = 15000;
$item_1->quantity = 2;
$item_1->tax = 19;
$item_1->total = 30000;
$payment->basket[] = $item_1;

// Add the shipping costs
$shipping = new \SecucardConnect\Product\Payment\Model\Basket();
$shipping->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_SHIPPING;
$shipping->name = 'DHL Paket National';
$shipping->tax = 19;
$shipping->total = 499;
$payment->basket[] = $shipping;

// Add "pay what you want"
$pwyw = new \SecucardConnect\Product\Payment\Model\Basket();
$pwyw->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_DONATION;
$pwyw->name = 'Donation for the platform';
$pwyw->total = 200;
$payment->basket[] = $pwyw;

// For payout: add platform fee
$payout_fee = new \SecucardConnect\Product\Payment\Model\Basket();
$payout_fee->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_STAKEHOLDER_PAYMENT;
$payout_fee->contract_id = 'PCR_MEK2DFR9T2M80MEU875XUQTH7M8UA7';
$payout_fee->name = 'platform fee';
$payout_fee->total = 450;
$payment->basket[] = $payout_fee;

// For payout: add crowdfunding investment
$payout_invest = new \SecucardConnect\Product\Payment\Model\Basket();
$payout_invest->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_STAKEHOLDER_PAYMENT;
$payout_invest->contract_id = 'PCR_3AYQR6T272M83WTYX75XU8CZNM8UA7';
$payout_invest->name = 'crowdfunding investment';
$payout_invest->total = 30049;
$payment->basket[] = $payout_invest;

// For payout: add "pay what you want"
$payout_pwyw = new \SecucardConnect\Product\Payment\Model\Basket();
$payout_pwyw->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_STAKEHOLDER_PAYMENT;
$payout_pwyw->contract_id = 'PCR_3PSWDHWZN2M80MGNX75XU5HHNM8UA7';
$payout_pwyw->name = 'PayWhatYouWant';
$payout_pwyw->total = 200;
$payment->basket[] = $payout_pwyw;


// Calculate total amount
$payment->amount = 0;
foreach($payment->basket as $item) {
    if (in_array($item->item_type, [
        \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_ARTICLE,
        \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_SHIPPING,
        \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_DONATION
    ])) {
        $payment->amount += (int)$item->total;
    }
}
Parameters
  • item_type - Type of basket element
  • name - Name of the article or service
  • price - Price of the item in cents (per piece / per unit)
  • quantity - Quantity of the item
  • tax - Tax rate → statement in full percentage without the percent sign, eg: 19, 7 or 0
  • total - Total amount in cents of the beasket element
  • contract_id - Contract-ID of the pre-sighted receiver (only for itemtype: *stakeholderpayment*)
  • apikey - Alternative for contract_id (f.e. during the migration phase from the old flex.API to the secuconnect API)
Item Types

Further differentiation of the basket components can be achieved using parameter item_type.

The following types of basket elements are possible:

  • article - Good or service
  • shipping - Shipping and handling
  • donation - Donation
  • stakeholder_payment - Amount for third parties (needs a seperate activation for the contract)

For the type stakeholder_payment is the parameters contract_id or alternatively the parameter apikey needed to identify the intended recipient.

Update basket

If the pay-out for the transaction is still blocked ("accrual = true") then the basket can still be changed. This is necessary if doesn't known at the time the order the stakeholder interests. One use-case for this is for example the shipment of goods via "drop shipping". A further is the placing of service packages (such as repair services by various partners, which will be selected by their current workload).

/**
 * @var \SecucardConnect\Product\Payment\SecupayCreditcardsService $service
 */
$service = $secucard->payment->secupaycreditcards;

$basket = [];

$item = new \SecucardConnect\Product\Payment\Model\Basket();
$item->item_type = \SecucardConnect\Product\Payment\Model\Basket::ITEM_TYPE_STAKEHOLDER_PAYMENT;
$item->contract_id = 'PCR_3AYQR6T272M83WTYX75XU8CZNM8UA7';
$item->name = 'Share for Stakeholder XY';
$item->total = 30049;
$basket[] = $item;

if ($service->updateBasket('abcdefghixyz123456789', $basket)) {
    // Successful
}

Cancel / refund

To cancel a payment or to make refund it is necessary to execute the API call "cancel" with the same payment method with which the transaction was created. Thus, if a prepay-payment has been submitted, the cancel-command must be issued with the object "SecupayPrepaysService". Depending on the status of the payment transaction, a refund to the payer will be issued automatically.

/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

if ($service->cancel('abcdefghixyz123456789')) {
    // Successful
}

// To do a partitial refund you can define the amount as third parameter.
// The secound paramter is d
// $service->cancel('abcdefghixyz123456789', null, 150);

If the transaction created with a sub-account (by specifying the Contract-ID) so that ID must be passed as the second parameter.

The third parameter defines the amount to be refund. If the parameter is "0", then the full (balance) is always the refund amount.

Capture (Perform pre-authorized payment / confirm invoice payment)

To release a pre-authorized payment it's necessary to run a "clearing". This will be done by the "capture" command. A payment is pre-authorized when the paymet transaction will be created with the parameter payment_action = authorization.

For invoice payments the capture command will be confirm the bill and the agreed period till the due date of the payment will be start.

for prepay payments or on subscriptions a capture is not necessary / possible. The background for this is that the payment will be done before the shipping starts.

A partially release of the payment is currently not supported.

/**
 * @var \SecucardConnect\Product\Payment\SecupayCreditcardsService $service
 */
$service = $secucard->payment->secupaycreditcards;

if ($service->capture('abcdefghixyz123456789')) {
    // Successful
}

Cancel pre-authorized payment

If a pre-authorized payment should be released without charge the payer, you need to call also the cancel command. Undo a this cancellation is not possible. In this case, a new payment transaction must be created.

Details of this call are described on "Cancel / refund".

/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

if ($service->cancel('abcdefghixyz123456789')) {
    // Successful
}

Unblock payment for payout

If a payment was created with activating to blocking the pay-out ( "accrual = true") or was in the contract settings defined that all payments will be automatically be blocked for pay-out, it is needed to release this lock. This will be done by calling the reverseAccrual command. Once this command has been successfully called the payment shall release for pay-out and it will be paid out on the next pay-out date. This assumes that the contract has no pay-out lock. This is as always the case when the merchant / project has not been fully identified.

/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

if ($service->reverseAccrual('abcdefghixyz123456789')) {
    // Successful
}

Subsequent payments

If you want to change the amount for a payment transaction after the payment was made, f.e. the return of rented item was to late, you can (after the contract was activated for this) increase this payment up to 20% of the original amount. For amounts beyond, or for prepay payments you need to create a new payment transaction.

/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

$amount = 1000;

$basket = [];

$item = new \SecucardConnect\Product\Payment\Model\Basket();
$item->name = 'Delayed return';
$item->total = 1000;
$basket[] = $item;

if ($service->initSubsequent('abcdefghixyz123456789', $amount, $basket)) {
    // Successful
}

Transmit shipping information

Shipping information can be transmitted via the setShippingInformation command. This information is needed by the customer support f.e. if the buyer applies with questions about a charge on his bank account. But even for invoice payments this information is important so that the exact due date can be determined (f.e. 10 working days after delivery). It's possible to transmitt this information seperatly or by doing the capture.

Request
/**
 * @var \SecucardConnect\Product\Payment\SecupayPrepaysService $service
 */
$service = $secucard->payment->secupayprepays;

if ($service->setShippingInformation('abcdefghixyz123456789', 'DHL', '340433836908764611', '2017-1685896-5')) {
    // Successful
}
Parameters
  1. ID of the transaction
  2. Shipping service provider, such as DHL, Hermes, UPS
  3. Tracking number
  4. Invoice Number

Create a recurring payment

General

It is possibile to reuse payments in two ways. The preferred method it is to define that at the first payment that this one will be a recurring payment. Alternatively this can be done at a later point (but this needs a activated contract option). A successfully completed payment is required to perform a second payment, without the payer needs enter his payment data again. After submitting the first transaction in the response object ther will be returned a value which is called "Subscription ID". This have to be stored in your system and be passed on each further payment transaction. It's not possible to change the currency of recurring payment. So a new payment must be submitted for each (new) currency.

PHP SDK

Request
// Create payments
/**
 * @var \SecucardConnect\Product\Payment\SecupayCreditcardsService $service
 */
$service = $secucard->payment->secupaycreditcards;

/*
 * 1) Start first payment (f.e. set-up fee)
 */
$payment = new \SecucardConnect\Product\Payment\Model\SecupayCreditcard();
$payment->amount = 1000; // Amount in cents (or in the smallest unit of the given currency)
$payment->currency = 'EUR'; // Can not changed for a created subscription!
$payment->purpose = 'Set-up fee for www.example.com';
$payment->order_id = '201700123'; // 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';

// The customer will be redirected to "url_success" after you (the shop) has show him the iframe
// and he has filled out the form in this iframe.
// The url of this iframe will be returned in the response of this save request in the variable called "iframe_url".
$payment->redirect_url = new \SecucardConnect\Product\Payment\Model\RedirectUrl();
$payment->redirect_url->url_success = 'http://shop.example.com/success.php';
// The customer will be redirected to "url_failure" if we don't accept him for credit card payments.
// You should offer him to pay with other payment methods on this page.
$payment->redirect_url->url_failure = 'http://shop.example.com/failure.php';

// Activate the option to reuse the payment transaction
$payment->subscription = new \SecucardConnect\Product\Payment\Model\Subscription();
$payment->subscription->purpose = 'Payment for www.example.com';

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

// Do not debit the buyer's funding source before the project is successful (only make a pre-authorization):
$payment->payment_action = $payment::PAYMENT_ACTION_AUTHORIZATION;

$payment = $service->save($payment);
Parameter
  • amount - Total amount of payment in cents (or the smallest cash unit of the relevant currency)
  • currency - ISO 4217 code of currency, eg EUR for euros
  • purpose - the purpose of the payment. This is the later assignment of the payment is for example on the account statement of the buyer.
  • order_id - Specifying an order number. Depending on the contract setting, this must be unique for each payment.
  • redirect_url
    • url_success - After successfully entering the cash data of the payer is returned to this page.
    • url_failure - After canceling or on errors the payer will be redirected to this page and can select there an another payment method.
      • url_push - The secupay system will be send status change notifications to this URL.
    subscription
    • purpose - This statement of the purpose will be always used for recurring payments if no other prupose was defined. If you don't transmit a (existing) Subscription-ID in this request, it will be created a new Subscription-ID for this payment if you define a purpose here.
  • contract - Specifying the ID of the contract to which the payment should be assigned. It's only needed if you want to assign this payment to a sub-account.
  • accrual - Indicates whether the payment is locked for pay-out (TRUE) or not (FALSE). Standard value here is FALSE.
  • payment_action - Specifies whether a pre-authorization ("authorization") or instant payment ( "sale") is to be performed. Standard value here is "sale". The collection of the pre-authorized payment is made with the "capture" command.
Response
Created secupay creditcard transaction with id: zqucyuxjkqhu2052150
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] => 1000
    [currency] => EUR
    [purpose] => Set-up fee for www.example.com
    [order_id] => 1494574969
    [trans_id] => 9568677
    [status] => internal_server_status
    [transaction_status] => 1
    [basket] => 
    [experience] => 
    [accrual] => 1
    [subscription] => 
    [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/zqucyuxjkqhu2052150
        )

    [url_success] => 
    [url_failure] => 
    [iframe_url] => https://api-testing.secupay-ag.de/payment/zqucyuxjkqhu2052150
    [opt_data] => 
    [payment_action] => authorization
    [used_payment_instrument] => 
    [id] => zqucyuxjkqhu2052150
    [object] => payment.secupaycreditcards
)

Store the Subscription-ID

After creating the first payment a so-called Subscription-ID will be returned in the response object. This have to be stored and can then be reused for each recurring payments then:

$subscription_id = (int)$payment->subscription->id;

Forward the payer to enter the payment data

After transmitting the data of the payer and the amount of the basket, it's 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 am IFrame. This step is necessary to ensure safe entry of the payment data. This is especially necessary when entering credit card data. Some areas of this site may 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;
}

Subsequent creation of a Subscription-ID

As an alternative to the previously explained way, it's also possible to create a Subscription-ID later. But this is not the common way.

/**
 * @var \SecucardConnect\Product\Payment\SecupayCreditcardsService $service
 */
$service = $secucard->payment->secupaycreditcards;

$subscriptionId = $service->updateSubscription('abcdefghixyz123456789', 'XY Mitgliedschaft');
if ($subscriptionId > 0) {
    // Successful
}

Reuse subscription

As soon as a customer has successfully completed a payment, it's possibile to reuse the payment without the customer needs to re-enter the payment data again.

PHP SDK

Request
$subscription_id = 737;
$payment = new \SecucardConnect\Product\Payment\Model\SecupayCreditcard();
$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;

// Do not debit the buyer's funding source before the project is successful (only make a pre-authorization):
$payment->payment_action = $payment::PAYMENT_ACTION_AUTHORIZATION;

$payment = $service->save($payment);
Response
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
)