Home Credit

yui/craft-homecredit adds Home Credit consumer financing as an online payment method on a store running yui/craft-plugin. Home Credit is a consumer-lending provider active in Czechia and Slovakia; customers use it to pay for an order in installments instead of paying the full price up front.

Use it when you want to offer installment financing at checkout, and optionally show customers a live monthly-installment calculator on product or cart pages before they reach checkout.

What it does

• Registers HomeCreditGateway with yStore's payment gateway registry (PaymentService::EVENT_REGISTER_PAYMENT_GATEWAYS) so Home Credit appears as a selectable payment method at checkout, next to any other configured payment method.
• Builds a Home Credit financing application from the current order (customer, address, line items, total) and redirects the customer to Home Credit's hosted application flow to sign the financing contract.
• Reads back the application status when the customer returns to the store, and again whenever the order's status changes to delivered or ready_shipped, keeping Home Credit informed of shipment progress.
• Renders an optional installment calculator widget (hc.renderCalculator()) on site templates, backed by Home Credit's hc-calc web component.
• Adds a License page under the plugin's CP navigation, consistent with other YUI plugins.
• Ships Slovak and Hungarian translations of the settings labels and calculator error messages; unlisted languages fall back to English.

Where admins work with this plugin

In Craft CP, open Home Credit in the CP navigation (or Settings → Plugins → Home Credit):

• Settings (homecredit/settings) — provider credentials, checkout display, availability restrictions, and calculator configuration, split across General, Restrictions, Calculator, and Credentials tabs, plus an Enable / Sandbox Mode toggle pair in the sidebar. See Settings.
• License (homecredit/license) — activate, redeem, or revoke the plugin license, and copy the entitlement token. Same license flow used across YUI plugins.
• Payment transaction details — when viewing a payment transaction that was paid through Home Credit, the transaction detail view includes a Home Credit–specific panel showing the financing application's current status, fetched live from Home Credit's API.

There is no dedicated payments/transactions list in this plugin version — the financing application itself is managed on Home Credit's side; this plugin only reflects application status back into yStore's own order and payment transaction records.

How the checkout payment flow works

1. The customer selects Home Credit (or the configured Select button name) as their payment method at checkout.
2. yStore calls the gateway's placeOrder(), which loads the order and its items from the database, builds a Home Credit financing application request (customer name/email/phone/address, order number, line items with images, total price), and sends it to Home Credit via ApiService::prepare().
3. Home Credit responds with an application id and a gatewayRedirectUrl; the customer is redirected there to complete identity verification and sign the financing contract on Home Credit's hosted pages.
4. Home Credit redirects the customer back to the store's checkout callback URL. The gateway's postValidate() looks up the application by applicationId (stored on the payment transaction's extra data), fetches its current state/stateReason from Home Credit, and maps that to a yStore payment status (pending, processing, ready_to_ship, shipped, delivered, payment_review, or canceled) — see Developer → Application status mapping.
5. When the order's fulfillment status later changes to delivered or ready_shipped in yStore, the plugin automatically calls Home Credit's order/deliver or order/send endpoint so Home Credit's own records track the shipment, and logs a note on the order confirming Home Credit was notified.
6. Any Home Credit API error (missing order data, authentication failure, application rejected) is logged through the shared yStore error log (homecredit-gateway:placeOrder/postValidate/api-service:*) instead of surfacing raw Home Credit error payloads to the customer.

Installment calculator on site pages

Independently of the checkout gateway, the plugin exposes a Twig global hc (Yui\HomeCredit\services\HomeCreditService) on every site request. Call hc.renderCalculator() from a product or cart template to show a Home Credit "choose an installment method" button that opens the official Home Credit calculator widget:

{{ hc.renderCalculator(product.price, {
    form: 'add-to-cart-form',
    wrapper: 'installment-modal-root',
}) }}

• price is the item/order price in the site's major currency unit (the plugin converts it to minor units internally).
• The calculator only renders when Enable and Enable Calculator are both on in settings and the price is not below Minimal Price; otherwise the widget is replaced with an empty page fragment that only logs the reason (plugin/calculator disabled, or price below Minimal Price) to the browser console via console.error() — nothing is shown to the customer.
• The widget writes the customer's chosen installment plan into a hidden custom[_homecredit] field on the given form once they confirm it, so the selection survives to the order.

See Developer → Calculator widget for the full variable reference.

Requirements

• Craft CMS 5 project.
• yui/craft-core version 1, yui/craft-plugin (yStore) version 2+.
• A Home Credit merchant/partner account (separate credentials for the CZ and SK financing API, and separate sandbox test credentials) for Credentials.
• A Home Credit Calculator API key and Product Set Code, if you plan to enable the installment calculator widget (sandbox test keys are used automatically while Enable Sandbox Mode in the Calculator tab is on).
• Composer access to https://packages.yui.sk/.

Installation

composer config repositories.yui composer https://packages.yui.sk/
composer require yui/craft-homecredit
php craft plugin/install homecredit

Then open Home Credit → Settings → Credentials and enter the Home Credit partner Username and Password (see Settings).

Security notes

• Username/Password and Calculator API Key are stored as plain settings data — do not commit them to version control; set them through the CP settings form on each environment instead.
• Enable Sandbox Mode (financing API) and the Calculator tab's own Enable Sandbox Mode talk to Home Credit's test environment and never move real money or create a real financing contract; keep both on until a full test checkout has been verified.
• While the financing API's Enable Sandbox Mode is on, the plugin ignores the configured Username/Password and uses Home Credit's published sandbox test credentials instead — no real partner credentials are sent to the sandbox endpoint.

Developer / API reference

See Developer for the HomeCreditGateway and ApiService methods, the Home Credit application status mapping, the hc Twig global, and CP routes.

Frequently asked questions

Does this plugin support both Czech and Slovak Home Credit? Yes. The Language setting (cs-CZ or sk-SK) selects both the financing API base URL (apisk-test.homecredit.sk / apicz-test.homecredit.cz in sandbox, api.homecredit.sk / api.homecredit.cz in production) and the calculator's sandbox base URL/credentials.

Can I restrict Home Credit to specific countries or a date/time window? The Restrictions tab has Visible From / Visible To and Available in countries fields, the same pattern used by other YUI payment plugins. Verify their effect against the current yStore checkout payment method registry before relying on them in production, since not every YUI payment plugin's Restrictions tab is read by checkout in every version.

How do I test a payment before going live? Turn on Enable Sandbox Mode in the sidebar (financing API) and, if you use the calculator, the separate Enable Sandbox Mode on the Calculator tab. Complete a full checkout in sandbox mode and confirm the payment transaction's Home Credit panel shows an application status before switching either sandbox toggle off.

Where do I see the financing application status for an order? Open the order's payment transaction in Craft CP — the Home Credit panel on that view shows the application's live state/stateReason, fetched from Home Credit's API using the stored applicationId.

What happens if I mark an order as both sent and delivered? Only send one of Mark Order as Sent or Mark Order as Delivered per order. Home Credit's own status flow expects exactly one of ready_shipped / delivered, not both — see the status list in Developer.