Payroc Payments for OpenCart — card payments on the Payroc payment page

Payroc Payments for OpenCart 4.x, 3.x and 2.3 takes card payments through the Payroc Hosted Payment Page. The buyer picks “Pay by card” at checkout, types the card on the Payroc page and comes back to the shop; the order is paid only when the signature of the answer matches and the amount, currency and order number agree with the cart. USD and CAD terminals are supported.

What you need from Payroc. A Payroc merchant account with a USD or CAD terminal. The terminal ID and the terminal secret come from the Self-Care Portal, the API key from the Payroc Developer Portal. The terms, limits and fees are set by Payroc in your agreement.

What the buyer sees

At the checkout the buyer chooses “Pay by card” and presses the button. The shop opens the Payroc payment page, where the buyer types the card: the card data never reaches your shop. After paying, Payroc sends the buyer back and the “order placed” page appears. If the bank declines, the buyer sees the reason and returns to the checkout with the same cart to try another card. If the buyer closes the tab before coming back, the order is still confirmed: Payroc tells the shop in the background.

What the admin gets

Extensions → Extensions → Payments → Payroc Payments (CatCode): the tabs “Connection”, “Checkout”, “Order statuses” and “Pro”. On “Connection” choose the test or live environment and enter the terminal ID, the terminal secret, the API key and the terminal currency (USD or CAD). The secret and the API key are stored encrypted and never shown again. “Check connection” asks Payroc whether it knows the terminal and whether it is active. The module also shows the two addresses for the Payroc Self-Care Portal: the Receipt Page URL, where Payroc brings the buyer back, and the Validation URL, where Payroc posts a confirmation in the background. A click on an address copies it.

The “Checkout” tab sets the title and the description of the method for every language, the minimum order total, the geo zone and the sort order; “Order statuses” sets the statuses for a paid, a declined and a refunded order. An order stays without a status until the payment is confirmed, so empty attempts do not clutter the order list. Every payment attempt gets a new order number at Payroc, so a second try after a decline is never confused with the first.

The answer from Payroc is accepted only after its signature is checked with the terminal secret. An approved payment sets the paid status; if the amount, the currency or the cart changed, or only part of the amount was approved, the order gets the “review” status with a note. Repeated and late answers change nothing, and a second approval for the same order leaves a note about the double payment. The order tab shows the payment, the masked card, the Payroc payment ID and the attempts; refunds, full or partial, with a reason, and the “Check payment status” button are there too.

Pro: authorize now, capture later. The amount is held on the card through the Payroc pre-authorization page, the order gets the “held” status, and the “Capture” and “Release” buttons in the order take the money or free the hold (partly, through the amount field). The hourly check captures held payments of orders that reached the status you chose and releases the hold of cancelled ones.

Payment links (Pro) for any unpaid order, for example one taken by phone: single-use, with a preset amount and a validity of 1 to 60 days; Payroc e-mails it to the buyer with your message, and a paid or cancelled order switches the link off by itself. The hourly background check picks up payments Payroc has not answered for. The payments journal and report show the terminal’s payments for a period and match them to shop orders (matches, amount differs, approved but unpaid, no shop order) with a CSV export. The request journal of Payroc calls is kept for 30 days. Up to three extra terminals for other currencies, each with its own secret.

How it works, step by step

1. Install the archive for your OpenCart version and enable the module.
2. In the Payroc Self-Care Portal take the terminal ID and the terminal secret, and create an API key in the Developer Portal.
3. Enter them in the module settings, choose the terminal currency and press “Check connection”.
4. Copy the Receipt Page URL and the Validation URL from the settings into the Payroc portal (terminal → Settings) and enable Validation.
5. The buyer chooses “Pay by card”, types the card on the Payroc page and returns to the shop.
6. The module checks the signature and the amount and moves the order to paid; refunds are made from the order tab.

Under the hood

• Payroc Hosted Payment Page: the request is signed with SHA-512, the answer is accepted by its signature, amount, currency and the order number the shop issued.
• The return page does not depend on the buyer’s session: in OpenCart 4 it is a static page that moves the buyer to the shop’s own result page, so the cart and the login are kept.
• The background confirmation from Payroc (Validation URL) is handled together with the buyer’s return: the order is booked once even when both answers arrive at the same time.
• Refunds carry an idempotency key; Payroc errors (RFC 7807) are shown in words.
• The terminal secret and the API key are stored encrypted; the module does not change the core, works through OpenCart events and keeps its settings on update.
• Not included: saved cards, embedded Hosted Fields (payment happens on the Payroc page), bulk actions on the order list; OpenCart 4.0.0–4.0.1 is not supported.
• Interface in English (en-gb).

How to install

1. Extensions → Installer: upload the archive for your version without renaming it (OpenCart 4: cc_payroc.ocmod.zip, 3.x: cc_payroc-oc3.ocmod.zip, 2.3: cc_payroc-oc2.ocmod.zip).
2. For 3.x and 2.3: Extensions → Modifications → Refresh.
3. Extensions → Payments → Payroc Payments (CatCode): install it and open the settings.
4. Enter the terminal ID, the secret and the API key, choose the currency and press “Check connection”.
5. Add the Receipt Page URL and the Validation URL in the Payroc Self-Care Portal.
6. For Pro: paste a key or start the trial on the Pro tab.