WooCommerce
The IZI Pay - Pagamento Multicaixa plugin adds two payment methods to your WooCommerce checkout:
- Payment by Reference: the customer receives a Multicaixa entity and reference and pays later.
- Multicaixa Express: the customer approves a payment request on their phone.
Requirements
- WordPress 7.0 or later, WooCommerce 10.9 or later, and PHP 8.1 or later.
- Store currency set to Angolan kwanza (AOA). Orders must be between 0.01 and 10,000,000 AOA.
- HTTPS on your store for production.
- The details listed in What you need from IZI Pay.
The plugin works with both the classic and the block-based checkout, and with WooCommerce's high-performance order storage (HPOS).
Install
- Request the plugin ZIP file from IZI Pay support at suporte@izipay.ao.
- In WordPress, open Plugins → Add New Plugin → Upload Plugin, choose the ZIP file and click Install Now.
- Click Activate.
- Open WooCommerce → Settings → IZI Pay.
The settings page has three tabs: Connection, API Credentials and Payment Methods.
Set up
1. Enter your credentials
Open API Credentials. It has a Sandbox profile and a Production profile; fill in each one with the details IZI Pay gave you for that environment.
| Field | Needed for |
|---|---|
| Client ID, Client secret | Both payment methods |
| GPO merchant ID, GPO POS ID, GPO user email | Multicaixa Express |
| Refund supervisor ID | Automatic Multicaixa Express refunds only |
For Payment by Reference, your client ID must also be enabled for payment references. IZI Pay sets this up with your credentials.
2. Choose the environment and test it
Open Connection:
- Active environment: Sandbox (the default) or Production. New orders use this environment.
- Test active profile: checks that the credentials for the active environment work.
- Debug logging: writes payment and status-check events to the WooCommerce logs (WooCommerce → Status → Logs). Credentials, tokens and phone numbers are never logged.
3. Turn on the payment methods
Open Payment Methods:
- Payment by Reference → Enable
- Reference validity (days): how long the customer has to pay, from 1 to 30 days. The default is 3.
- Expiring-soon warning (hours): unpaid references that expire within this time are highlighted in your orders list. The default is 24.
- Multicaixa Express → Enable
A payment method only appears at checkout when it's enabled, its credentials for the active environment are complete, and the store currency is AOA.
4. Confirm reference payments instantly
Without this step, reference orders are still confirmed by automatic checks, just later. With it, an order is marked as paid as soon as the customer pays.
- In Connection, under Real-time PPR confirmation, copy the Callback URL. It looks like
https://your-store.com/wp-json/izipay/v2/ppr/callback. - Choose a secret value, enter it in Callback Access-Key, and save.
- In the IZI Pay Portal, open Definições → Integrações and add a webhook with that URL and the same Access-Key (Portal Guide).
The plugin rejects notifications with a wrong Access-Key, or whose amount or currency doesn't match the order.
What happens at checkout
Payment by Reference
- The customer chooses Payment by Reference and places the order.
- The order confirmation page and the order email show the entity, reference, amount and expiry date.
- The order stays On hold until the payment is confirmed.
- When the customer pays, the order moves to Processing (Order statuses). Without instant confirmation, the plugin checks about 1 minute after checkout, then every 5 minutes for the first half hour, then every 30 minutes.
- If the reference expires unpaid, the order is cancelled automatically.
If you cancel an unpaid order yourself, the plugin also cancels its reference so it can no longer be paid. If the customer paid just before, the order goes back to paid instead.
Multicaixa Express
- The customer chooses Multicaixa Express and places the order. The plugin uses the order's billing phone, which must be a nine-digit Angolan number. Spaces and the
+244prefix are removed automatically. - The customer approves the request on their phone within 60 seconds.
- The result arrives during checkout. If the payment succeeds, the order moves to Processing. If it fails, the customer sees the reason and can try again.
Order statuses
The plugin uses WooCommerce's standard order statuses:
| Order status | When |
|---|---|
| On hold | A reference was created and the customer hasn't paid yet. |
| Processing | The payment was confirmed, by reference or Multicaixa Express. Orders where every item is virtual and downloadable go straight to Completed instead. |
| Pending payment | Multicaixa Express was declined, not approved in time, or failed. The status doesn't change; the customer stays at checkout and can try again. |
| Failed | IZI Pay reported that the reference payment failed. |
| Cancelled | The reference expired unpaid, or the order was cancelled. |
| Refunded | The full amount was refunded. A partial refund doesn't change the status; it appears on the order. |
Processing means paid
An order in Processing has been paid and is waiting for you to deliver it. WooCommerce doesn't move it to Completed by itself: change the status to Completed once you've shipped or delivered the order.
Managing orders
- Orders list: extra columns for the IZI Pay Reference, Expiration date, Payment method and IZI Pay status. You can search by reference, filter by payment method and IZI Pay status, and sort by expiration date. References close to expiring are flagged.
- Order page: an IZI Pay payment details box with the reference, status and IDs. Under order actions:
- IZI Pay: Check payment status asks IZI Pay for the latest status of a reference order.
- IZI Pay: Retry reference cancellation appears when a reference couldn't be cancelled. Until it succeeds, the reference may still be payable.
- Reconciliation export: Export IZI Pay reconciliation downloads a CSV with one row per IZI Pay order matching your current filters, including gross, refunded and net amounts.
Refunds
- Multicaixa Express: use WooCommerce's refund button on the order for a full or partial refund. The money is returned through IZI Pay. This needs the Refund supervisor ID for the environment the order was created in, and the refund is recorded only after IZI Pay confirms it.
- Payment by Reference: these payments can't be refunded through IZI Pay.
Manual WooCommerce refunds are turned off for IZI Pay orders, because they would mark the order as refunded without returning any money.
Troubleshooting
| Problem | What to check |
|---|---|
| A payment method doesn't appear at checkout | It's enabled in Payment Methods, the credentials for the active environment are complete (Multicaixa Express also needs the three GPO fields), and the store currency is AOA. |
| "Enter a valid nine-digit Angolan billing phone number…" | The billing phone must be a nine-digit Angolan mobile number. |
| A reference order is still On hold after the customer paid | Use IZI Pay: Check payment status on the order, then check the instant-confirmation setup in step 4. |
| "Configure the refund supervisor ID for the … environment" | Add the Refund supervisor ID to that environment's profile and try the refund again. |
| Anything else | Turn on Debug logging and check WooCommerce → Status → Logs. |