> ## 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.

# PrestaShop

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

# NiftiPay for PrestaShop

Accepts crypto, fiat card, and ramping payments in PrestaShop. Shared concepts
are covered in [E-commerce plugins](/docs/plugins/overview).

## Requirements

* PrestaShop 1.7.0.0 or newer
* PHP ≥ 7.4

## Download

<Card title="Download NiftiPay for PrestaShop" icon="download" href="https://drive.google.com/file/d/1nsvJvp-9wivtKUPppcNb-TDJvIGk222V/view?usp=sharing">
  Latest release as a `.zip`, ready to upload to PrestaShop.
</Card>

## Before you install

Have both credentials ready — the module 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 module 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-confirmation page. The
      module overrides this per order when **Return URL mode** is *PrestaShop
      order-confirmation 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 module.
    * **Merchant webhook URL** *(required)* — your shop's webhook controller URL,
      shown on the module configuration 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 module.
  </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. If
  several integrations must post to one shop, fill the **Webhook secrets map**
  below.
</Note>

## Installation

<Steps>
  <Step title="Install the module">
    Upload the `niftipay` folder to `modules/` and install it from **Modules →
    Module Manager**. Install creates the transaction table, registers the
    module hooks, and adds a custom order state, **Awaiting NiftiPay Payment**.
  </Step>

  <Step title="Open the configuration page">
    Click **Configure** on the NiftiPay module.
  </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 on the configuration page into the NiftiPay
    dashboard, then paste the returned **Webhook secret** back into the module.
  </Step>

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

## 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                                                        |
| Webhook secrets map | Optional JSON of `webhookId → secret`, so several integrations can post to one shop                                |
| Return URL          | Used only in **custom** return mode                                                                                |
| Return URL mode     | *Custom URL* or *PrestaShop order-confirmation page* (recommended — returns the customer to their real order page) |
| Failure URL         | Where the customer goes when a payment fails                                                                       |
| Debug               | Verbose logging                                                                                                    |

### Per method

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

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

## Endpoints the module exposes

| Controller     | Purpose                                                                        |
| -------------- | ------------------------------------------------------------------------------ |
| `webhook`      | Receives payment status updates — this is the URL to register in the dashboard |
| `validation`   | Creates the PrestaShop order and the NiftiPay order, then redirects            |
| `status`       | Polled while a crypto invoice is open                                          |
| `return`       | Handles the customer coming back from a hosted payment page                    |
| `fraudsignals` | Employee-only proxy for fraud signals and IP risk on the admin order page      |

The webhook URL looks like
`https://shop.example.com/index.php?fc=module&module=niftipay&controller=webhook`,
or its friendly-URL equivalent when friendly URLs are enabled. The exact URL for
your shop is shown on the configuration page.

## Payment flows

The module creates the PrestaShop order first, resolves the return URL, then:

**Crypto** — creates the NiftiPay order and stores the address, network,
destination tag, amount, and expiry; the customer goes to the order-confirmation
page, which renders the QR and countdown and polls for status.

**Fiat** — creates the order with `serviceFeePayer`, `returnUrl`, and
`failureUrl`, stores the fiat order key for refunds, and redirects the customer
to the hosted payment page.

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

If order creation fails, the order is moved to the error state with a message
and the customer is sent to your **Failure URL** when one is configured.

## Order state mapping

| Event                  | Resulting state                                                 |
| ---------------------- | --------------------------------------------------------------- |
| `paid`                 | Your configured paid status — *Payment accepted* or *Delivered* |
| `pending`, `underpaid` | Awaiting NiftiPay Payment                                       |
| `cancelled`, `expired` | Cancelled — skipped if the order is already paid                |
| `refunded`             | Refunded                                                        |

A `paid` event on an already-cancelled order marks the transaction as **late
paid** and adds an order message rather than reopening the order.

## Admin features

* **Test API key** and **Refresh coins** buttons on the configuration page.
* Order page panel with the transaction details, fee payer, crypto refund
  address form, fiat cancel/refund button, and a fraud signals / IP risk block.

## Troubleshooting

| Symptom                                                       | Cause                                                                                                          |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Webhooks return 401                                           | Secret mismatch, or the event's webhook ID has no entry in the secrets map and the single secret doesn't match |
| Customer lands on a custom page instead of order confirmation | **Return URL mode** is set to *Custom URL* — switch it to *PrestaShop order-confirmation page*                 |
| Method missing at checkout                                    | Disabled in the module, disabled on your account, or the cart total is outside the method's min/max            |
| Order stuck on *Awaiting NiftiPay Payment*                    | The webhook never arrived — check the URL is publicly reachable and enable **Debug**                           |
| Fee payer keeps reverting                                     | Expected — your account default wins. The configuration page adopts it on load, with a 5-minute cache          |