Binding a basket

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:

1 Description of the method
2 Example implementation in PHP

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_id`	Basket's unique ID assigned by the merchant	string	Y

Request

Field name	Description	Type	Requirement status	Additional remarks
`binding_method`	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	`"binding_method":"DEEP_LINK"`
`binding_place`	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, LOGIN_PAGE, CHECKOUT_PAGE, REGISTERFORM_PAGE, MINICART_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	`"binding_place":"PRODUCT_CARD"`
`phone_number`	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	`"phone_number":{"country_prefix":"+48","phone":"600000000"}`
`phone_number.country_prefix`	Prefix. Collected from the iziGetPayData prefix, and transferred in the format with the character "+".	string	Y
`phone_number.phone`	Phone number taken from phoneNumber iziGetPayData	string	Y
`browser`	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	`"browser":{"user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 16_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Mobile/15E148 Safari/604.1","description":"Safari","platform":"iPhone","architecture":"5.0 (iPhone; CPU iPhone OS 16_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Mobile/15E148 Safari/604.1","data_time":"2023-08-14T12:47:45.000Z","location":"-","customer_ip":"000.000.000.00","port":"443"}}`
`browser.user_agent`	User agent	string	Y
`browser.description`	Browser Name	string	O
`browser.platform`	The platform	string	Y
`browser.architecture`	Architecture	string	Y
`browser.data_time`	Date	string($date-time)	Y
`browser.location`	Location	string	Y
`browser.customer_ip`	Customer IP	string	Y
`browser.port`	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
`qr_code`	QrCode generated	string	O	"qr_code":"iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABxUlEQVR4Xu2XQa6DMAxEjViw5Ai5CVysEkhcDG6SI7Bkgeo/4wD9rdTt9H+pWUQ0rwvLY48T83fLXg+u9SV/hIxm1nreep+y9euQ8buWksn93k7Zl7XGBuxxpiTZutZ962zwDWHlzdoPkNG2ar2liPIzZE+RmNBHT6jPmKxDZeDL87NyAhI1ipx05/ZcvQISa7fmbmiQah2OEyFBbEhMQkQ3ZMduqVmIhWTKDVsUToH/VCtFOp1CRPajN/oVv2d0bEmRkDh6Azv14WENz2iLPioy+eUUtoVSlatJs/iYGqTIG4dTYDuUExGnKoiN3blVKBNiKWFEKBMkps7NDJFoWFJyJmZu99IgqNYSm4o4HQo+0TMgTgxOcCnZUZmcWSwOfrFaBzGxqIs7Lw3l69BHRjgwcWmYi19buvRREfbpCn+AXyca5UMfHUFbhCp1mduXPjoSYbFP6RnoWHv4tYjAH+pIEQ0r+mWSkli8MyGs8Ay+KaRkNN7fwqFyWCYCHKQkKqTMbR7WfE6IyfmSYJT8eiinJMfEwMD8fXPQkuJQC8yTzq0l1AejkzcWtiiG99WnGhI1OuI9d1ygeakusanIm/Ul/5X8ALFA0R7Pm5CfAAAAAElFTkSuQmCC",
`deep_link`	Deep link for the Android/iOs systems	String	O	`"deep_link":"https://inpost.pl/izilink?binding_id=1ec6fdab-4098-485d-aaac-a7ac986f878f "`
`deep_link_hms`	Deep link for the HMS system – currently not used	String	O	`"deep_link_hms":"https://inpost.pl/izilink?binding_id=1ec6fdab-4098-485d-aaac-a7ac986f878f "`

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.

Developer Documentations

Binding a basket

Description of the method

Example implementation in PHP

Related pages