Developer / API

Gateway API

Yui\HomeCredit\gateways\HomeCreditGateway extends yStore's yui\craft\base\BasePaymentGateway and is registered on PaymentService::EVENT_REGISTER_PAYMENT_GATEWAYS. The methods below are the contract yStore's checkout calls into; they are not normally called directly from custom code, but are useful when debugging a checkout integration.

use Yui\HomeCredit\gateways\HomeCreditGateway;

$gateway = new HomeCreditGateway();
$details = $gateway->getDetails();

Method	Purpose
getHandle(): string	Returns Plugin::PLUGIN_HANDLE (homecredit).
getDetails(): array	Returns the payment method descriptor yStore uses to list Home Credit at checkout: name, code/handle (homecredit), type (online), instructions, price, enabled, plus url, logo, and description for the CP/checkout UI. Returns [] and logs on error.
placeOrder(array $data, array $items, ?string $code = null): array	Builds and sends the Home Credit financing application for an order. Returns ['redirectUrl' => ..., 'extra' => [...]] on success (see below), or [] if the order data/items are invalid or Home Credit returned an error.
postValidate(array $params): array	Called on the checkout return/callback with $params['order_number'] (the order's increment ID). Looks up the payment transaction, reads the stored applicationId, fetches the application's current details from Home Credit, and returns ['success' => bool, 'paid' => float, 'status' => string].

placeOrder() success payload

[
    'redirectUrl' => $api->prepare($data, $items)->getRedirectUri(), // Home Credit's gatewayRedirectUrl
    'extra' => $api->getParams(), // paymentData sent to Home Credit, plus 'applicationId'
];

redirectUrl is what the storefront sends the customer's browser to — Home Credit's hosted application flow. extra['applicationId'] is what postValidate() and the payment-transaction detail panel later use to look up the application on Home Credit's side.

Application status mapping

postValidate() maps Home Credit's stateReason (uppercased) to a yStore payment status via HomeCreditGateway's status constants:

HomeCreditGateway constant	Home Credit stateReason	yStore status	Marks paid?
HOME_CREDIT_PROCESSING_REDIRECT_NEEDED	PROCESSING_REDIRECT_NEEDED	not mapped (falls back to pending)	no
HOME_CREDIT_PROCESSING_PREAPPROVED	PROCESSING_PREAPPROVED	processing	no
HOME_CREDIT_PROCESSING_APPROVED	PROCESSING_APPROVED	processing	no
HOME_CREDIT_PROCESSING_REVIEW	PROCESSING_REVIEW	processing	no
HOME_CREDIT_PROCESSING_ALT_OFFER	PROCESSING_ALT_OFFER	not mapped (falls back to pending)	no
HOME_CREDIT_PROCESSING_SIGNED	PROCESSING_ALT_SIGNED	processing	no
HOME_CREDIT_READY_TO_SHIP	READY_TO_SHIP	ready_to_ship	yes
HOME_CREDIT_READY_SHIPPED	READY_SHIPPED	shipped	yes
HOME_CREDIT_READY_DELIVERED	READY_DELIVERED	delivered	yes
HOME_CREDIT_REJECTED	REJECTED	canceled	no
HOME_CREDIT_READY_PAID	READY_PAID	payment_review	yes
HOME_CREDIT_CANCELLED_NOT_PAID	CANCELLED_NOT_PAID	canceled	no
HOME_CREDIT_CANCELLED_RETURNED	CANCELLED_RETURNED	canceled	no
(any other value)	—	pending	no

success in the postValidate() return array is true whenever Home Credit returned application details at all (i.e. the application exists and is reachable), regardless of which status it's in — it does not mean the order is paid. Check status/paid for the actual financing outcome. paid is only set to the transaction's total_due when status is one of payment_review, delivered, shipped, or ready_to_ship.

Per Home Credit's own status list, the e-shop must send either order/send (ready_shipped) or order/deliver (delivered) for a given order, never both.

ApiService

Yui\HomeCredit\services\ApiService (Plugin::$plugin->getHomeCreditApi(), component id home-credit-api) wraps Home Credit's financing REST API over raw cURL. Its base URL is chosen at construction from Sandbox Mode and Language:

Sandbox	Language	Base URL
on	cs-CZ	https://apicz-test.homecredit.cz/verdun-train
on	sk-SK	https://apisk-test.homecredit.sk/verdun-train
off	cs-CZ	https://api.homecredit.cz
off	sk-SK	https://api.homecredit.sk

Method	Purpose
prepare(array $data, array $items): self	Builds the financing application request from raw order $data and $items, obtains a token if needed, POSTs to /financing/v1/applications, and stores the decoded response on $this->api. Chainable. Throws if $data or $items is empty.
getToken(): ?string	POSTs to /authentication/v1/partner/ with Username/Password (or Home Credit's sandbox test credentials while Sandbox Mode is on) and stores the returned accessToken. Throws if no token is obtained.
getRedirectUri(): ?string	Returns $this->api['gatewayRedirectUrl'] from the last prepare() call, or null.
getParams(): array	Returns the paymentData sent to Home Credit, with applicationId ($this->api['id']) merged in. Throws if the API wasn't initialized or has no id.
getApplicationDetails(?string $applicationId): array	GETs /financing/v1/applications/{applicationId} and returns ['state', 'stateReason', 'type', 'gatewayRedirectUrl'], or [] on error. Used by both postValidate() and the payment-transaction detail panel.
changeStatus(int $orderId, string $orderStatus): void	Called from the CP order-status-change event (see Extensibility). For $orderStatus of ready_shipped or delivered, PUTs /financing/v1/applications/{applicationId}/order/send or /order/deliver, logs the response, and saves an order comment confirming Home Credit was notified. No-op for other statuses.

Requests to /financing/v1/applications (creating an application) build their payload differently depending on Sandbox Mode:

• Sandbox on (DataHelper::getSandboxRequestData()): a fixed test customer (John Trener, Brno address) and, if the order has no line items loaded yet, up to 10 randomly generated fake items — useful for exercising the flow without real order/customer data.
• Sandbox off: the real customer name/email, billing address, and order line items (via DataHelper::getOrderedItems(), which reads each item's product image for the request payload).

hc Twig global

Yui\HomeCredit\twigextensions\hcTwigExtension registers hc as a Twig global on site (non-CP, non-console) requests, pointing at the plugin's HomeCreditService component (Plugin::$plugin->getHomeCredit()).

Calculator widget

{{ hc.renderCalculator(price, variables) }}

Parameter	Type	Purpose
price	float	The item/order price in the site's major currency unit. Multiplied by 100 internally before being compared against Minimal Price and sent to the widget.
variables	array	Optional overrides merged into the widget's configuration — see below.

Supported variables keys (all optional):

Key	Purpose
form	ID of a <form> element. When the customer confirms an installment plan, the widget writes the result to a hidden custom[_homecredit] input on this form.
wrapper	ID of an element to mount the calculator into when Open in modal window is off. A leading # is stripped automatically if present.
extraFeePriceInputIdentifier	ID of a numeric <input> whose value (× 100) is added to price before it's sent to the widget — for example, an extended-warranty fee selector.

renderCalculator() returns one of two Twig templates depending on eligibility:

• homecredit/frontend/calculator-widget.twig — mounts the <hc-calc> custom element (Home Credit's calculator web component, CalculatorAsset/hc-calculator.min.js) with apiKey, productSetCode, dataCalculatorBaseUrl, price, downPayment, fixDownPayment, language, isModal, hideHeader, buttonText, and debug set from settings (sandbox values substituted when the Calculator tab's Enable Sandbox Mode is on).
• homecredit/frontend/calculator-error.twig — rendered instead when the plugin/calculator is disabled, or when price is below Minimal Price. It produces no visible output: the translated reason (The HomeCredit plugin or Calculator is not enabled. or Price Error. Your price ({price}) is lower than the minimal price ({minimal_price}).) is only passed to a <script>console.error('...')</script> tag, so it surfaces in the browser console, not on the page.

Control panel routes

Registered on UrlManager::EVENT_REGISTER_CP_URL_RULES, all under homecredit/*:

• homecredit/settings — settings page (SettingsController::actionIndex).
• homecredit/settings/test-token — calls ApiService::getToken() and redirects back with a success/error flash (SettingsController::actionTestToken).
• homecredit/license, homecredit/license/redeem, homecredit/license/revoke, homecredit/license/activate, homecredit/license/delete, homecredit/license/copy-token — license management, shared AbstractLicenseController flow used by other YUI plugins.

There are no anonymous/site-facing routes registered by this plugin directly — the checkout redirect to Home Credit and the return callback are driven through yStore's own checkout controllers calling HomeCreditGateway::placeOrder() / postValidate(), not through Home Credit–specific URLs.

Extensibility

• Order status change → Home Credit notification. The plugin listens for yui\craft\services\OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE (CP requests only) and, when $event->statusTo is delivered or ready_shipped, calls Plugin::$plugin->getHomeCreditApi()->changeStatus() for that order. This is the plugin's only registered Craft event outside the payment gateway registration.
• Payment transaction detail hook. The plugin hooks payment-transaction-specific-details (CP requests) to render a Home Credit application-status panel (homecredit/components/payment-transaction/details.twig) whenever a payment transaction has an applicationId in its extra data.
• To react to a Home Credit application outside the standard checkout flow (for example, a reconciliation job that re-checks pending applications), call Plugin::$plugin->getHomeCreditApi()->getApplicationDetails($applicationId) directly and branch on the status mapping above.
• This plugin version does not register its own permissions, GraphQL types, or MCP tools.