mono installments (Покупка частинами) Ukraine
Installments (push to the mono app). Official documentation: https://monobank.ua/api-docs/chast. Gateway fee: per the agreement with mono (paid by the store).
Credentials
“Покупка частинами” agreement → store_id and secret key. Sandbox: https://u2-demo-ext.mono.st4g3.com (demo store test_store_with_confirm).
- Environment variables
MONOPARTS_STORE_IDMONOPARTS_SECRET_KEYMONOPARTS_PARTS=3,4,6,9,12MONOPARTS_CONFIRM=immediate|on_fulfillment- Webhook
POST /webhooks/monoparts. Headersstore-id,signature= base64(HMAC-SHA256(body, secret)). The same formula on every Mistok request to mono.
What Mistok calls
| Request | Fields / meaning |
|---|---|
POST /api/order/create | store_order_id, client_phone (+380…, required), total_sum (UAH, 2 decimals), invoice{date, number, source: INTERNET}, available_programs[{available_parts_count, type: payment_installments}], products[{name, count, sum}], result_callback → {order_id} |
POST /api/order/state | state / order_sub_state — WAITING_FOR_STORE_CONFIRM is modelled as hold |
POST /api/order/confirm | store confirmation (money reaches the store only after it) — immediately or on fulfilment |
POST /api/order/return | refund: sum, store_return_id, return_money_to_card=true (partial allowed) |
POST /api/order/reject | rejecting an unconfirmed order (cancellation) |
POST /api/order/data | total_sum for amount reconciliation |
Statuses
IN_PROCESS/ADDED → created · WAITING_FOR_STORE_CONFIRM → hold → (confirm) → SUCCESS/ACTIVE → success · FAIL/* → failure, timeouts → expired · SUCCESS/RETURNED → reversed.
Mistok’s model: created → processing → (hold →) success | failure | expired | reversed. The Shopify order receives a payment only on success and only after the amount and currency are checked against our record.
Sandbox
Test phone numbers: ending in 1 = confirmation, 2 = waiting, 3 = declined on limit, 4 = waiting for store confirmation.
Limitations
- there is no payment page — the buyer confirms in the mono app within 15 min; Mistok shows a waiting page that polls the status
- UAH only
- buyer’s phone number is required
Not confirmed by a live run
Implemented from the official docs and SDKs; a first run on test keys is mandatory.
- the list of sub-states may grow — unknown ones are mapped by the top-level state
- in the sandbox order/data does not return total_sum (state only) — the payment amount is fixed by our signed create