Download the PHP package sol-parts/payum-hutko without Composer

Payum Hutko

Provides Hutko acquiring integration for Payum: hosted checkout with instant debit or two-stage preauth hold payments, and refunds. Hutko speaks the Fondy-compatible protocol 1.0 (JSON, SHA1 merchant signature).

Supported operations:

• Capture — create a payment (/api/checkout/url/) and redirect the customer to the Hutko payment page (checkout_url).
• Authorize — same flow with preauth=Y: the funds are locked on the customer's card and the store settles the payment later.
• DoCapture (the shared request from sol-parts/payum-contracts, when installed) — settle a preauth hold via /api/capture/order_id/, full or partial amount.
• Cancel — reversal of an active preauth hold via /api/reverse/order_id/. For anything else it is a no-op: a captured payment is returned by Refund, and a not-yet-paid order simply expires on its own.
• Refund — refund of a paid order via /api/reverse/order_id/, full transaction amount.
• Notify — the postback (server_callback_url) is treated as a sync trigger only: the state is always re-fetched server-to-server, so a forged callback can at most trigger an extra sync. Hutko considers a postback delivered only on HTTP 200 and retries otherwise — the action always answers 200.
• Sync — re-fetch the order state via /api/status/order_id/.
• GetStatus — maps Hutko order statuses to Payum ones (see the table below).

Payment flow

Authorize creates a preauth payment: the money is locked instead of charged until the store settles or releases it:

While an order is still payable (created / processing) the capture flow does not create a new payment: the returning customer is redirected back to the same Hutko payment page (checkout_url) until the order is paid or expires.

Status mapping

Hutko has no separate order status for a settled hold — both a successful preauth and its capture report approved. The gateway keeps the stage in the payment details (preauth, captured) and resolves the ambiguity locally.

Installation

Usage with PayumBuilder

Usage with Symfony PayumBundle

Register the gateway factory:

Configure a gateway:

Options

There is no sandbox option: Hutko serves live and test traffic on the same endpoint, and testing is done under the dedicated test merchant (1700002 / password test in the official documentation).

Payment details

ConvertPaymentAction fills amount — in minor units (kopecks), as the Fondy protocol expects — along with currency, order_desc and order_id taken from the payment.

The gateway attaches response_url to the long-lived after-URL token and server_callback_url to a notify token, so both survive repeated visits.

Caveats

• All amounts are in minor units (kopecks), including the partial amount of DoCapture and the reverse calls.
• approved is ambiguous: Hutko reports it both for a successful preauth hold and for its settlement. The gateway tracks the stage with the preauth and captured payment details — do not strip them when manipulating the details externally.
• /api/reverse/order_id/ is a single endpoint for both reversal of a hold and refund of a captured payment. The gateway always reverses the full transaction amount; partial refunds are not implemented.
• The postback body is deliberately not parsed and its signature is not verified: the state is always re-fetched via /api/status/order_id/ under the merchant credentials. Answer anything but HTTP 200 and Hutko keeps redelivering the postback.
• A checkout/url call answered with HTTP 200 but a non-success response_status is reported as an exception carrying the gateway error code and message together with the endpoint URL.
• Error responses are reported with the HTTP status code and a truncated body snippet — balancer errors (429, 5xx) answer with HTML, not JSON.

License

Released under the MIT License.