Merge pull request #28 from Ticketpark/v3-wip

v3

.github/contributing.md

@@ -0,0 +1,30 @@
+# Contributing to this library
+
+🎉  Thanks for being interested in contributing to this library!
+
+## Basics
+
+* Follow [Symfony coding standards](http://symfony.com/doc/current/contributing/code/standards.html)
+* Write useful commit messages
+* Be nice and respect others
+
+## Technical guidelines
+
+### Request containers
+
+* Put mandatory properties into the constructor
+* No setters for data which is set in constructor
+
+Note that some data seems to be mandatory, but is not marked as such in the Saferpay docs. We strictly follow the
+information in the Saferpay docs and keep all data optional unless Saferpay explicity marks
+it as mandatory.
+
+### Response containers
+
+* No constructors
+* No setters
+* All properties are optional
+
+Even though in the Saferpay doc some data is marked as mandatory in responses, we keep them all optional in this
+library because it is not in our control whether this data will actually be provided or not.
+

README.md

@@ -15,29 +15,29 @@ composer require ticketpark/saferpay-json-api
 ```
 
 ## Usage
-See [example folder](/example).
+In order to perform a payment as you would typically do it in an online shop, you need to handle the following steps:
 
+1. Initialize the payment page (see [/example/PaymentPage/example-initialize.php](/example/PaymentPage/example-initialize.php))
+2. Redirect the user to the payment page and let them enter their payment data
+3. Assert that the payment was successfully done (see [/example/PaymentPage/example-assert.php](/example/PaymentPage/example-assert.php))
+4. Capture the payment to make it final (see [/example/Transaction/example-capture.php](/example/Transaction/example-capture.php))
 
-## Documentation
+Have a look at the [example folder](/example) for more.
 
-This library is based on v1.2 of the Saferpay JSON API:
-https://saferpay.github.io/jsonapi/1.2/
+## Documentation
 
-## Roadmap
+Find the most current documentation of the Saferpay JSON API here:<br>
+https://saferpay.github.io/jsonapi/
 
-* v3 will be based on the most recent version of the Saferpay API (currently v1.17)
-* v2.3 added support for PHP 7.4
-* v2 added type-hints with major refactoring and required PHP 7.3
-* v1 was the initial version of this library based on PHP 5.6 and the Saferpay API v1.2
+This library is currently based on v1.17 of the Saferpay JSON API.
 
 ## Contribution
-You are welcome to contribute to this repo.
+You are [welcome to contribute](/.github/contributing.md) to this repo.
 
-* Follow [Symfony coding standards](http://symfony.com/doc/current/contributing/code/standards.html)
-* Write useful commit messages
-* Be nice and respect others
 
-## License
-This bundle is under the MIT license. See the complete license in the bundle:
+## History
 
-    Resources/meta/LICENSE
+* v3 added more major refactoring and based on current version of Saferpay API
+* v2.3 added support for PHP 7.4
+* v2 added type-hints with major refactoring and required PHP 7.3
+* v1 was the initial version of this library based on PHP 5.6 and the Saferpay API v1.2

example/PaymentPage/example-assert.php

@@ -0,0 +1,50 @@
+<?php declare(strict_types=1);
+
+use Ticketpark\SaferpayJson\Request\Exception\SaferpayErrorException;
+use Ticketpark\SaferpayJson\Request\RequestConfig;
+use Ticketpark\SaferpayJson\Request\PaymentPage\AssertRequest;
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+require_once __DIR__ . '/../credentials.php';
+
+// A token you received after initializing a payment page (see example-assert.php)
+
+$token = 'xxx';
+
+// -----------------------------
+// Step 1:
+// Prepare the assert request
+// See http://saferpay.github.io/jsonapi/#Payment_v1_PaymentPage_Assert
+
+$requestConfig = new RequestConfig(
+    $apiKey,
+    $apiSecret,
+    $customerId,
+    true
+);
+
+// -----------------------------
+// Step 2:
+// Create the request with required data
+
+$assertRequest = new AssertRequest(
+    $requestConfig,
+    $token,
+);
+
+// -----------------------------
+// Step 3:
+// Execute and check for successful response
+
+try {
+    $response = $assertRequest->execute();
+} catch (SaferpayErrorException $e) {
+    die ($e->getErrorResponse()->getErrorMessage());
+}
+
+echo 'The transaction has been successful! Transaction id: ' . $response->getTransaction()->getId()."\n";
+
+// -----------------------------
+// Step 4:
+// Capture the transaction to get the cash flowing.
+// See ../Transaction/example-capture.php

example/PaymentPage/example-initialize.php

@@ -0,0 +1,79 @@
+<?php declare(strict_types=1);
+
+use Ticketpark\SaferpayJson\Request\Exception\SaferpayErrorException;
+use Ticketpark\SaferpayJson\Request\PaymentPage\InitializeRequest;
+use Ticketpark\SaferpayJson\Request\RequestConfig;
+use Ticketpark\SaferpayJson\Request\Container;
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+require_once __DIR__ . '/../credentials.php';
+
+// -----------------------------
+// Step 1:
+// Initialize the required payment page data
+// See https://saferpay.github.io/jsonapi/#Payment_v1_PaymentPage_Initialize
+
+$requestConfig = new RequestConfig(
+    $apiKey,
+    $apiSecret,
+    $customerId,
+    true
+);
+
+$amount = new Container\Amount(
+    5000, // amount in cents
+    'CHF'
+);
+
+$payment = new Container\Payment($amount);
+$payment->setDescription('Order No. 12839');
+
+$returnUrls = new Container\ReturnUrls(
+    'http://www.mysite.ch/success?orderId=12839',
+    'http://www.mysite.ch/fail'
+);
+
+// -----------------------------
+// Step 2:
+// Create the request with required data
+
+$initializeRequest = new InitializeRequest(
+    $requestConfig,
+    $terminalId,
+    $payment,
+    $returnUrls
+);
+
+// Note: More data can be provided to InitializeRequest with setters,
+// for example: $initializeRequest->setPayer()
+// See Saferpay documentation for available options.
+
+// -----------------------------
+// Step 3:
+// Execute and check for successful response
+
+try {
+    $response = $initializeRequest->execute();
+} catch (SaferpayErrorException $e) {
+    die ($e->getErrorResponse()->getErrorMessage());
+}
+
+// -----------------------------
+// Step 4:
+// Save the response token, you will need it later to verify the payment (see step 7)
+echo 'Payment token: ' . $response->getToken() . "<br>\n";
+
+// -----------------------------
+// Step 5:
+// Redirect to the payment page
+echo 'Redirect to: ' . $response->getRedirectUrl() ."<br>\n";
+
+// -----------------------------
+// Step 6:
+// Fill in test payment page. For dummy credit card numbers see
+// https://saferpay.github.io/sndbx/paymentmeans.html
+
+// -----------------------------
+// Step 7:
+// On success page and notification url, assert that the payment has been successful.
+// -> see example-assert.php