CryptoPayr — Lineage 2 crypto donation module
=============================================

Accept crypto (Bitcoin, Ethereum, USDT and 30+ coins) for your Lineage 2
server. Players buy "donate coins" on the CryptoPayr hosted checkout and the
purchased items are credited to their character automatically once the payment
is confirmed on-chain — via a signed webhook. No card data, no chargebacks.

Works with the common L2J / L2OFF cores (item delivery via items_delayed,
character_items, items_external or items).


1. Create your CryptoPayr project
---------------------------------
- Sign up at https://cryptopayr.com and verify your account.
- Go to Dashboard -> Developers and copy your API key (sk_live_...).
  The same key is used to create payments AND to verify incoming webhooks.


2. Upload the module
--------------------
- Upload the contents of this archive to your web server, e.g. into a folder
  named "donate" (https://yourserver.com/donate/).
- IMPORTANT: the server running these files must be able to reach your live
  Lineage 2 GAME database (not the website CMS database).
- The site must be reachable from the internet over HTTPS, because CryptoPayr
  delivers the payment webhook to handler.php.
- Make config.php writable (chmod 666 config.php) for the installer.


3. Run the installer
---------------------
- Open https://yourserver.com/donate/install.php and follow the steps:
    1) Environment checks
    2) Game database connection (creates the cryptopayr_payments table)
    3) Auto-detection of the character / item tables
    4) Settings: item ID granted per coin, price per coin, currency (USD/EUR/...),
       minimum coins per order, and your CryptoPayr API key.
       Optionally set the public URL of this folder (recommended if you run
       behind a proxy / load balancer).
- After it finishes, DELETE install.php. The module refuses to create payments
  while install.php still exists.


4. Add the donation form
------------------------
- Two ready-made pages are included:
    - form_example.php     (simple POST form)
    - form_with_ajax.php    (AJAX form with nicer error popups)
  Link to one of them from your website, or embed your own form that POSTs to
  payment.php with these fields:

    <form method="POST" action="/donate/payment.php">
        <input type="text"   name="us_account" placeholder="Character name">
        <input type="number" name="sum" min="1" placeholder="Number of coins">
        <input type="submit" value="Pay with crypto">
    </form>


How it works
------------
- payment.php looks up the character, records a pending order in
  cryptopayr_payments, creates a CryptoPayr payment (amount = coins x price),
  and redirects the player to the hosted checkout. The local order id is passed
  as the payment "metadata".
- handler.php receives the signed webhook. It verifies the
  X-CryptoPayr-Signature header (HMAC-SHA256 of the raw body with your API key),
  then on status COMPLETED credits ITEM_ID x coins to the character. The order
  is claimed atomically, so items are granted at most once even if the webhook
  is delivered more than once.


Notes & troubleshooting
-----------------------
- Order totals must clear the CryptoPayr minimum order amount. Set the coin
  price / minimum coins so a single order is at least a couple of USD.
- "Character not found": the name must match characters.char_name exactly.
- "item grant failed" in CryptoPayr's webhook log: the payment was received but
  the item insert failed (usually DB permissions). The order stays recoverable —
  fix permissions and CryptoPayr will retry, or grant the item manually. Every
  order is recorded in the cryptopayr_payments table (status: 0 pending,
  1 completed, 2 refunded) with the CryptoPayr transaction id (tid).
- Security: config.php holds your DB credentials and API key. The bundled
  .htaccess blocks direct web access to it and to the lib/ folder. Keep it.


Support
-------
Docs:  https://cryptopayr.com/docs
Email: support@cryptopayr.com

MIT licensed. (c) CryptoPayr
