-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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
- Loading branch information
1 parent
94beefb
commit 44ecfab
Showing
33 changed files
with
1,120 additions
and
213 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # Exceptions handling | ||
|
|
||
| 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**. | ||
|
|
||
| You should at least handle `\SumUp\Exceptions\SumUpSDKException` exception but if you want you can handle all sorts of exceptions. | ||
|
|
||
| ```php | ||
| try { | ||
| $sumup = new \SumUp\SumUp($config); | ||
| } catch (\SumUp\Exceptions\SumUpAuthenticationException $e) { | ||
| echo $e->getCode() . ': ' . $e->getMessage(); | ||
| } catch (\SumUp\Exceptions\SumUpResponseException $e) { | ||
| echo $e->getCode() . ': ' . $e->getMessage(); | ||
| } catch (\SumUp\Exceptions\SumUpSDKException $e) { | ||
| echo $e->getCode() . ': ' . $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| More information about the exceptions can be found in [the reference](https://github.com/sumup/sumup-ecom-php-sdk/tree/master/docs#exceptions). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| # How to authorize using the SDK | ||
|
|
||
| ## Overview | ||
|
|
||
| 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). | ||
|
|
||
| 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). | ||
|
|
||
| ## Authorization code flow | ||
|
|
||
| > **Note:** this is the flow we recommend. | ||
| 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. | ||
|
|
||
| ```php | ||
| $sumup = new \SumUp\SumUp([ | ||
| 'app_id' => 'YOUR-CLIENT-ID', | ||
| 'app_secret' => 'YOUR-CLIENT-SECRET', | ||
| 'grant_type' => 'authorization_code', | ||
| 'scope' => ['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly'], | ||
| 'code' => 'YOUR-AUTHORIZATION-CODE' | ||
| ]); | ||
| $accessToken = $sumup->getAccessToken(); | ||
| $refreshToken = $accessToken->getRefreshToken(); | ||
| $value = $accessToken->getValue(); | ||
| ``` | ||
|
|
||
| > **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. | ||
| For more information about this flow read in [this guide](https://developer.sumup.com/docs/authorization#authorization-code-flow). | ||
|
|
||
| ## Client credentials flow | ||
|
|
||
| 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. | ||
|
|
||
| ```php | ||
| $sumup = new \SumUp\SumUp([ | ||
| 'app_id' => 'YOUR-CLIENT-ID', | ||
| 'app_secret' => 'YOUR-CLIENT-SECRET', | ||
| 'grant_type' => 'client_credentials', | ||
| 'scope' => ['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly'] | ||
| ]); | ||
| $accessToken = $sumup->getAccessToken(); | ||
| $value = $accessToken->getValue(); | ||
| ``` | ||
|
|
||
| For more information about this flow read in [this guide](https://developer.sumup.com/docs/authorization#client-credentials-flow). | ||
|
|
||
| ## Password flow | ||
|
|
||
| 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. | ||
|
|
||
| ```php | ||
| $sumup = new \SumUp\SumUp([ | ||
| 'app_id' => 'YOUR-CLIENT-ID', | ||
| 'app_secret' => 'YOUR-CLIENT-SECRET', | ||
| 'grant_type' => 'password', | ||
| 'scope' => ['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly'], | ||
| 'username' => 'YOUR-SUMUP-USERNAME', | ||
| 'password' => 'YOUR-SUMUP-PASSWORD' | ||
| ]); | ||
| $accessToken = $sumup->getAccessToken(); | ||
| $value = $accessToken->getValue(); | ||
| ``` | ||
|
|
||
| ## How to get new access from a refresh token | ||
|
|
||
| Here is how to get a **new access token from a refresh token**: | ||
|
|
||
| ```php | ||
| $sumup = new \SumUp\SumUp([ | ||
| 'app_id' => 'YOUR-CLIENT-ID', | ||
| 'app_secret' => 'YOUR-CLIENT-SECRET', | ||
| 'scope' => ['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly'], | ||
| 'refresh_token' => 'REFRESH-TOKEN' | ||
| ]); | ||
| // you need to call the method `refreshToken()` to get a new access token | ||
| $refreshedAccessToken = $sumup->refreshToken(); | ||
| $value = $refreshedAccessToken->getValue(); | ||
| ``` | ||
|
|
||
| > **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). | ||
| ## How to reuse a valid access token | ||
|
|
||
| If you already have a valid access token you can reuse it like this: | ||
|
|
||
| ```php | ||
| $sumup = new \SumUp\SumUp([ | ||
| 'app_id' => 'YOUR-CLIENT-ID', | ||
| 'app_secret' => 'YOUR-CLIENT-SECRET', | ||
| 'scope' => ['payments', 'transactions.history', 'user.app-settings', 'user.profile_readonly'], | ||
| 'access_token' => 'VALID-ACCESS-TOKEN' | ||
| ]); | ||
| ``` | ||
|
|
||
| ## Override access token for a service | ||
|
|
||
| You can always initialize a service with an access token that is different from the one you already have from your `SumUp\SumUp` instance. | ||
|
|
||
| ```php | ||
| $checkoutService = $sumup->getCheckoutService('ACCESS-TOKEN-INSTANCE'); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # How to override HttpClient | ||
|
|
||
| ## Overview | ||
|
|
||
| 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. | ||
|
|
||
| ## \SumUp\HttpClients\SumUpCUrlClient | ||
|
|
||
| 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). | ||
|
|
||
| ## \SumUp\HttpClients\SumUpGuzzleHttpClient | ||
|
|
||
| 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. | ||
|
|
||
| > **Note:** This library is not required for using this SDK. | ||
| ## Create your own HTTP client | ||
|
|
||
| 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. | ||
|
|
||
| > **Note:** you also have to **handle** all the **responses** and all the **exceptions** that might occur. |
Oops, something went wrong.