Binding a basket
- Joanna Wołosz
The article contains a description of the method used to bind a basket together with an example implementation of the method in PHP.
On this page:
Description of the method
The method intended to initialize the binding process for a basket using one of two methods: a qrCode or a phone number, and to transfer the browser information in order to add the browser to the trusted browsers.
Parameters
Field name | Description | Type | Requirement status | Additional remarks |
| Basket's unique ID assigned by the merchant | string | Y |
|
Request
Field name | Description | Type | Requirement status | Additional remarks |
| The chosen form of binding a basket two methods available [PHONE, DEEP_LINK]. PHONE – we inform, if the widget has transferred in the iziGetPayData method the parameters prefix - prefix phone number; PHONENumber- phone number DEEP_LINK – we inform, if the widget has failed to transfer the prefix in the iziGetPayData method and phoneNumber in iziGetPayData | string | O |
|
| The site of binding a basket in the Merchant's store (the place of embedding the widget). Available sites: PRODUCT_CARD, BASKET_SUMMARY, ORDER_CREATE, BASKET_POPUP, THANK_YOU_PAGE, We provide the value received from the widget from the field bindingPlace in iziGetPayData. PRODUCT_CARD - product card BASKET_SUMMARY - basket summary ORDER_CREATE - order creation stage BASKET_POPUP - basket side panel THANK_YOU_PAGE * -this is not the site for binding, but for embedding the widget, which should assume the dedicated Thank You Page form upon placing the order LOGIN_PAGE - login page CHECKOUT_PAGE - checkout page REGISTERFORM_PAGE - registerform page MINICART_PAGE - minicart.
| string | O |
|
| An object intended to transfer the phone number with which the basket is to be bound. The object only required if binding_method= PHONE. Data collected from the method iziCanBeBound | object | O |
|
| Prefix. Collected from the iziGetPayData prefix, and transferred in the format with the character "+". | string | Y | |
| Phone number taken from phoneNumber iziGetPayData | string | Y | |
| An object intended to transfer information related to the browser which the customer currently uses, and it binds the basket in order to add the browser to the trusted browsers. | object | Y |
|
| User agent | string | Y | |
| Browser Name | string | O | |
| The platform | string | Y | |
| Architecture | string | Y | |
| Date | string($date-time) | Y | |
| Location | string | Y | |
| Customer IP | string | Y | |
| Port | string | Y |
Response
202 – an empty response when the binding takes place with the use of a phone number (binding_method= PHONE)
200
Response
Field name | Description | Type | Requirement status | Additional remarks |
| QrCode generated | string | O |
|
| Deep link for the Android/iOs systems | String | O |
|
| Deep link for the HMS system – currently not used | String | O |
|
POST /v1/izi/basket/{basket_id}/binding
Example request
{
"binding_method": "PHONE",
"binding_place": "PRODUCT_CARD",
"phone_number": {
"country_prefix": "+48",
"phone": "5xxxxxxxx"
},
"browser": {
"user_agent": "Testzilla 1.0",
"description": "Test agent",
"platform": "Ino Linux 2.0",
"architecture": "x86-646",
"data_time": "2023-08-24T08:52:01.113Z",
"location": "-",
"customer_ip": "127.0.0.1",
"port": "8080"
}
}
Example implementation in PHP
Entering the code -
Only the postBasketBinding function has been added in the implementacjaKlienta.txt file.
/**
* Client symfony implementation used for communication between Merchant and InPost Pay application.
*
* @param InpostPayBearerServiceInterface $inpostPayBearerService <p> Bearer service interface,
* with contains creating bearer token which is required for communication with Inpost Pay </p>
*
*/
final class InpostPayClient implements InpostPayClientInterface
{
private ClientInterface $client;
private InpostPayURLCreatorInterface $URLCreator;
private InpostPayBearerServiceInterface $bearerService;
public function __construct(
ClientInterface $client,
InpostPayURLCreatorInterface $URLCreator,
InpostPayBearerServiceInterface $bearerService
) {
$this->client = $client;
$this->URLCreator = $URLCreator;
$this->bearerService = $bearerService;
}
public function postBasketBinding(string $basketId, BasketBindingRequest $requestBody): ?QrCodeData
{
if (BindingMethod::PHONE()->equals($requestBody->getBindingMethod()) && !$requestBody->getPhoneNumber()) {
throw InpostPayPostBasketBindingException::createNoPhoneForPhoneBindingMethodException();
}
$path = sprintf('basket/%s/binding', $basketId);
$uri = new Uri($this->buildUri($path));
/** @var string $body */
$body = json_encode($requestBody);
$request = new Request(
'POST',
$uri,
$this->provideDefaultClientHeaders(),
$body
);
try {
$response = $this->client->sendRequest($request);
$statusCode = $response->getStatusCode();
$content = $response->getBody()->getContents();
if (HttpResponseStatus::ACCEPTED()->getValue() === $statusCode) {
return null;
}
if (HttpResponseStatus::OK()->getValue() === $statusCode) {
/**
* @var QrCodeDataArray $data
*/
$data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);
return QrCodeData::fromArray($data);
}
} catch (\Throwable $throwable) {
throw InpostPayPostBasketBindingException::createResponseException($throwable);
}
throw InpostPayPostBasketBindingException::createBadStatusCodeException($statusCode, $content);
}
public function putBasket(string $basketId, Basket $basket): InpostBasketId
{
$path = sprintf('basket/%s', $basketId);
$uri = new Uri($this->buildUri($path));
/** @var string $body */
$body = json_encode($basket);
$request = new Request(
'PUT',
$uri,
$this->provideDefaultClientHeaders(),
$body
);
try {
$response = $this->client->sendRequest($request);
$content = $response->getBody()->getContents();
/**
* @var array{inpost_basket_id: string} $responseData
*/
$responseData = json_decode($content, true, 512, JSON_THROW_ON_ERROR);
return InpostBasketId::fromArray($responseData);
} catch (\Throwable $throwable) {
throw InpostPayPutBasketException::createResponseException($throwable);
}
}
public function deleteBasketBinding(string $basketId, bool $ifBasketRealized = null): void
{
$path = sprintf('basket/%s/binding', $basketId);
$uri = (new Uri($this->buildUri($path)))
->withQuery(Psr7\Query::build(['if_basket_realized' => $ifBasketRealized]));
$request = new Request(
'DELETE',
$uri,
$this->provideDefaultClientHeaders()
);
try {
$response = $this->client->sendRequest($request);
$statusCode = $response->getStatusCode();
$content = $response->getBody()->getContents();
} catch (\Throwable $throwable) {
throw InpostPayDeleteBasketBindingException::createResponseException($throwable);
}
if (HttpResponseStatus::NO_CONTENT()->getValue() === $statusCode) {
return;
}
throw InpostPayDeleteBasketBindingException::createBadStatusCodeException($statusCode, $content);
}
public function deleteBrowserBinding(string $browserId): void
{
$path = sprintf('browser/%s/binding', $browserId);
$uri = new Uri($this->buildUri($path));
$request = new Request(
'DELETE',
$uri,
$this->provideDefaultClientHeaders()
);
try {
$response = $this->client->sendRequest($request);
$statusCode = $response->getStatusCode();
$content = $response->getBody()->getContents();
} catch (\Throwable $throwable) {
throw InpostPayDeleteBrowserBindingException::createResponseException($throwable);
}
if (HttpResponseStatus::NO_CONTENT()->getValue() === $statusCode) {
return;
}
throw InpostPayDeleteBrowserBindingException::createBadStatusCodeException($statusCode, $content);
}
public function getSigningKey(string $version): SigningKeyResponse
{
$path = sprintf('signing-keys/public/%s', $version);
$uri = new Uri($this->buildUri($path));
$request = new Request(
'GET',
$uri,
$this->provideDefaultClientHeaders()
);
try {
$response = $this->client->sendRequest($request);
$statusCode = $response->getStatusCode();
$content = $response->getBody()->getContents();
if (HttpResponseStatus::OK()->getValue() === $statusCode) {
/**
* @var SigningKeyResponseArray $data
*/
$data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);
return SigningKeyResponse::fromArray($data);
}
} catch (\Throwable $throwable) {
throw InpostPayGetSigningKeyException::createResponseException($throwable);
}
throw InpostPayGetSigningKeyException::createBadStatusCodeException($statusCode, $content);
}
public function getSigningKeys(): SigningKeysResponse
{
$path = 'signing-keys/public';
$uri = new Uri($this->buildUri($path));
$request = new Request(
'GET',
$uri,
$this->provideDefaultClientHeaders()
);
try {
$response = $this->client->sendRequest($request);
$statusCode = $response->getStatusCode();
$content = $response->getBody()->getContents();
if (HttpResponseStatus::OK()->getValue() === $statusCode) {
/**
* @var SigningKeysResponseArray $data
*/
$data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);
return SigningKeysResponse::fromArray($data);
}
} catch (\Throwable $throwable) {
throw InpostPayGetSigningKeysException::createResponseException($throwable);
}
throw InpostPayGetSigningKeysException::createBadStatusCodeException($statusCode, $content);
}
/**
* @return array{
* Authorization: string,
* Content-Type: string
* }
*
* @throws InpostPayEndpointException
*/
private function provideDefaultClientHeaders(): array
{
return [
'Authorization' => sprintf('Bearer %s', $this->bearerService->getBearerToken()),
'Content-Type' => 'application/json',
];
}
private function buildUri(string $path): string
{
return sprintf(
'%s%s',
$this->URLCreator->create()->getUrl(),
$path
);
}
}
SDK.zip contains a code which includes the object of the request and of the endpoint response.
