Merge pull request #124 from heidelpay/develop

Release 1.2.3.0

CHANGELOG.md

@@ -3,6 +3,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.2.3.0][1.2.3.0]
+
+### Added
+*   An example for `prepayment` payment method.
+*   An example for `invoice` payment method.
+*   Charge methods `getCancelledAmount` and `getTotalAmount`.
+*   Authorize method `getCancelledAmount`.
+*   Detailed `keypair` fetch.
+*   Added properties to keypair resource.
+
+### Fixed
+*   A problem with HeidelpayApiException.
+*   A problem which resulted in an error when trying to create a `customer` implicitly with a transaction when its `customerId` was set. 
+
+### Changed
+*   Replaced unreliable `Payment::cancel()` method with `Payment::cancelAmount()` which takes multiple cancellation scenarios into account.
+*   Replaced `ApiResponseCodes::API_ERROR_AUTHORIZE_ALREADY_CANCELLED` with `ApiResponseCodes::API_ERROR_ALREADY_CANCELLED`.
+*   Replaced `ApiResponseCodes::API_ERROR_CHARGE_ALREADY_CHARGED_BACK` with `ApiResponseCodes::API_ERROR_ALREADY_CHARGED_BACK`.
+*   Add deprecation notice for `Payment::cancelAllCharges` and `Payment::cancelAuthorization`
+*   Adapted integration tests with basket to changes in API.
+*   Refactor deprecation notices.
+*   Refactored and extended unit tests.
+*   Test keypair can now be set via environment variables.
+
 ## [1.2.2.0][1.2.2.0]
 
 ### Fixed
@@ -274,3 +298,4 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 [1.2.0.0]: https://github.com/heidelpay/heidelpayPHP/compare/1.1.6.0..1.2.0.0
 [1.2.1.0]: https://github.com/heidelpay/heidelpayPHP/compare/1.2.0.0..1.2.1.0
 [1.2.2.0]: https://github.com/heidelpay/heidelpayPHP/compare/1.2.1.0..1.2.2.0
+[1.2.3.0]: https://github.com/heidelpay/heidelpayPHP/compare/1.2.2.0..1.2.3.0

examples/Invoice/Constants.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * This file defines the constants needed for the Invoice example.
+ *
+ * Copyright (C) 2019 heidelpay GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @link  https://docs.heidelpay.com/
+ *
+ * @author  Simon Gabriel <[email protected]>
+ *
+ * @package  heidelpayPHP/examples
+ */
+
+require_once __DIR__ . '/../Constants.php';
+
+define('EXAMPLE_PATH', __DIR__);
+define('EXAMPLE_URL', EXAMPLE_BASE_FOLDER . 'Invoice');
+define('CONTROLLER_URL', EXAMPLE_URL . '/Controller.php');

examples/Invoice/Controller.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * This is the controller for the Invoice example.
+ * It is called when the pay button on the index page is clicked.
+ *
+ * Copyright (C) 2019 heidelpay GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @link  https://docs.heidelpay.com/
+ *
+ * @author  Simon Gabriel <[email protected]>
+ *
+ * @package  heidelpayPHP/examples
+ */
+
+/** Require the constants of this example */
+require_once __DIR__ . '/Constants.php';
+
+/** @noinspection PhpIncludeInspection */
+/** Require the composer autoloader file */
+require_once __DIR__ . '/../../../../autoload.php';
+
+use heidelpayPHP\examples\ExampleDebugHandler;
+use heidelpayPHP\Exceptions\HeidelpayApiException;
+use heidelpayPHP\Heidelpay;
+use heidelpayPHP\Resources\CustomerFactory;
+use heidelpayPHP\Resources\PaymentTypes\Invoice;
+
+session_start();
+session_unset();
+
+$clientMessage = 'Something went wrong. Please try again later.';
+$merchantMessage = 'Something went wrong. Please try again later.';
+
+function redirect($url, $merchantMessage = '', $clientMessage = '')
+{
+    $_SESSION['merchantMessage'] = $merchantMessage;
+    $_SESSION['clientMessage']   = $clientMessage;
+    header('Location: ' . $url);
+    die();
+}
+
+// Catch API errors, write the message to your log and show the ClientMessage to the client.
+try {
+    // Create a heidelpay object using your private key and register a debug handler if you want to.
+    $heidelpay = new Heidelpay(HEIDELPAY_PHP_PAYMENT_API_PRIVATE_KEY);
+    $heidelpay->setDebugMode(true)->setDebugHandler(new ExampleDebugHandler());
+
+    /** @var Invoice $invoice */
+    $invoice = $heidelpay->createPaymentType(new Invoice());
+
+    $customer = CustomerFactory::createCustomer('Max', 'Mustermann');
+    $orderId = str_replace(['0.', ' '], '', microtime(false));
+
+    $transaction = $invoice->charge(12.99, 'EUR', CONTROLLER_URL, $customer, $orderId);
+
+    // You'll need to remember the shortId to show it on the success or failure page
+    $_SESSION['ShortId'] = $transaction->getShortId();
+
+    // Redirect to the success or failure page depending on the state of the transaction
+    $payment = $transaction->getPayment();
+
+    if ($payment->isPending()) {
+        // In case of authorization this is normal since you will later charge the payment.
+        // You can create the order with status pending payment and show a success page to the customer if you want.
+
+        // In cases of redirection to an external service (e.g. 3D secure, PayPal, etc) it sometimes takes time for
+        // the payment to update it's status. In this case it might be pending at first and change to cancel or success later.
+        // Use the webhooks feature to stay informed about changes of the payment (e.g. cancel, success)
+        // then you can cancel the order later or mark it paid as soon as the event is triggered.
+
+        // In any case, the payment is not done when the payment is pending and you should ship until it changes to success.
+        redirect(PENDING_URL);
+    }
+    // If the payment is neither success nor pending something went wrong.
+    // In this case do not create the order.
+    // Redirect to an error page in your shop and show an message if you want.
+
+    // Check the result message of the transaction to find out what went wrong.
+    $merchantMessage = $transaction->getMessage()->getCustomer();
+} catch (HeidelpayApiException $e) {
+    $merchantMessage = $e->getMerchantMessage();
+    $clientMessage = $e->getClientMessage();
+} catch (RuntimeException $e) {
+    $merchantMessage = $e->getMessage();
+}
+redirect(FAILURE_URL, $merchantMessage, $clientMessage);

examples/Invoice/index.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * This file provides an example implementation of the Invoice payment type.
+ *
+ * Copyright (C) 2019 heidelpay GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @link  https://docs.heidelpay.com/
+ *
+ * @author  Simon Gabriel <[email protected]>
+ *
+ * @package  heidelpayPHP/examples
+ */
+
+/** Require the constants of this example */
+require_once __DIR__ . '/Constants.php';
+
+/** @noinspection PhpIncludeInspection */
+
+/** Require the composer autoloader file */
+require_once __DIR__ . '/../../../../autoload.php';
+?>
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>
+        Heidelpay UI Examples
+    </title>
+    <script src="https://code.jquery.com/jquery-3.1.1.min.js"
+            integrity="sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8=" crossorigin="anonymous"></script>
+
+    <link rel="stylesheet" href="https://static.heidelpay.com/v1/heidelpay.css" />
+</head>
+
+<body style="margin: 70px 70px 0;">
+
+<form id="payment-form" action="<?php echo CONTROLLER_URL; ?>" class="heidelpayUI form" novalidate>
+    <button class="heidelpayUI primary button fluid" id="submit-button" type="submit">Pay</button>
+</form>
+
+</body>
+</html>

examples/Prepayment/Constants.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * This file defines the constants needed for the Prepayment example.
+ *
+ * Copyright (C) 2019 heidelpay GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @link  https://docs.heidelpay.com/
+ *
+ * @author  Simon Gabriel <[email protected]>
+ *
+ * @package  heidelpayPHP/examples
+ */
+
+require_once __DIR__ . '/../Constants.php';
+
+define('EXAMPLE_PATH', __DIR__);
+define('EXAMPLE_URL', EXAMPLE_BASE_FOLDER . 'Prepayment');
+define('CONTROLLER_URL', EXAMPLE_URL . '/Controller.php');

examples/Prepayment/Controller.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * This is the controller for the Prepayment example.
+ * It is called when the pay button on the index page is clicked.
+ *
+ * Copyright (C) 2019 heidelpay GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @link  https://docs.heidelpay.com/
+ *
+ * @author  Simon Gabriel <[email protected]>
+ *
+ * @package  heidelpayPHP/examples
+ */
+
+/** Require the constants of this example */
+require_once __DIR__ . '/Constants.php';
+
+/** @noinspection PhpIncludeInspection */
+/** Require the composer autoloader file */
+require_once __DIR__ . '/../../../../autoload.php';
+
+use heidelpayPHP\examples\ExampleDebugHandler;
+use heidelpayPHP\Exceptions\HeidelpayApiException;
+use heidelpayPHP\Heidelpay;
+use heidelpayPHP\Resources\CustomerFactory;
+use heidelpayPHP\Resources\PaymentTypes\Prepayment;
+
+session_start();
+session_unset();
+
+$clientMessage = 'Something went wrong. Please try again later.';
+$merchantMessage = 'Something went wrong. Please try again later.';
+
+function redirect($url, $merchantMessage = '', $clientMessage = '')
+{
+    $_SESSION['merchantMessage'] = $merchantMessage;
+    $_SESSION['clientMessage']   = $clientMessage;
+    header('Location: ' . $url);
+    die();
+}
+
+// Catch API errors, write the message to your log and show the ClientMessage to the client.
+try {
+    // Create a heidelpay object using your private key and register a debug handler if you want to.
+    $heidelpay = new Heidelpay(HEIDELPAY_PHP_PAYMENT_API_PRIVATE_KEY);
+    $heidelpay->setDebugMode(true)->setDebugHandler(new ExampleDebugHandler());
+
+    /** @var Prepayment $prepayment */
+    $prepayment = $heidelpay->createPaymentType(new Prepayment());
+
+    $customer = CustomerFactory::createCustomer('Max', 'Mustermann');
+    $orderId = str_replace(['0.', ' '], '', microtime(false));
+
+    $transaction = $prepayment->charge(12.99, 'EUR', CONTROLLER_URL, $customer, $orderId);
+
+    // You'll need to remember the shortId to show it on the success or failure page
+    $_SESSION['ShortId'] = $transaction->getShortId();
+
+    // Redirect to the success or failure page depending on the state of the transaction
+    $payment = $transaction->getPayment();
+
+    if ($payment->isPending()) {
+        // In case of authorization this is normal since you will later charge the payment.
+        // You can create the order with status pending payment and show a success page to the customer if you want.
+
+        // In cases of redirection to an external service (e.g. 3D secure, PayPal, etc) it sometimes takes time for
+        // the payment to update it's status. In this case it might be pending at first and change to cancel or success later.
+        // Use the webhooks feature to stay informed about changes of the payment (e.g. cancel, success)
+        // then you can cancel the order later or mark it paid as soon as the event is triggered.
+
+        // In any case, the payment is not done when the payment is pending and you should ship until it changes to success.
+        redirect(PENDING_URL);
+    }
+    // If the payment is neither success nor pending something went wrong.
+    // In this case do not create the order.
+    // Redirect to an error page in your shop and show an message if you want.
+
+    // Check the result message of the transaction to find out what went wrong.
+    $merchantMessage = $transaction->getMessage()->getCustomer();
+} catch (HeidelpayApiException $e) {
+    $merchantMessage = $e->getMerchantMessage();
+    $clientMessage = $e->getClientMessage();
+} catch (RuntimeException $e) {
+    $merchantMessage = $e->getMessage();
+}
+redirect(FAILURE_URL, $merchantMessage, $clientMessage);