You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update license and remove version in composer.json
* Update license in composer.json
* Improve documentation for API reference of the SDK
* Move documentation folder
* Add version in the composer.json because we use it
* Fix validation exception when to be thrown
* Improve documentation about exceptions
* Fix parsing errors
* Add custom service for building custom requests to the API
* Improve documentation
* Add guides to the documentation
* Simplify the usage of the Authorization service
* Improve documentation about the authorization service
* Improve documentation about Checkouts service
* Fix annotations
* Fix conventions about namespaces
* Improve documentation about Custom service
* Fix documentation styles
* Improve documentation about Customer service
* Improve documentation about Merchant service
* Improve documentation about Payouts service
* Improve documentation about Transaction service
* Improve documentation about SumUp service
* Improve documentation about exceptions handling and also the links between files
* Version bump
* Minor improvements after code review
| Name | Description | Value | Default value | Required |
43
-
|--- |--- |--- |--- |--- |
44
-
|app_id | This is the client id that you receive after you [register](https://developer.sumup.com/docs/register-app) your application in SumUp |`string`|*No default value*| Yes |
45
-
|app_secret | This is the client secret that corresponds to the client id |`string`|*No default value*| Yes |
46
-
|grant_type | This indicates which authorization flow should be used to acquire OAuth token | One of: `authorization_code`, `client_credentials`, `password`| '`authorization_code`' | No |
47
-
|scopes | This is an array with all the [authorization scopes](https://developer.sumup.com/docs/authorization#authorization-scopes) that you need for your application |`array` with possible values: `payments`, `transactions.history`, `user.app-settings`, `user.profile_readonly`, `user.profile`, `user.subaccounts`, `user.payout-settings`, `balance`, `products`|`['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly']`| No |
48
-
|code | This is the code returned at the last step from [authorization code flow](https://developer.sumup.com/docs/authorization#authorization-flows)|`string`|`null`| Conditional (required only if `grant_type => 'authorization_code'`) |
49
-
|username | This is your SumUp's username if you want to use password authorization flow |`string`|`null`| Conditional (required only if `grant_type => 'password'`) |
50
-
|password | This is your SumUp's password if you want to use password authorization flow |`string`|`null`| Conditional (required only if `grant_type => 'password'`) |
51
-
|access_token | This is the value of a valid access token that is acquired through other methods. It is used if you don't want to request new access token |`string`|`null`| No |
52
-
|refresh_token | This is the refresh token through which can be requested new access token |`string`|`null`| No |
53
-
|use_guzzlehttp_over_curl | This is a configuration whether to use GuzzleHttp if both GuzzleHttp library and cURL module are installed. |`bool`|`false`| No |
54
-
|custom_headers | This sends custom headers with every http request to SumUp server |`array` with key-value pairs containing the header's name (as key) and the header's value (as value) |`[]`| No |
55
-
56
-
## Authorization
57
-
58
-
Every time you make an instance of the `\SumUp\SumUp` class you get a valid OAuth 2.0 access token. The access token is then passed automatically to every service call you make but of course you can override this (see examples below). In case you need the access token you can access it like this:
To get a particular service you first need to create a `\SumUp\SumUp` object. Then from this object you can get any of the services we support in the SDK.
151
-
152
-
Here is an example how to get transactions history:
> All services' methods return response of type `\SumUp\HttpClients\Response` or throw an exception (view [exceptions handling](https://github.com/sumup/sumup-ecom-php-sdk#exceptions-handling)).
176
-
177
-
## Exceptions handling
178
-
179
-
Exceptions handling is an important part of our code. We pay attention to this detail and **we recommend to wrap every statement from this SDK with a `try {} catch() {}` clause**.
180
-
181
-
You should at least handle `\SumUp\Exceptions\SumUpSDKException` exception but if you want you can handle all sorts of exceptions.
Here is a table with all the exceptions that are thrown from this SDK:
196
-
197
-
| Exception | Conditions |
198
-
|--- |--- |
199
-
|`\SumUp\Exceptions\SumUpAuthenticationException`| This exception is thrown when there is no access token or it is already expired. |
200
-
|`\SumUp\Exceptions\SumUpConnectionException`| This exception is thrown when there is connectivity issues over the network. |
201
-
|`\SumUp\Exceptions\SumUpResponseException`| This exception is thrown when there are some [4xx http errors](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_errors) such as `404 Not Found`. |
202
-
|`\SumUp\Exceptions\SumUpValidationException`| This exception is thrown when there is one or more wrong data send to the server. In the message there is information about which field(s) is incorrect. |
203
-
|`\SumUp\Exceptions\SumUpServerException`| This exception is thrown when there are http errors of [5xx](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_Server_errors). |
204
-
|`\SumUp\Exceptions\SumUpConfigurationException`| This exception is thrown when you provide a bad configuration for initialization of the `\SumUp\SumUp` object. |
205
-
|`\SumUp\Exceptions\SumUpArgumentException`| This exception is thrown when you don't provide a mandatory argument to a function. |
206
-
|`\SumUp\Exceptions\SumUpSDKException`| This is the main exception which others inherit from. So this is the last exception to handle in your code if you want to catch many exceptions.|
44
+
*[How to authorize?](https://github.com/sumup/sumup-ecom-php-sdk/blob/master/docs/HowToAuthorize.md)
45
+
*[How to handle exceptions?](https://github.com/sumup/sumup-ecom-php-sdk/blob/master/docs/ExceptionsHandling.md)
46
+
*[How to use my own HTTP client?](https://github.com/sumup/sumup-ecom-php-sdk/blob/master/docs/HowToOverrideHttpClient.md)
Exceptions handling is an important part of our code. We pay attention to this detail and **we recommend to wrap every statement from this SDK with a `try {} catch() {}` clause**.
4
+
5
+
You should at least handle `\SumUp\Exceptions\SumUpSDKException` exception but if you want you can handle all sorts of exceptions.
This guide will help you to authorize and get an OAuth 2.0 token using the SDK. If you want to know what happens behind the scenes you can visit this [authorization guide](https://developer.sumup.com/docs/authorization).
6
+
7
+
Every time you make an instance of the `\SumUp\SumUp` class you get a valid OAuth 2.0 access token. The access token is then passed to every service call you make (but of course you can [override](https://github.com/sumup/sumup-ecom-php-sdk/blob/master/docs/HowToOverrideHttpClient.md) this).
8
+
9
+
## Authorization code flow
10
+
11
+
> **Note:** this is the flow we recommend.
12
+
13
+
First you need to send the merchant to pass through the [authorization flow](https://developer.sumup.com/docs/authorization#1-your-application-requests-authorization) so you can get a `code` and after that you can continue with the following example code.
> **Note:** once you get a refresh token you can store it in a database and then use it to get new access tokens for the same merchant.
29
+
30
+
For more information about this flow read in [this guide](https://developer.sumup.com/docs/authorization#authorization-code-flow).
31
+
32
+
## Client credentials flow
33
+
34
+
If you want to use just the `client_id` and the `client_secret` you can use following snippet of code but keep in mind that not all endpoints can be requested with access token from this flow.
For more information about this flow read in [this guide](https://developer.sumup.com/docs/authorization#client-credentials-flow).
48
+
49
+
## Password flow
50
+
51
+
Here is an example how you can use the `password` flow. But also keep in mind that not all endpoints can be requested with access token from this flow.
// you need to call the method `refreshToken()` to get a new access token
78
+
$refreshedAccessToken = $sumup->refreshToken();
79
+
$value = $refreshedAccessToken->getValue();
80
+
```
81
+
82
+
> **Note:** keep in mind that the refresh token can also expire although it has long life span. For more information you can read [here](https://developer.sumup.com/docs/authorization#6-the-authorization-server-returns-an-access-token).
83
+
84
+
## How to reuse a valid access token
85
+
86
+
If you already have a valid access token you can reuse it like this:
We provide two clients for dealing with HTTP communication: `\SumUp\HttpClients\SumUpCUrlClient` and `\SumUp\HttpClients\SumUpGuzzleHttpClient`. We also give the option to use your own HTTP client if you want to.
6
+
7
+
## \SumUp\HttpClients\SumUpCUrlClient
8
+
9
+
The `SumUpCUrlClient` client provides functionality for creating HTTP requests and getting responses using the PHP module [cURL](http://php.net/manual/en/book.curl.php).
10
+
11
+
## \SumUp\HttpClients\SumUpGuzzleHttpClient
12
+
13
+
The `SumUpGuzzleHttpClient` client provides functionality for creating HTTP requests and getting responses using the open-source library [Guzzle](https://packagist.org/packages/guzzlehttp/guzzle). We support **version 6.x** of the library.
14
+
15
+
> **Note:** This library is not required for using this SDK.
16
+
17
+
## Create your own HTTP client
18
+
19
+
If you have another way of HTTP communication you can make a class that implements the interface `\SumUp\HttpClients\SumUpHttpClientInterface`. After that you can pass an instance of that class to the constructor of `\SumUp\SumUp` as second parameter. Then the SDK would use this client for every request to the SumUp's servers.
20
+
21
+
> **Note:** you also have to **handle** all the **responses** and all the **exceptions** that might occur.
0 commit comments