Portmone for OpenCart — card, Apple Pay and Google Pay payments

CatCode Portmone is a Portmone.com payment module for OpenCart 2.3, 3.x and 4.x. The shopper pays by card, Apple Pay or Google Pay on the Portmone payment page, and the order in your store moves to a paid status on its own. The difference from the usual “redirect and take it on trust”: the module trusts neither the shopper’s return nor the notification — before marking an order paid it asks Portmone for the status itself and checks the amount.

What the shopper sees

At checkout it is an ordinary payment method, “Card, Apple Pay, Google Pay (Portmone)”. The shopper confirms the order and clicks “Pay” — the module creates an invoice in Portmone and opens the payment page.

After the payment Portmone sends the shopper back to the store. The module ignores whatever arrives in the URL or the POST body and asks Portmone for the status using the shop login and password. If the payment went through, the shopper lands on the order confirmation page; if not, the order gets the failed-payment status, the products go back into the cart and a prompt to try again appears on top.

A repeat attempt goes to Portmone under a new number, and the module closes the previous invoice with closeInvoice so that a single order cannot be paid twice. If the shopper has already paid and presses “Back”, they land on the success page instead of a second payment.

The method is shown only for the currencies Portmone accepts: UAH, USD, EUR, GBP, PLN and KZT. If the shopper switches the store to another currency, Portmone hides itself.

What the admin gets

• “Test connection” sends a status request with your credentials and, when a signature key is set, also creates a 1 UAH test invoice and closes it right away. A wrong password or key shows up in the admin, not in a call from a customer.
• Six order statuses on a separate tab: awaiting payment, paid, funds held, hold released, failed payment and refunded.
• Order history with the Portmone invoice number, the masked card, the authorisation code and the result of every status check. An underpayment is visible immediately and such an order never becomes paid.
• Payment window — how many minutes the payment link stays valid — and a geo zone, if you need Portmone only in some countries.
• Payment journal (Pro) — every payment in one list: order total, paid, refunded, the Portmone state next to the order status, the invoice number and the card, plus the “Sync” and “Refund” buttons.

How it works, step by step

1. The shopper picks Portmone at checkout and confirms the order. The module creates an invoice in Portmone with a unique attempt number, the order amount and currency. If Portmone issued you a signature key, the request is signed with HMAC-SHA256. The order gets the “awaiting payment” status.
2. The shopper pays on the Portmone page — by card, Apple Pay, Google Pay or any other method enabled for your store.
3. The shopper returns to the store (Portmone does this with a cross-domain POST). The module asks Portmone for the status with a result request and decides what happened to the money from that answer only.
4. Amount and ownership checks: the number must have been issued for this very order, the Payee ID must be yours, and the amount must not be lower than the order total. If less was paid, the order stays under review with a note for the manager.
5. The order moves to the status you chose, and the invoice number, masked card and authorisation code go into its history.
6. If the shopper closed the tab and never came back, the Portmone notification to the address from the settings does the job — JSON or XML. The module does not take the notification on trust either: the status is requested through the API again, and a repeated notification does not duplicate the history entry.
7. A repeat attempt closes the previous invoice, so two payments for one order cannot go through.
8. In two-stage mode (Pro) the funds are only held on the card. You capture them from the journal when the order is ready to ship, or release the hold. Card schemes keep such holds for up to 7 days.

Under the hood

• The status comes from the Portmone API only. The shopper’s return, the notification and the “Sync” button all lead to one place: a result request with the shop login and password. A forged request to your site changes nothing.
• Unique attempt numbers: the order number plus a counter and a random suffix. A declined old attempt will not touch an order that is already paid, and an old attempt that was paid is still counted even if the shopper opened a new one.
• The shopper’s session survives: Portmone returns the buyer with a cross-domain POST, and OpenCart used to open a new session on such a request, losing the cart and the login. On that return the module does not let the session cookie be overwritten.
• OpenCart 4.1: if the core voided an order that was not placed yet while the shopper reloaded the checkout, the module rebuilds it from the current cart instead of refusing the payment.
• Module texts are not overwritten by the language files of other extensions loaded by order-status events.
• The password and the signature key are encrypted in the database (AES-256-CBC with an integrity check), and the password is masked in the request log.
• Its own extension code cc_portmone: the official Portmone module can sit next to it — the settings and tables are separate.
• The OpenCart core is not patched: in 4.x the module installs as a regular extension, and in 3.x and 2.3 it needs no ocmod edits of the core. The payment table survives uninstallation so that refunds and holds are not lost.
• A Pro gate that does not brick anything: when the trial ends only the Pro features stop, while already held funds can still be captured or released.

Installation

1. OpenCart 4.x: Extensions → Installer → upload cc_portmone.ocmod.zip and click Install. Then Extensions → Payments → “Portmone — card, Apple Pay, Google Pay” → Install → Edit.
2. OpenCart 3.x: Extensions → Installer → upload cc_portmone-oc3.ocmod.zip, refresh the modifications, then Extensions → Payments → Portmone → Install.
3. OpenCart 2.3: the stock 2.3 installer copies files over FTP only, so it is easier to unpack the contents of the upload/ folder from cc_portmone-oc2.ocmod.zip into the store root. Then Extensions → Payments → Portmone → Install.
4. Fill in the Payee ID, shop login and password (and the signature key, if Portmone issued one), click “Test connection” and save.
5. Send your Portmone manager the notification URL — it is shown in the module settings.
6. For Pro: paste the licence key from the e-mail you get after the payment, or start the 7-day trial.