README

Provides monobank Chast (hire purchase — «Покупка частинами») integration for Payum.

Unlike card gateways there is no redirect to a bank page: the store creates a purchase application, the customer confirms the credit agreement in the monobank app, and the store settles the application after handing the goods over.

Supported operations:

Capture — create an application (order/create, HMAC-SHA256-signed) and render a waiting page asking the customer to confirm the agreement in the monobank app.
DoCapture (the shared request from sol-parts/payum-contracts, when installed) — confirm goods handover (order/confirm) on a settled application. This is not a technical hold finalize: it states «the goods were handed over», charges the customer's first installment and sends the money to the store.
Cancel — reject a not-yet-confirmed application (order/reject).
Refund — product return (order/return) with the money sent back to the customer's card.
Notify — the callback payload is deliberately ignored: the state is always re-fetched from the bank API (order/state), so no webhook signature handling is needed and a forged callback can at most trigger an extra sync.
Sync / GetStatus — refresh the application state and map it to Payum statuses (see the table below).

Payment flow

sequenceDiagram
    autonumber
    actor C as Customer
    participant S as Store
    participant M as monobank

    C->>S: Chooses hire purchase at checkout
    S->>M: order/create (HMAC-SHA256 signed)
    M-->>S: order_id
    S-->>C: Waiting page - confirm in the monobank app
    C->>M: Confirms the credit agreement in the app
    M->>S: result_callback notification
    S->>M: order/state
    Note over S: WAITING_FOR_STORE_CONFIRM - authorized
    Note over S: Goods handed over to the customer
    S->>M: DoCapture - order/confirm
    M-->>S: ACTIVE - captured, money sent to the store

Status mapping

Application state	Payum status
`WAITING_FOR_CLIENT`	pending
`WAITING_FOR_STORE_CONFIRM`	authorized — the agreement is confirmed, the store may hand over the goods and must settle via `DoCapture`
`ACTIVE`, `DONE`	captured
`RETURNED`	refunded
`REJECTED_BY_CLIENT`, `REJECTED_BY_STORE`	canceled
`state=FAIL`	failed

Installation

composer require sol-parts/payum-monobank-chast

Usage with PayumBuilder

use Payum\Core\GatewayFactoryInterface;
use Payum\Core\PayumBuilder;
use SolParts\PayumMonobankChast\MonobankChastGatewayFactory;

$payum = (new PayumBuilder())
    ->addGatewayFactory('monobank_chast', static function (array $config, GatewayFactoryInterface $coreGatewayFactory) {
        return new MonobankChastGatewayFactory($config, $coreGatewayFactory);
    })
    ->addGateway('monobank_chast', [
        'factory' => 'monobank_chast',
        'storeID' => 'your-store-id',
        'signKey' => 'your-sign-key',
        'sandbox' => false,
    ])
    ->getPayum();

Usage with Symfony PayumBundle

# config/services.yaml
services:
    app.monobank_chast_gateway_factory:
        class: Payum\Core\Bridge\Symfony\Builder\GatewayFactoryBuilder
        arguments: [SolParts\PayumMonobankChast\MonobankChastGatewayFactory]
        tags:
            - { name: payum.gateway_factory_builder, factory: monobank_chast }

Configure a gateway:

# config/packages/payum.yaml
payum:
    gateways:
        monobank_chast:
            factory: monobank_chast
            storeID: '%env(MONOBANK_CHAST_STORE_ID)%'
            signKey: '%env(MONOBANK_CHAST_SIGN_KEY)%'
            sandbox: false

Options

Option	Required	Description
`storeID`	yes	Store identifier, sent as the `store-id` header on every API call.
`signKey`	yes	HMAC-SHA256 key: every request body is signed and sent in the `signature` header.
`sandbox`	no (default `true`)	`true` targets the bank's demo environment. The default is deliberately safe: an unconfigured gateway never creates real credit applications.

Payment details

ConvertPaymentAction fills store_order_id (the payment number), total_sum (major units — hryvnias with two decimals, unlike most card gateways) and an invoice block. The application supports 3 to 6 parts (Api::MIN_PARTS_COUNT / MAX_PARTS_COUNT); pass parts_count and the products list in the details before capture as described in the bank's docs.

The waiting page is rendered through the payum.template.obtain_token config option and can be replaced without touching the actions. The bundled template is in Ukrainian — the product exists only for customers of a Ukrainian bank — and its «back to the order» link points to the long-lived after-URL token rather than the one-time capture token, so the customer can leave the waiting page and come back more than once.

Caveats

DoCapture (order/confirm) is allowed only in WAITING_FOR_STORE_CONFIRM and has financial consequences for the customer; the action re-checks the live state right before confirming and is a no-op in any other state.
Refund (order/return) sends total_sum from the details — a full return of the application amount, with return_money_to_card=true.
The callback URL (result_callback) is attached to a Payum notify token; the callback body is never trusted — every notification triggers an order/state re-fetch instead.
Error responses are reported with the HTTP status code and a truncated body snippet; a FAIL state inside an HTTP 200 body is reported with the endpoint URL and state.

License

Released under the MIT License.

sol-parts / payum-monobank-chast

Maintainers

Package info

Statistics

Security