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.

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”.

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-1.0.1.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-1.0.1.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.