=== ROKI Connect for Give ===
Contributors: rokiconnect
Tags: donations, payments, credit card, honduras, fundraising
Requires at least: 6.2
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

Accept card donations in lempiras on your GiveWP forms through ROKI Connect, the Honduran payment gateway.

== Description ==

ROKI Connect lets churches, NGOs, fundraisers and schools in Honduras take credit and debit card donations in lempiras (HNL) on their GiveWP forms, instead of asking donors for a bank transfer and a screenshot.

**How it charges**

The donor leaves for a secure ROKI checkout page, pays, and comes back to your site. Card details are typed on ROKI's page: they never pass through your server and this plugin never sees or stores them. Card fields inside the donation form itself are planned, not available yet.

It behaves the same in the GiveWP visual form builder and in the previous generation of forms, which is what many organizations already have built.

**What it does for you**

* **The donation is completed by a signed notification, not by the browser.** Coming back from the checkout means the browser came back, not that the money moved. The donation is marked complete when ROKI says so over a signed webhook.
* **Refunds from the WordPress admin.** The plugin voids the transaction first whenever it still can, because a void never shows up on the donor's card statement, and refunds it once it has settled. Requires GiveWP 4.6 or later, which is where GiveWP added gateway refunds.
* **Notifications that are actually verified.** The signature is checked with HMAC-SHA256 over the raw request body and compared in constant time, and repeated deliveries are discarded by their event identifier.
* **Each notification is matched to its own site.** Two WordPress sites on the same ROKI merchant account each receive the other's notifications, correctly signed with the same secret. Every donation carries its own key, so a payment made on another site cannot complete a donation on this one.
* **A lempira guard.** ROKI charges in HNL. If the form is set to another currency the plugin stops before charging: sending the bare number would turn a 100 dollar donation into a 100 lempira charge.
* **Optional donor-covered fee.** A switch that asks ROKI to recalculate the total so the organization receives the full donated amount.
* **Payment links that expire.** You choose how many hours the checkout link stays valid.

**What this plugin does not do, said plainly**

* It does not mark a donation as received because the donor returned from the checkout.
* **It does not poll ROKI in the background.** There is no fallback reconciliation job. If the webhook URL is not registered in the ROKI portal, paid donations stay pending forever. Registering it is step 5 below and it is not optional.
* It does not store card numbers. It never receives them.
* It does not translate its own screens. The plugin's settings and messages are in Spanish whatever language your WordPress admin is set to; only this readme is in English.

**You need a ROKI account**

This plugin connects your site to ROKI Connect, a third-party payment service, and it does not work without it. You need a ROKI merchant account to obtain your keys.

Nothing is transmitted until a donor starts a donation. At that moment the plugin sends the ROKI API the donation amount, a donation reference, the title of the donation form, the return URLs of your site, and identifiers of the donation and of the site itself. If your form collects them, it also sends the donor's name, email address and phone number. Afterwards it asks ROKI to void or refund a transaction only when you press refund in the WordPress admin.

* Service: https://roki.la
* Technical documentation: https://connect.roki.la
* Terms of service: https://roki.la/terms
* Privacy policy: https://roki.la/privacy

Built in Honduras by Danilo Antúnez.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install it from **Plugins > Add New > Upload Plugin**.
2. Activate it from the **Plugins** menu. GiveWP 3.0 or later has to be installed and active.
3. Go to **Donations > Settings > Payment Gateways** and open the **ROKI Connect** section.
4. Paste your secret key into **Llave secreta de sandbox** to test, or into **Llave secreta de produccion** to charge for real. Test keys start with `sk_test_` and live keys with `sk_live_`; both come from the API Integration tab of the ROKI portal. The plugin's own fields are in Spanish whatever language your admin is in.
5. Copy the webhook URL shown on that screen, register it in the Webhooks tab of the ROKI portal, and paste the signing secret it gives you into **Secreto de firma del webhook**.
6. Under **Donations > Settings > General**, set the currency to **Honduran Lempira**.
7. Enable ROKI Connect on your donation form and make a test donation with a sandbox key before taking real money.

== Frequently Asked Questions ==

= Which currencies can it charge in? =

Honduran lempiras (HNL) only, which is what ROKI Connect processes. If the form is set to another currency the plugin stops before charging instead of charging the wrong amount.

= Do I really have to register the webhook? =

Yes. The signed notification is the only thing that completes a donation, and this plugin has no background job that asks ROKI about pending donations. Without the webhook registered, the money arrives at ROKI and the donation stays pending in GiveWP.

= Can I test without moving real money? =

Yes. With an `sk_test_` key everything works the same against the ROKI sandbox, and no money moves.

= Can I refund a donation from the WordPress admin? =

Yes, on GiveWP 4.6 or later. The plugin voids the transaction first when it still can and refunds it once it has settled. GiveWP always refunds the full donation, so there is no partial case to decide.

= Does it work with the old donation forms? =

Yes. The gateway shows up both in the GiveWP visual form builder and in the previous generation of forms.

= Can I run it alongside the ROKI Connect plugin for WooCommerce? =

Yes. A parish or a school that also sells something can have both installed. Each one carries the same PHP API client inside; the first to load wins and the other reuses it.

= Do donors need a ROKI account? =

No. Only the organization receiving the donations needs one.

== External services ==

This plugin connects to **ROKI Connect**, the payment API of ROKI Technologies S.A. de C.V., to
take card donations. A ROKI merchant account is required; the plugin does nothing without one. ROKI
is the payment processor, so this connection is what the plugin is for.

**What is sent, and when**

Every time a donor submits a donation and chooses this gateway, the plugin sends the following to
`https://aura.roki.systems/api/connect/v1`:

* the donation amount, and a label built from the donation form's title;
* the donation id, the form id, the donation key and your site URL, so the donation can be matched
  back when ROKI notifies your site;
* an expiry time for the payment link;
* the return addresses on your site, so the donor comes back after paying;
* the donor's name, email address and phone number, **only when they are present** in the donation.
  They prefill ROKI's payment form and are used for the receipt.

The card number is never sent by the plugin and never reaches your server: the donor types it on
ROKI's own page, and only the result comes back.

The plugin also queries that same API to check the status of pending donations.

**Terms and privacy**

* Terms and Conditions: https://roki.la/terms
* Privacy Policy: https://roki.la/privacy

== Screenshots ==

1. The ROKI Connect settings inside GiveWP payment gateways.

== Changelog ==

= 1.0.0 =
* First release.
* Donations charged through the hosted ROKI checkout, on both the new and the legacy GiveWP forms.
* Signed webhooks with HMAC-SHA256 over the raw body, constant-time comparison and deduplication by event identifier.
* Each notification is matched to the site it belongs to, so two sites sharing one ROKI account cannot complete each other's donations.
* Voids and refunds from the WordPress admin.
* Optional donor-covered processing fee and a configurable expiry for the payment link.

== Upgrade Notice ==

= 1.0.0 =
First release. After activating, register the webhook URL shown on the settings screen in the ROKI portal: that signed notification is what completes a donation, and there is no fallback polling.
