PrivatBank installments (Оплата частинами) Ukraine
Installments / instant installments (PayParts). Official documentation: https://pbdocs.gitbook.io/api-oc/. Gateway fee: PP — paid by the store, II — paid by the buyer; per the agreement with the bank.
Credentials
Account at payparts2.privatbank.ua/ipp/admin (OTP login, requires a PrivatBank account): storeId, password. Sandbox: /ipp/sandbox.
- Environment variables
PRIVATPARTS_STORE_IDPRIVATPARTS_PASSWORDPRIVATPARTS_PARTS=4PRIVATPARTS_TYPE=PP|II|PB|IA- Webhook
POST /webhooks/privatparts(JSON: storeId, orderId, paymentState, message, signature). Signature = base64(SHA1(password + storeId + orderId + paymentState + message + password)). The bank’s IPs can be allow-listed: 217.117.66.32–63, 217.117.68.32–63.
What Mistok calls
| Request | Fields / meaning |
|---|---|
POST /ipp/v2/payment/create (or /hold) | storeId, orderId, amount, partsCount, merchantType, products[{name, count, price}], responseUrl, redirectUrl, signature → {state, token}; payment page /ipp/v2/payment?token=… |
POST /ipp/v2/payment/state | paymentState |
POST /ipp/v2/payment/confirm · /cancel | confirm/cancel the hold (LOCKED) |
POST /ipp/v2/payment/decline | refund |
Statuses
CREATED → created · CLIENT_WAIT/OTP_WAITING/PP_CREATION → processing · LOCKED → hold · SUCCESS → success · FAIL/CANCELED → failure.
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
The bank’s sandbox page and the demo store /ipp/demo/products; the application decision takes 30–40 s.
Limitations
- amount 300–50 000 UAH
- partsCount 2–25
- UAH only
Not confirmed by a live run
Implemented from the official docs and SDKs; a first run on test keys is mandatory.
- partial refund rules and the state after a refund are not documented
- LOCKED timeout is not specified