Skip to content

Commit dcd68f3

Browse files
Miguel-MultiSafepaydanielcivit
Miguel-MultiSafepay
and
danielcivit
authored
PLGWOOS-1025: PHP SDK support for terminal endpoints (#391)
--------- Co-authored-by: Daniel Civit <daniel.civit@multisafepay.com>
1 parent d21d975 commit dcd68f3

10 files changed

Lines changed: 818 additions & 0 deletions

File tree

‎USAGE.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -395,6 +395,49 @@ $transactions = $transactionListing->getTransactions();
395395
$pager = $transactionListing->getPager(); // If pagination is needed, this Pager object can be used
396396
```
397397

398+
### List terminals
399+
List all POS terminals bound to a MultiSafepay account.
400+
401+
Authentication for this endpoint requires a **Merchant Account API Key**. Note: according to the public API documentation, this endpoint is not available in the TEST environment.
402+
More information at our [Documentation Center](https://docs.multisafepay.com/reference/listterminals).
403+
```php
404+
$yourMerchantAccountApiKey = 'your-merchant-account-api-key';
405+
$isProduction = true;
406+
$multiSafepaySdk = new \MultiSafepay\Sdk($yourMerchantAccountApiKey, $isProduction);
407+
408+
$options = [
409+
'page' => 1,
410+
'limit' => 50,
411+
];
412+
413+
$terminalListing = $multiSafepaySdk->getTerminalManager()->getTerminals($options);
414+
$terminals = $terminalListing->getTerminals();
415+
416+
$pager = $terminalListing->getPager(); // If pagination is needed, this Pager object can be used
417+
```
418+
419+
### List terminals by group
420+
Filter POS devices bound to a MultiSafepay account using a `terminal_group_id`.
421+
422+
Authentication for this endpoint requires a **Merchant Account API Key**. Note: according to the public API documentation, this endpoint is not available in the TEST environment.
423+
More information at our [Documentation Center](https://docs.multisafepay.com/reference/listterminalsbygroup).
424+
```php
425+
$yourMerchantAccountApiKey = 'your-merchant-account-api-key';
426+
$isProduction = true;
427+
$multiSafepaySdk = new \MultiSafepay\Sdk($yourMerchantAccountApiKey, $isProduction);
428+
429+
$terminalGroupId = 'your-terminal-group-id';
430+
$options = [
431+
'page' => 1,
432+
'limit' => 50,
433+
];
434+
435+
$terminalListing = $multiSafepaySdk->getTerminalManager()->getTerminalsByGroup($terminalGroupId, $options);
436+
$terminals = $terminalListing->getTerminals();
437+
438+
$pager = $terminalListing->getPager(); // If pagination is needed, this Pager object can be used
439+
```
440+
398441
### Pushing a payment request to a Smart POS device
399442
```php
400443
use MultiSafepay\ValueObject\Customer\Country;

‎src/Api/TerminalManager.php‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
<?php declare(strict_types=1);
2+
/**
3+
* Copyright © MultiSafepay, Inc. All rights reserved.
4+
* See DISCLAIMER.md for disclaimer details.
5+
*/
6+
7+
namespace MultiSafepay\Api;
8+
9+
use MultiSafepay\Api\Terminals\TerminalListing;
10+
use MultiSafepay\Exception\ApiException;
11+
use Psr\Http\Client\ClientExceptionInterface;
12+
13+
/**
14+
* Class TerminalManager
15+
*
16+
* @package MultiSafepay\Api
17+
*/
18+
class TerminalManager extends AbstractManager
19+
{
20+
private const ALLOWED_OPTIONS = [
21+
'page' => '',
22+
'limit' => '',
23+
];
24+
25+
/**
26+
* List POS terminals filtered by a terminal group id.
27+
*
28+
* Authentication for this endpoint requires a Merchant Account API Key.
29+
*
30+
* @param string $terminalGroupId
31+
* @param array $options
32+
* @return TerminalListing
33+
* @throws ClientExceptionInterface|ApiException
34+
*/
35+
public function getTerminalsByGroup(string $terminalGroupId, array $options = []): TerminalListing
36+
{
37+
$options = array_intersect_key($options, self::ALLOWED_OPTIONS);
38+
39+
$endpoint = 'json/terminal-groups/' . $terminalGroupId . '/terminals';
40+
$context = ['terminal_group_id' => $terminalGroupId];
41+
42+
$response = $this->client->createGetRequest($endpoint, $options, $context);
43+
44+
return new TerminalListing($response->getResponseData(), $response->getPager());
45+
}
46+
47+
/**
48+
* List all POS terminals bound to a MultiSafepay account.
49+
*
50+
* Authentication for this endpoint requires a Merchant Account API Key.
51+
*
52+
* @param array $options
53+
* @return TerminalListing
54+
* @throws ClientExceptionInterface|ApiException
55+
*/
56+
public function getTerminals(array $options = []): TerminalListing
57+
{
58+
$options = array_intersect_key($options, self::ALLOWED_OPTIONS);
59+
$response = $this->client->createGetRequest('json/terminals', $options);
60+
61+
return new TerminalListing($response->getResponseData(), $response->getPager());
62+
}
63+
}

‎src/Api/Terminals/Terminal.php‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
<?php declare(strict_types=1);
2+
/**
3+
* Copyright © MultiSafepay, Inc. All rights reserved.
4+
* See DISCLAIMER.md for disclaimer details.
5+
*/
6+
7+
namespace MultiSafepay\Api\Terminals;
8+
9+
use MultiSafepay\Api\Base\ResponseBody;
10+
use MultiSafepay\Exception\InvalidDataInitializationException;
11+
12+
/**
13+
* Class Terminal
14+
*
15+
* Represents a POS terminal as returned by the API.
16+
* The exact fields may evolve; use getData() for forward compatibility.
17+
*/
18+
class Terminal extends ResponseBody
19+
{
20+
public const ID_KEY = 'id';
21+
public const PROVIDER_KEY = 'provider';
22+
public const NAME_KEY = 'name';
23+
public const CODE_KEY = 'code';
24+
public const CREATED_KEY = 'created';
25+
public const LAST_UPDATED_KEY = 'last_updated';
26+
public const MANUFACTURER_ID_KEY = 'manufacturer_id';
27+
public const SERIAL_NUMBER_KEY = 'serial_number';
28+
public const ACTIVE_KEY = 'active';
29+
public const GROUP_ID_KEY = 'group_id';
30+
public const COUNTRY_KEY = 'country';
31+
32+
/**
33+
* Terminal constructor.
34+
*
35+
* @param array $data
36+
* @throws InvalidDataInitializationException
37+
*/
38+
public function __construct(array $data = [])
39+
{
40+
$this->validate($data);
41+
parent::__construct($data);
42+
}
43+
44+
/**
45+
* Validate required fields
46+
*
47+
* @param array $data
48+
* @return void
49+
* @throws InvalidDataInitializationException
50+
*/
51+
private function validate(array $data): void
52+
{
53+
if (empty($data[self::ID_KEY])) {
54+
throw new InvalidDataInitializationException('Missing required field: ID');
55+
}
56+
57+
if (empty($data[self::PROVIDER_KEY])) {
58+
throw new InvalidDataInitializationException('Missing required field: Provider');
59+
}
60+
61+
if (empty($data[self::NAME_KEY])) {
62+
throw new InvalidDataInitializationException('Missing required field: Name');
63+
}
64+
}
65+
66+
/**
67+
* Get the terminal ID
68+
*
69+
* @return string
70+
*/
71+
public function getId(): string
72+
{
73+
return (string)$this->get(self::ID_KEY);
74+
}
75+
76+
/**
77+
* Get the terminal provider
78+
*
79+
* @return string
80+
*/
81+
public function getProvider(): string
82+
{
83+
return (string)$this->get(self::PROVIDER_KEY);
84+
}
85+
86+
/**
87+
* Get the terminal name
88+
*
89+
* @return string
90+
*/
91+
public function getName(): string
92+
{
93+
return (string)$this->get(self::NAME_KEY);
94+
}
95+
96+
/**
97+
* Get the terminal code
98+
*
99+
* @return string|null
100+
*/
101+
public function getCode(): ?string
102+
{
103+
$code = $this->get(self::CODE_KEY);
104+
return $code !== null ? (string)$code : null;
105+
}
106+
107+
/**
108+
* Get the terminal creation date
109+
*
110+
* @return string|null
111+
*/
112+
public function getCreated(): ?string
113+
{
114+
$created = $this->get(self::CREATED_KEY);
115+
return $created !== null ? (string)$created : null;
116+
}
117+
118+
/**
119+
* Get the terminal last updated date
120+
*
121+
* @return string|null
122+
*/
123+
public function getLastUpdated(): ?string
124+
{
125+
$lastUpdated = $this->get(self::LAST_UPDATED_KEY);
126+
return $lastUpdated !== null ? (string)$lastUpdated : null;
127+
}
128+
129+
/**
130+
* Get the terminal manufacturer ID
131+
*
132+
* @return string|null
133+
*/
134+
public function getManufacturerId(): ?string
135+
{
136+
$manufacturerId = $this->get(self::MANUFACTURER_ID_KEY);
137+
return $manufacturerId !== null ? (string)$manufacturerId : null;
138+
}
139+
140+
/**
141+
* Get the terminal serial number
142+
*
143+
* @return string|null
144+
*/
145+
public function getSerialNumber(): ?string
146+
{
147+
$serialNumber = $this->get(self::SERIAL_NUMBER_KEY);
148+
return $serialNumber !== null ? (string)$serialNumber : null;
149+
}
150+
151+
/**
152+
* Check if the terminal is active
153+
*
154+
* @return bool
155+
*/
156+
public function isActive(): bool
157+
{
158+
return (bool)$this->get(self::ACTIVE_KEY);
159+
}
160+
161+
/**
162+
* Get the terminal group ID
163+
*
164+
* @return int|null
165+
*/
166+
public function getGroupId(): ?int
167+
{
168+
$groupId = $this->get(self::GROUP_ID_KEY);
169+
return $groupId !== null ? (int)$groupId : null;
170+
}
171+
172+
/**
173+
* Get the terminal country code
174+
*
175+
* @return string|null
176+
*/
177+
public function getCountry(): ?string
178+
{
179+
$country = $this->get(self::COUNTRY_KEY);
180+
return $country !== null ? (string)$country : null;
181+
}
182+
}

‎src/Api/Terminals/TerminalListing.php‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?php declare(strict_types=1);
2+
/**
3+
* Copyright © MultiSafepay, Inc. All rights reserved.
4+
* See DISCLAIMER.md for disclaimer details.
5+
*/
6+
7+
namespace MultiSafepay\Api\Terminals;
8+
9+
use MultiSafepay\Api\Pager\Pager;
10+
11+
class TerminalListing
12+
{
13+
/**
14+
* @var Terminal[]
15+
*/
16+
private $terminals;
17+
18+
/**
19+
* @var Pager|null
20+
*/
21+
private $pager;
22+
23+
/**
24+
* @param array $data
25+
* @param Pager|null $pager
26+
*/
27+
public function __construct(array $data, ?Pager $pager = null)
28+
{
29+
$terminals = [];
30+
if (!empty($data)) {
31+
foreach ($data as $terminalData) {
32+
$terminals[] = new Terminal((array)$terminalData);
33+
}
34+
}
35+
$this->terminals = $terminals;
36+
37+
if (isset($pager)) {
38+
$this->pager = $pager;
39+
}
40+
}
41+
42+
/**
43+
* @return Terminal[]
44+
*/
45+
public function getTerminals(): array
46+
{
47+
return $this->terminals;
48+
}
49+
50+
/**
51+
* @return array
52+
*/
53+
public function asArray(): array
54+
{
55+
$terminals = [];
56+
foreach ($this->terminals as $terminal) {
57+
$terminals[] = $terminal->getData();
58+
}
59+
60+
return $terminals;
61+
}
62+
63+
/**
64+
* @return Pager|null
65+
*/
66+
public function getPager(): ?Pager
67+
{
68+
return $this->pager ?? null;
69+
}
70+
}

‎src/Sdk.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
use MultiSafepay\Api\GatewayManager;
1313
use MultiSafepay\Api\IssuerManager;
1414
use MultiSafepay\Api\PaymentMethodManager;
15+
use MultiSafepay\Api\TerminalManager;
1516
use MultiSafepay\Api\TokenManager;
1617
use MultiSafepay\Api\TransactionManager;
1718
use MultiSafepay\Api\WalletManager;
@@ -143,6 +144,14 @@ public function getCategoryManager(): CategoryManager
143144
return new CategoryManager($this->client);
144145
}
145146

147+
/**
148+
* @return TerminalManager
149+
*/
150+
public function getTerminalManager(): TerminalManager
151+
{
152+
return new TerminalManager($this->client);
153+
}
154+
146155
/**
147156
* @return Client
148157
*/

0 commit comments

Comments
 (0)