iPay.ua for OpenCart — card, Apple Pay and Google Pay payments

CatCode iPay is a payment module for iPay.ua for OpenCart 2.3, 3.x and 4.x. The customer pays by card, Apple Pay or Google Pay on the secure iPay page, and the order in your store moves to “Paid” by itself. The module takes the status not from what a notification claims, but from the iPay API’s answer to your own keys, so nobody can fake a payment with a request to your site.

The base version is free with no limit on the number of payments: accepting payments, notifications, amount check, sandbox. Pro adds a payment log, refunds from the admin panel, capturing and cancelling pre-authorisations, and a payment link for orders taken over the phone.

Live demo

The module is installed on our demo stores for OpenCart 4.x, OpenCart 3.x and OpenCart 2.3. The payment method is disabled there: a payment through iPay can’t go through without a contract with iPay, and we don’t want to show shoppers someone else’s payment page. The screenshots below were taken during an end-to-end test on these stores: cart, payment, return to the store, order history, payment log and refund.

The easiest way to see it all live is to install the free version in your own store and enter iPay test credentials: requests go to the sandbox-checkout.ipay.ua sandbox and no money moves. The iPay test card 3333 3333 3333 3331 always succeeds, 3333 3333 3333 3349 is declined, and 3333 3333 3333 3356 gives a pre-authorisation.

What the customer sees

At checkout it’s a regular payment method, “Card, Apple Pay, Google Pay (iPay.ua)”. The customer confirms the order, the module creates a payment in iPay and takes them to the payment page showing the amount in hryvnias and your store name. The page opens in the store language: Ukrainian, Russian or English.

After paying, iPay returns the customer to the store. If the payment went through, they land on the “Order placed” page. If not, the items stay in the cart with a hint on top to try again or choose another method. The cart neither disappears nor gets duplicated.

The method is shown only for carts in hryvnias. If the customer switches the store currency to dollars or euros, the payment method hides: iPay would charge the same figure in hryvnias.

What the admin gets

• One-click key check. The module makes a service request to iPay and tells you whether the merchant ID and signing key are accepted. No payment is created.
• Separate order statuses for “awaiting payment”, “paid”, “funds blocked”, “payment failed” and “refund”.
• Order history with the iPay payment number and the masked card. Underpayment is visible at once: “paid 3969.85 UAH instead of 3979.85 UAH — needs checking”, and such an order doesn’t move to paid.
• Payment log (Pro): all iPay payments in one list, with the iPay status next to the order status. The “Reconcile”, “Refund”, “Capture” and “Release hold” buttons are right there.

How it works, step by step

1. The customer confirms an order paid with iPay. The module creates a payment with a PaymentCreate request: amount in kopecks, the description “Payment for order No. …”, return addresses, page language. The order gets the “awaiting payment” status.
2. The customer pays on the iPay page by card, Apple Pay or Google Pay.
3. iPay sends a notification to your site. The module finds its order by the payment number and asks iPay for the real status with a Status request, using its own keys.
4. The module compares the paid amount with the order total. If everything matches, the order becomes “Paid”, and the payment number and card are written to the history.
5. The customer returns to the store. The module asks for the status once more: if the notification didn’t arrive, the order is closed here. A repeated notification doesn’t become a duplicate in the history.
6. If iPay has enabled pre-authorisation for you, the funds are first only blocked. In Pro they are captured automatically as soon as a manager moves the order to a paid status. Or manually from the log: “Capture” or “Release hold”.

Pricing

The free version costs 0 UAH, forever and with no turnover limits. Pro is 990 UAH, a one-off payment. The OpenCart license is perpetual, with no yearly fees. One key works with the 2.3, 3.x and 4.x builds; it has two activations, i.e. the live store and a test copy.

Before buying, you can switch Pro on for 7 days right from the module settings: enter your email and get a key for this site. No card required, nothing renews by itself. After the trial Pro switches off, and the free version keeps working.

Requirements

• OpenCart 2.3.0.x, 3.0.x or 4.0.2 – 4.1.x; PHP 7.0+ for 2.3, and for 3.x and 4.x whatever version your OpenCart requires.
• PHP cURL and SimpleXML extensions, outbound HTTPS requests from the server.
• A contract with iPay.ua: merchant ID (mch_id) and signing key (sign_key). iPay issues sandbox test credentials together with the contract.
• Cart currency — Ukrainian hryvnia (UAH).
• iPay configures the notification address on its side: the module shows a ready URL that you send to iPay support once. The address must be reachable from outside, without basic-auth.

Under the hood

iPay signs requests and notifications like this: a salt plus an HMAC-SHA512 of the salt with the merchant key. That signature doesn’t cover the message body. So the module takes nobody at their word: the notification signature is checked, but the order is changed only by the answer to a Status request that the module itself sends to iPay with your keys. A forged or intercepted notification can at most make the module check the status one more time.

Then come the safeguards we usually find missing in other payment modules. A late notification won’t roll a paid order back. Pressing “Back” after paying won’t create a second payment. An order that has already moved past status 0 won’t go to the bank with the old amount. Underpayment won’t become a payment. A full refund on the payment day goes as a reversal, later as a refund. Partial refunds are counted cumulatively, and you can’t go over the remaining balance.

The signing key is stored encrypted in the database. The OpenCart core isn’t patched: in 4.x and 3.x everything works through standard events, and in 2.3 also without ocmod edits. The payment table and settings stay when the module is uninstalled, so you won’t lose the history.

How to install

1. OpenCart 4.x: Extensions → Installer → upload cc_ipay.ocmod.zip and click “Install”. Then Extensions → Payments → “iPay.ua — оплата карткою (CatCode)” → “Install” → “Edit”.
2. OpenCart 3.x: Extensions → Installer → upload cc-ipay-oc3.ocmod.zip, then Extensions → Payments → iPay → “Install”.
3. OpenCart 2.3: the stock 2.3 installer requires FTP, so it’s easier to unpack the contents of the upload/ folder from cc-ipay-oc2.ocmod.zip into the store root. Then Extensions → Payments → iPay → “Install”.
4. Enter the merchant ID and signing key, click “Check keys”, save and send the notification URL to iPay support.
5. To start, enable the “Sandbox” and make a test payment with the card 3333 3333 3333 3331.

Version history

1.0.0 — first release for OpenCart 2.3, 3.x and 4.x. Payments through the iPay.ua Checkout API: card, Apple Pay, Google Pay. Notifications with reconciliation through the Status API, protection against underpayment and repeated notifications, sandbox and key check. In Pro — payment log, refunds (reversal/refund, full and partial), capturing and cancelling pre-authorisation, automatic capture when an order is confirmed, a payment link for an order from the admin panel.