=== CatCode Appmax Payments for WooCommerce ===
Contributors: catcodestudio
Tags: appmax, pix, payments, woocommerce, brazil
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Appmax payments for WooCommerce: Pix with a QR code and a copy-and-paste code, the order confirmed by the Appmax webhook.

== Description ==

Connects WooCommerce to your Appmax account through the Appmax API, with the merchant credentials of your own store (Client ID and Client Secret from the API screen of the Appmax panel).

* **Pix for every order** — the buyer and the order are created at Appmax with the order total, and the buyer gets the QR code and the "Pix Copia e Cola" code on the order page, in "My account" and in the e-mail.
* **Countdown** — the order page shows how long the code can still be paid, from the expiry date Appmax returns. You can set your own validity in minutes or keep the one of your Appmax store.
* **Confirmed by Appmax** — the Appmax webhook tells the shop about the payment. The plugin never trusts the content of a webhook: it reads the order back from Appmax and only that answer marks the WooCommerce order as paid. A payment with another amount puts the order on hold with a note.
* **The page updates by itself** — the buyer sees "Payment received" without reloading, also when the webhook is late.
* **Expired, refused, refunded, chargeback** — the order follows the Appmax status: an expired Pix cancels the order and returns the stock, refunds and chargebacks are written in the order notes.
* **Appmax JS** — the script Appmax requires on the checkout to collect the buyer's IP is loaded on the checkout page.
* **CPF/CNPJ** — taken from a Brazilian checkout fields plugin when the checkout has one, otherwise asked in the payment box and checked before anything is sent.
* **Check connection** and **Check payment status** buttons, in plain words.
* Works with the classic and the block checkout and with HPOS. Offered in Brazilian reais only. Sandbox and production.
* Translations included: English and Brazilian Portuguese.

= Pro =

The Pro version is sold on [catcode.com.ua](https://catcode.com.ua/modules/catcode-appmax-payments-for-woocommerce/), with a 7-day trial that never starts by itself:

* **Credit card with instalments** — the card is turned into a token by Appmax JS in the buyer's browser, so the card number never reaches the shop. The instalment plans come from the interest set for your store at Appmax; the interest is added to the order as a fee, so the order total is what the card is charged.
* **Boleto** — PDF link and digitable line on the order page and in the e-mail; an unpaid boleto that Appmax cancels cancels the order.
* **Refunds from WooCommerce** — full or partial, for Pix and card (Appmax refunds a boleto only from its panel).
* **Subscriptions** — a product gets a period (days, weeks, months, years, and the number of charges); a paid order of such products becomes an Appmax subscription, and every new charge becomes a paid renewal order in the shop. Pause, resume and cancel from the order screen.
* **Hourly status check** — waiting orders are read back from Appmax, so a lost webhook does not leave an order on hold.
* **Sales recovery** — an order left unpaid is sent to the Appmax sales recovery with the link to pay it.
* **Request log** — the last 200 calls to Appmax with their answers.
* Updates from catcode.com.ua.

The licence runs for 1-5 years and includes updates and support for that term; a purchased licence keeps its Pro features after the term ends. One key covers two sites: the shop and its test copy.

Appmax is a trademark of its owner. This plugin is an independent integration made by CatCode; it is not an official plugin of Appmax and is not affiliated with or endorsed by it. You need your own Appmax merchant account.

== External services ==

The plugin connects to the Appmax API ([appmax.com.br](https://appmax.com.br/), documentation at [docs.appmax.com.br](https://docs.appmax.com.br/)) at `auth.appmax.com.br` and `api.appmax.com.br` (or `auth.sandboxappmax.com.br` and `api.sandboxappmax.com.br` with the sandbox), and only after you enter your credentials.

* For a token (checking the connection and before the other calls): the Client ID and the Client Secret.
* When the buyer pays: the buyer's name, e-mail, phone, IP address, CPF or CNPJ and billing address (POST /v1/customers); then the order total, the shipping amount and the names, SKUs and quantities of the products (POST /v1/orders); then the payment request.
* When a webhook arrives, the order page asks for the payment status or you press "Check payment status": the Appmax order number, to read it.

On the checkout the browser loads Appmax JS from `scripts.appmax.com.br` (or `scripts.sandboxappmax.com.br`). Appmax requires it: it collects the buyer's IP address, which Appmax needs for every payment.
With the card (Pro) the same script turns the card number, holder, expiry and security code into a token, sent from the browser straight to Appmax.

* Card (Pro): the token, the holder's name and CPF/CNPJ, the number of instalments, the text for the card statement; the order total and the number of instalments to get the instalment plans.
* Boleto (Pro): the payer's CPF or CNPJ.
* Refund (Pro): the Appmax order number and the amount.
* Subscriptions (Pro): the Appmax order number, the period and the number of charges; to pause, resume or cancel, the subscription number.
* Sales recovery (Pro): the buyer's name, e-mail, phone, IP address and the link to pay the order.

[Appmax API documentation](https://docs.appmax.com.br/)

== Installation ==

1. Upload the plugin and activate it. WooCommerce must be active and the shop currency the Brazilian real.
2. In the Appmax panel open **API** (under Applications), press "Generate credentials", choose or create the store and copy the Client ID and the Client Secret (the secret is shown once).
3. In WooCommerce → **Appmax** choose the environment, paste the credentials and save. "Check connection" tells whether Appmax accepted them.
4. In the Appmax panel open **API → Webhooks**, choose the store, paste the webhook address shown on the plugin screen and tick the order and payment events.
5. WooCommerce → Settings → Payments: enable "Pix (Appmax)" and place a test order. In the sandbox a Pix is approved by itself about 5 seconds after it is created.

== Frequently Asked Questions ==

= How does the shop know that the Pix was paid? =

Appmax calls the webhook address of your site. The plugin reads the order from Appmax and settles the WooCommerce order from that answer. While the buyer keeps the order page open the plugin also asks Appmax itself (at most every 30 seconds), so a late webhook does not hold the order.

= Is the webhook call signed? =

No, Appmax does not sign webhooks. That is why the address carries a long random part and why the content of a call is never used to mark an order as paid.

= The checkout says "Enter a valid CPF or CNPJ" =

Appmax needs the CPF or CNPJ of the payer. If your checkout has no such field, the payment box asks for it; the check digits are verified before anything is sent.

= Why is a phone number required? =

Appmax requires the buyer's phone with the area code (DDD) to create the buyer.

== Changelog ==

= 1.0.0 =
* First release: Pix through Appmax with QR code, copy-and-paste code and countdown, webhook confirmed by reading the order from Appmax, classic and block checkout.
* Pro: credit card with Appmax JS tokenization and instalments, boleto, refunds, subscriptions, hourly status check, sales recovery, request log, updates from catcode.com.ua.
