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

Payum Monobank

Provides monobank acquiring (plata by mono) integration for Payum: hosted checkout with instant debit or two-stage hold payments, refunds and ECDSA-signed webhooks.

Supported operations:

• Capture — create an invoice (invoice/create) and redirect the customer to the monobank payment page (pageUrl).
• Authorize — same flow with paymentType=hold: the funds are locked for up to 9 days and the store settles the payment later.
• DoCapture (the shared request from sol-parts/payum-contracts, when installed) — settle a held payment via invoice/finalize, full or partial amount.
• Cancel — invalidate a not-yet-paid invoice (invoice/remove); payment by that invoice becomes impossible.
• Refund — refund of a paid invoice (invoice/cancel): the full paid amount by default, a partial one via the refundAmount detail, plus optional extRef and fiscal items.
• Notify — the webhook body is verified against the merchant public key (ECDSA-SHA256, X-Sign header) and bound to the transaction's invoiceId before the payload is applied.
• Sync — re-fetch the invoice state via invoice/status.
• GetStatus — maps monobank statuses to Payum ones, including hold (authorized), reversed (refunded) and expired.

Payment flow

Authorize creates a hold payment: the money is locked instead of charged, and monobank auto-reverses the hold after 9 days unless it is finalized:

A failed payment attempt (3-D Secure decline, timeout) does not kill the invoice: monobank allows retries by the same invoiceId, so the gateway keeps such a payment pending and sends the returning customer back to pageUrl until the invoice expires.

Installation

Usage with PayumBuilder

Usage with Symfony PayumBundle

Register the gateway factory:

Configure a gateway:

Options

Payment details

ConvertPaymentAction fills amount (minor units — kopecks), ccy (numeric ISO 4217) and merchantPaymInfo with reference (the payment number, always cast to string — monobank rejects a numeric one with INVALID_MERCHANT_PAYM_INFO) and destination.

The gateway itself defaults validity to 24 hours, attaches redirectUrl to the long-lived after-URL token and webHookUrl to a notify token, so both survive repeated visits.

A basketOrder supplied by the host application is validated the way monobank does — Σ(sum × qty) must equal amount, where sum is the price of a single unit. A basket whose lines carry the line total instead (Σ(sum) === amount) is transparently rebuilt into unit prices, splitting a non-divisible remainder across quantity rows; a basket matching neither formula is passed through untouched.

Caveats

• All amounts are in minor units (kopecks), including the partial amount of DoCapture and the refundAmount of Refund.
• A hold lives 9 days: without invoice/finalize monobank reverses it and returns the money. DoCapture on an already-reversed hold (errCode 1001) is not an error — the action re-syncs and the payment ends up reversed / refunded.
• failure is not terminal: the invoice stays payable until it expires, so GetStatus deliberately reports such a payment as unknown rather than failed, and the capture flow redirects the customer back to pageUrl for another attempt.
• Webhook delivery order is not guaranteed. Both the webhook and Sync apply a snapshot only if it is not older (modifiedDate) and does not roll a mature status (hold, success, reversed, expired) back to a pending one.
• The merchant public key is fetched from api/merchant/pubkey on every webhook, without persistent caching. When that fetch fails, the gateway answers 503 so monobank redelivers the webhook later; a webhook with an invalid X-Sign, or one about a different invoiceId than the transaction's, is answered 200 and ignored.
• Error responses are reported with the HTTP status code and a truncated body snippet — monobank answers with HTML, not JSON, on throttling (429) and balancer errors (5xx).

License

Released under the MIT License.