> ## Documentation Index
> Fetch the complete documentation index at: https://www.niftipay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce

> Install and configure the NiftiPay plugin for WooCommerce — crypto, fiat card, and ramping payments with webhooks, refunds, and fraud signals.

# NiftiPay for WooCommerce

Accepts crypto, fiat card, and ramping payments in WooCommerce. Works with both
classic checkout and WooCommerce Blocks. Shared concepts are covered in
[E-commerce plugins](/docs/plugins/overview).

## Requirements

* WordPress ≥ 6.2
* WooCommerce ≥ 6.0
* PHP ≥ 7.4

## Download

<Card title="Download NiftiPay for WooCommerce" icon="download" href="https://drive.google.com/file/d/19u5S9eUtE1AXMPBxRY6sdgL_79XEk5Ov/view?usp=sharing">
  Latest release as a `.zip`, ready to upload to WordPress.
</Card>

## Before you install

Have both credentials ready — the plugin can't create an order without them:

| # | What               | Where to get it                                                                                                          |
| - | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| 1 | **API key**        | Dashboard → **Settings → API Keys** → *Create key*. Copy it once — it is not shown again. See [API keys](/docs/api/api-keys). |
| 2 | **Integration ID** | Dashboard → **Settings → Fiat** → *Integrations*. See below.                                                             |

### Get your Integration ID

A **fiat integration** is the per-shop configuration your orders attach to:
which URLs the customer comes back to, and where status updates are sent. Every
order the plugin creates references exactly one integration.

<Steps>
  <Step title="Open Dashboard → Settings → Fiat">
    Fill the *Create integration* form:

    * **Name** — anything you recognise, e.g. `My Shop`.
    * **Return URL** *(required)* — your shop's order-received page. The plugin
      overrides this per order when **Return URL mode** is *WooCommerce
      thank-you page*, so any valid URL on your shop works here.
    * **Failure URL** — where the customer lands after a failed/cancelled payment.
      Must match the **Failure URL** you set in the plugin.
    * **Merchant webhook URL** *(required)* — your shop's webhook endpoint,
      shown at the top of the plugin settings page.
    * **Contact URL** — your contact/support page, shown to blocked customers.
  </Step>

  <Step title="Copy the ID">
    The new integration appears under **Your integrations** with
    `Integration ID: <id>`. Press **Copy ID** — that is the value you paste into
    the plugin.
  </Step>
</Steps>

Prefer the API? `GET /api/fiat/integrations` returns the same list:

```bash theme={null}
curl -X GET "https://www.niftipay.com/api/fiat/integrations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"
```

`integrations[].id` (e.g. `fi_abc123`) is the Integration ID. Full CRUD is in
[Fiat integrations](/docs/api/fiat-integrations); the same walkthrough with more
context is in [Fiat orders → How to get your `integrationId`](/docs/api/fiat-orders#how-to-get-your-integrationid).

<Note>
  **One integration per shop.** Running several shops on one account? Create one
  integration each — that keeps return URLs and webhooks from crossing over, and
  lets you filter orders per shop.
</Note>

## Installation

<Steps>
  <Step title="Install the plugin">
    In WordPress go to **Plugins → Add New → Upload Plugin**, pick the `.zip`
    you downloaded, install it, and activate. Activation registers the
    `/niftipay/webhook` endpoint and flushes rewrite rules.
  </Step>

  <Step title="Open the settings">
    Go to **WooCommerce → Settings → Payments → Niftipay**.
  </Step>

  <Step title="Add your credentials">
    Paste your **API key**, then your **Integration ID** — see
    [Get your Integration ID](#get-your-integration-id) above.
  </Step>

  <Step title="Register the webhook">
    Copy the **Webhook URL** shown at the top of the settings page into the
    NiftiPay dashboard (Webhooks section), then paste the returned **Webhook
    secret** back into the plugin.
  </Step>

  <Step title="Enable your payment methods">
    Turn on Crypto, Fiat, and/or Ramping, then save.
  </Step>
</Steps>

## Gateways

The plugin registers three WooCommerce gateways, all configured from the first
one's settings screen:

| Gateway ID         | Method    | Refunds              |
| ------------------ | --------- | -------------------- |
| `niftipay`         | Crypto    | Yes (refund address) |
| `niftipay_fiat`    | Fiat card | Yes (cancel/refund)  |
| `niftipay_ramping` | Ramping   | —                    |

## Settings reference

### Shared

| Setting         | Notes                                                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| API Key         | Your NiftiPay API key (Dashboard → Settings → API Keys)                                                                           |
| Integration ID  | Dashboard → Settings → Fiat → Integrations → **Copy ID**. The same integration is used by all three methods                       |
| Webhook Secret  | Returned by the dashboard when you register the webhook URL                                                                       |
| Return URL      | Used only in **custom** return mode                                                                                               |
| Return URL mode | *Use the Return URL above* or *WooCommerce thank-you page* (recommended — returns to the order-received page, order key included) |
| Failure URL     | Must match the failure URL on your integration                                                                                    |
| Debug log       | Writes to **WooCommerce → Status → Logs**, source `niftipay`                                                                      |

### Per method

Each of Crypto, Fiat, and Ramping has its own block of settings:

| Setting                       | Notes                                                                |
| ----------------------------- | -------------------------------------------------------------------- |
| Enable                        | Show the method at checkout                                          |
| Title / Description           | Checkout label and blurb                                             |
| Coins                         | Accepted tokens; refresh the list with the **Refresh coins** button  |
| Paid status                   | Order status applied when the `paid` event arrives                   |
| Minimum / Maximum order total | Per-currency, e.g. `EUR 10`, `USD 12`. Empty means no limit          |
| Card Fee Payer *(fiat only)*  | `customer` or `merchant`, synced with your account default both ways |

## Endpoints the plugin exposes

| Route                                          | Auth                            | Purpose                                                                        |
| ---------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------ |
| `POST /niftipay/webhook`                       | HMAC signature or shared secret | Payment status updates                                                         |
| `POST /wp-json/niftipay/v1/webhook`            | same                            | Same handler, REST route                                                       |
| `GET /wp-json/niftipay/v1/order-status`        | public (`id` = order ID)        | Polled by the invoice page; returns status, expiry, and a display message only |
| `GET /wp-json/niftipay/v1/order-risk`          | shop manager                    | IP risk for an order                                                           |
| `GET /wp-json/niftipay/v1/order-fraud-signals` | shop manager                    | Consolidated fraud signals                                                     |

<Note>
  If pretty permalinks are disabled on the site, register the
  `/wp-json/niftipay/v1/webhook` route in the dashboard instead of
  `/niftipay/webhook`.
</Note>

## Payment flows

**Crypto** — creates the order at NiftiPay, sets the WooCommerce order to
`on-hold`, and returns the customer to the order-received page, which renders
the invoice (QR, address, amount, countdown) and polls `order-status` every 10
seconds. The message swaps in place when the invoice expires, is cancelled, is
refunded, or is detected as paid.

**Fiat** — creates the order (sending `serviceFeePayer`, `returnUrl`,
`failureUrl`), stores the fiat order key for later refunds, sets the order to
`on-hold`, and redirects the customer to the hosted payment page. NiftiPay then
returns the customer to whichever URL the **Return URL mode** selects.

**Ramping** — creates a payment link and redirects to it.

## Admin features

* **Test API key** and **Refresh coins** buttons on the settings screen.
* Service-fee breakdown under the order totals on the admin order screen.
* Refund address field and fiat refund action on the order screen.
* Fraud signals and IP risk panel per order.
* A guard rail rewrites a bare `/order-received/` hit to the canonical
  order-received URL when the order can't be resolved from the path, which
  prevents "invalid order" landings after returning from a payment page.

## Troubleshooting

| Symptom                                                       | Cause                                                                                                                        |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Webhooks return 401                                           | The secret in the plugin doesn't match the dashboard, or the webhook is bound to a different integration                     |
| Customer lands on a custom page instead of the thank-you page | **Return URL mode** is set to *Use the Return URL above* — switch it to *WooCommerce thank-you page*                         |
| Method missing at checkout                                    | Disabled in the plugin, disabled on your account, or the cart total is outside the method's min/max                          |
| Order stuck on `on-hold` after payment                        | The webhook never arrived — check the URL is publicly reachable and enable **Debug log**                                     |
| Card Fee Payer keeps reverting                                | Expected — your account default wins. Change it in the dashboard or in the plugin; they sync both ways with a 5-minute cache |