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

# PagoPlux

> Charge cards in Ecuador through the PagoPlux API de Pago with your own card form and @fire-spark/payments-pagoplux-card.

> [!WARNING]
>
> **Beta.** `@fire-spark/payments-pagoplux-card` is in beta since SDK 0.13.1. PagoPlux voids only whole, same-day transactions by API, and has no status API. Test in sandbox before going live.

PagoPlux (pagoplux.com) is an Ecuadorian card processor. Fire spark uses its **API de Pago** (card not present): your channel shows its own card form on web, app, or kiosk, the package encrypts the card on the device, and Fire spark charges it with your PagoPlux credentials. The card never reaches Fire spark in plain text, and the PagoPlux secret key never reaches the channel.

| | |
| - | - |
| Countries | Ecuador |
| Currencies | USD |
| Status | Available (beta) |
| Package | `@fire-spark/payments-pagoplux-card` |

| Method | What the customer does |
| - | - |
| Card (`CARD`) | Types the card in your form. Diners, Interdin, and Discover cards also ask for a one-time code the bank sends by SMS or email |

## How it works

1. Your channel shows its card form and returns what the cardholder typed.
2. The package encrypts each card field on the device with AES-256-ECB and a one-time 32-character key, then encrypts that key with RSA using the payment's `encryption_public_key`. PagoPlux requires card data to leave the client encrypted.
3. Fire spark charges the encrypted card with the `client_id` and `secret_key` of the payment. The amount comes from the tender, never from the device.
4. If the card needs a one-time code, the package asks for it and sends the same encrypted card again with the code.

The package never stores or logs the card, and the Fire spark API never logs the encrypted card or the OTP session.

## Requirements

* A PagoPlux merchant account with access to the API de Pago, and its API access keys for each environment (sandbox and production are separate).
* An encryption public key generated in the PagoPlux dashboard. **PagoPlux must enable the public-key permission** on your account before you can generate it. There is one key per merchant.
* Your own card form. Fire spark does not draw it; your channel does.
* On React Native, `crypto.getRandomValues`: install `react-native-get-random-values` or `expo-crypto` (see [React Native](#react-native)).

## Activate it

1. In the dashboard, open your merchant, go to **Payments**, and create a payment with the provider **PagoPlux** and the method `CARD`.
2. In **Connection Settings**, fill in:

| Field | Key | Secret | Notes |
| - | - | - | - |
| Client ID | `client_id` | No | "Id Cliente" under the API access keys of the PagoPlux dashboard |
| Secret key | `secret_key` | Yes | "Clave Secreta". Stays in the Fire spark API; never sent to channels |
| Establishment ID | `establishment_id` | No | The establishment number your PagoPlux administrator hands over (e.g. `57`). Fire Spark sends it in base64; a value already in base64 also works |
| Encryption public key | `encryption_public_key` | No | RSA public key (PEM) from the **Generate** button in the PagoPlux dashboard. Sent to the channel to encrypt the card |
| Saved cards | `saved_cards` | No | Optional. `enabled` and `max_per_customer` (1 to 10). See [Saved cards](#saved-cards) |

3. Optional: set `installments` to offer deferred payments (see [Installments](#installments)), and `provider_environment` to force `sandbox` or `production`. Without it, the environment follows the merchant's.

### Per store

Each store can override these settings under **Store settings** in the payment form. Every field is optional: what a store leaves empty uses the Connection Settings above.

| Field | When |
| - | - |
| Establishment ID (`establishment_id`) | Each store with its own PagoPlux establishment (the usual case) |
| Client ID + Secret key (`client_id`, `secret_key`) | A store charged through its own PagoPlux account. Set both: a lone client ID is ignored. The secret key never leaves the Fire Spark API, not even to kiosks |
| Encryption public key (`encryption_public_key`) | The public key of that store's account |

Fire Spark charges and voids with the settings of the order's store, and the adapter asks Fire Spark for the store's public key (the `encryption_key` operation) before encrypting the card.

## Use it in the SDK

```bash theme={null}
pnpm add @fire-spark/payments-pagoplux-card
# React Native only (one of the two)
pnpm add react-native-get-random-values
npx expo install expo-crypto
```

Your channel implements a **collector**: it opens your card form and resolves with what the cardholder typed, or `null` if they cancelled. The adapter does the rest: it encrypts the card, asks Fire spark to charge it, and asks for the OTP when the bank requires one.

```typescript theme={null}
import { pagopluxCardPayments } from "@fire-spark/payments-pagoplux-card";
import type { PagopluxCardCollector } from "@fire-spark/payments-pagoplux-card";

const collector: PagopluxCardCollector = {
  collect: input => {
    // Your form: show input.amount and input.currency, and offer
    // input.installmentOptions when it is not empty.
    return openCardForm({
      amount: input.amount,
      currency: input.currency,
      installmentOptions: input.installmentOptions,
      signal: input.signal
    }).then(values => {
      if (!values) return null; // cancelled
      return {
        card: {
          number: values.cardNumber,
          expirationMonth: values.month, // "MM" or "M"
          expirationYear: values.year, // "YY" or "YYYY"
          cvv: values.cvv
        },
        buyer: {
          name: values.cardholderName,
          document_number: values.cedula // cédula or RUC, digits only
        },
        installments: values.installments ?? 0,
        interests: values.withInterest ?? false
      };
    });
  }
};

order.setPaymentAdapters([pagopluxCardPayments({ collector })]);

const result = await order.payIntent({ payment: pagopluxPayment });
```

The OTP prompt uses your payment UI (`input` in `order.setPaymentUI`), and progress messages use `message`. See [Terminal prompts and storage](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md#terminal-prompts-and-storage).

`payIntent({ payment })` places one real tender. To split PagoPlux with another method, call `order.setTenders` with an allocation and then `payIntent()`. See [Use payments in the SDK](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md).

### Options

| Option | Required | Description |
| - | - | - |
| `collector` | Yes | Your card form (`PagopluxCardCollector`) |
| `otpLabel` | No | Label of the OTP prompt. Default: `Código enviado por tu banco (SMS o email)` |
| `random` | No | Secure random source. Default: `crypto.getRandomValues` |

### The collector

`collect(input)` receives:

| Field | Description |
| - | - |
| `amount`, `currency` | What the tender charges. Show it on the form |
| `installmentOptions` | The installment counts configured on the payment, or `[]` when installments are off |
| `canSaveCard` | `true` when the payment has saved cards on: show the "Save card" checkbox |
| `error` | A message to show when a previous submission failed. `null` on the first call |
| `signal` | Aborted when the attempt is cancelled or times out. Close the form |

It resolves with a `PagopluxCardForm`, or `null` if the customer cancelled (the tender ends `FAILED` with `CANCELLED_BY_USER`):

| Field | Required | Description |
| - | - | - |
| `card.number`, `card.expirationMonth`, `card.expirationYear`, `card.cvv` | Yes | As typed. Non-digits in the number are removed; only the last two digits of the year are sent |
| `buyer` | No | `name` (cardholder name, split into first and last names) or `first_name` and `last_name`, `document_number`, `phone`, `email` |
| `shippingAddress` | No | `country`, `city`, `street`, `number` |
| `installments` | No | Months of deferral. `0` (default) is a single payment |
| `interests` | No | `true` for deferral with interest |
| `saveCard` | No | `true` when the customer ticked "Save card" (see [Save and pay](#save-and-pay)). Ignored when `canSaveCard` is `false` |

> [!WARNING]
>
> Never store, log, or send the card anywhere else. Resolve the promise and clear the form: the adapter encrypts the card right away.

PagoPlux requires the full buyer: document number (cédula or RUC), first and last names, phone, email, city, country, and street. Fire spark fills them from the order customer (customer, address, and billing info). What the form sends in `buyer` and `shippingAddress` wins, so ask for the cardholder name and ID number when they may differ from the customer. If a field is still missing, the charge is rejected with `INVALID_REQUEST`.

### React Native

The package encrypts with `crypto.getRandomValues`, which React Native does not ship. Do one of these:

```typescript theme={null}
// Option 1: polyfill once, at the top of your app entry
import "react-native-get-random-values";

// Option 2: pass expo-crypto as the random source
import * as Crypto from "expo-crypto";

pagopluxCardPayments({
  collector,
  random: bytes => Crypto.getRandomValues(bytes)
});
```

Without either, the charge fails before anything is sent to PagoPlux.

## One-time code (OTP)

Diners, Interdin, and Discover cards ask for a code the bank sends to the cardholder by SMS or email:

1. Fire spark charges the card and PagoPlux answers that an OTP is required.
2. The adapter asks for the code with `ui.input` (label `otpLabel`).
3. It sends the same encrypted card again with the code. The cardholder never retypes the card.
4. A wrong code can be retyped up to **3 times** in total. After that, the tender ends `FAILED` with `INVALID_PIN`.

## 3-D Secure

When the cardholder's bank requires it, PagoPlux answers with a bank challenge instead of charging:

1. The adapter shows it with `ui.challenge` of your payment UI (see [Bank challenges](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md#bank-challenges-3-d-secure)). 3DS v1 posts a form to the bank; 3DS v2 opens the bank URL.
2. The cardholder approves the payment on the bank page.
3. The bank sends the browser to Fire spark, which confirms the payment with PagoPlux and records the tender `PAID` or `FAILED`.
4. The adapter reads that result and returns it.

If your payment UI has no `challenge`, the tender ends `FAILED` with `INVALID_REQUEST` and nothing is charged. If the customer closes the challenge before the bank answers, the tender ends `FAILED` with `AMBIGUOUS` and is flagged for review: check the PagoPlux dashboard.

## Saved cards

Customers can save their card in PagoPlux and pay with it later without typing it again. PagoPlux tokenizes the card (card registration API); Fire spark keeps only an encrypted reference to the token, the brand, the last 4 digits, and the expiry. The token never reaches the channel.

### Turn them on

In the PagoPlux payment **Connection Settings**:

| Field | Key | Default | Notes |
| - | - | - | - |
| Saved cards | `saved_cards.enabled` | Off | When off, saving a card and paying with a saved one answer `SAVED_CARDS_DISABLED`. Deleting a card always works |
| Maximum cards per customer | `saved_cards.max_per_customer` | `5` | From 1 to 10 active cards per customer. Lowering it deletes no cards: customers over the limit delete one before saving another |

Saving a card needs a customer signed in to the storefront. When it registers the card, PagoPlux authorizes a minimal amount to validate it and reverses it right away: Fire spark charges and reverses nothing for the tokenization.

### Save and pay

When the payment has saved cards on, the collector receives `canSaveCard: true`. Show a "Save card" checkbox and return `saveCard: true` when the customer ticks it. The adapter:

1. Saves the card with the same encrypted card. The card's OTP or 3-D Secure is asked here when the bank requires it.
2. Charges the tender with the saved card, with the chosen installments.

| Case | Result |
| - | - |
| Paid | `PAID`, and `metadata.provider.saved_card` is `{ saved: true, id, brand, last4 }` |
| The customer is at the limit, the payment has saved cards off, or nobody is signed in | Charged anyway without saving the card. `metadata.provider.saved_card` is `{ saved: false, reason }` |
| The bank declines the card while saving it, the OTP was wrong 3 times, or 3-D Secure failed | `FAILED`, nothing charged |
| The card was saved but the payment with it was declined | `FAILED` with `CARD_DECLINED`. The card stays saved |

A payment with a saved card is voided like any PagoPlux payment (see [Refunds](#refunds)).

### Save only

For a "my cards" screen, with no order and no charge:

```typescript theme={null}
import { services } from "@fire-spark/core";
import { registerPagopluxCard } from "@fire-spark/payments-pagoplux-card";

const result = await registerPagopluxCard({
  server: {
    call: (operation, input) =>
      services.payments.operation(pagopluxPaymentId, operation, {
        order_id: null,
        attempt_reference: null,
        input
      })
  },
  ui: paymentUI, // input for the OTP, challenge for 3-D Secure
  collector // the same form; it receives amount 0
});

if (result.status === "REGISTERED") showCard(result.card);
```

| Result | What to do |
| - | - |
| `REGISTERED` | `card` has `id`, `brand`, `last4`, `expiry_month`, `expiry_year` |
| `CANCELLED` | The customer closed the form, the OTP prompt, or the challenge |
| `FAILED` + `SAVED_CARDS_DISABLED` | The merchant has saved cards off. Hide the option |
| `FAILED` + `SAVED_CARDS_LIMIT` | The customer is at the limit. Ask them to delete one |
| `FAILED` + `CARD_DECLINED` | The bank declined the card |
| `FAILED` + `INVALID_PIN` | The OTP was wrong 3 times |
| `FAILED` + `UNAUTHENTICATED` | Nobody is signed in |
| `FAILED` + `AMBIGUOUS` | No answer from the bank or PagoPlux. List the cards to check |

### List and delete

| Endpoint | What it does |
| - | - |
| `GET /api/storefront/v1/saved-cards` | Active cards of the signed-in customer: `id`, `brand`, `last4`, `expiry_month`, `expiry_year`, `provider` |
| `POST /api/storefront/v1/saved-cards/{card_id}/revoke` | Deletes the card in PagoPlux and in Fire spark and frees the slot |

## Installments

Turn on `installments` in the payment config (`enabled` and `options`) to offer deferred payments. The adapter passes the options to your form as `installmentOptions`; return the chosen count in `installments` and `interests` for deferral with interest. The maximum is 48 months. Debit cards are always a single payment (`0`).

## Amounts and taxes

Fire spark computes the amounts on the server: the taxed part of the order lines is prorated to the tender amount and sent as the amount with VAT, the rest as the amount without VAT. Both add up to the tender amount. The device never sends an amount.

## Storefront endpoint

The adapter calls this through the payment server operation. It uses the storefront session.

| Endpoint | What it does |
| - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/charge` | Charges the encrypted card for the current payment attempt, with the OTP when PagoPlux asked for one. Returns the outcome (`PAID`, `FAILED`, `PENDING`, `OTP_REQUIRED`, or `THREE_DS_REQUIRED` with the bank `challenge`). The amount comes from the tender, never from the request |
| `POST /api/storefront/v1/payments/{payment_id}/operations/encryption_key` | Public key to encrypt the card with: the order store's, else the Connection Settings one |
| `POST /api/storefront/v1/payments/{payment_id}/operations/three_ds_result` | After a 3-D Secure challenge: the tender status and the outcome Fire spark recorded when the bank sent the customer back |
| `GET /api/webhooks/payments/pagoplux/3ds-return/{ref}` | Where the bank sends the customer after the challenge (public, `ref` is signed by Fire spark). You never call it |
| `POST /api/storefront/v1/payments/{payment_id}/operations/register_card` | Saves the encrypted card of the signed-in customer. Returns `REGISTERED` with the card, `OTP_REQUIRED`, `OTP_INVALID`, `THREE_DS_REQUIRED` with the `challenge` and a `registration_ref`, or `FAILED`. It never returns the token |
| `POST /api/storefront/v1/payments/{payment_id}/operations/register_card_result` | After the 3-D Secure challenge of a registration: `PENDING`, `REGISTERED` with the card, or `FAILED` |
| `POST /api/storefront/v1/payments/{payment_id}/operations/charge_with_token` | Charges the current payment attempt with a saved card (`card_ref`, `confirmed_total`, `installments`, `interests`) |
| `GET /api/webhooks/payments/pagoplux/card-3ds-return/{ref}` | Where the bank sends the customer after a registration challenge (public, `ref` is signed by Fire spark). You never call it |

## What the customer sees

Your card form, then the OTP prompt or the bank challenge from your payment UI when the bank requires it. A paid tender records `details` with the card brand, last 4 digits, the authorization code, and the installments when there are more than one. The result metadata includes `attempt_reference`, `payment` (`provider_transaction_id`, `authorization_code`, `brand`, `card_type`, `last4`, `acquirer`), and `provider` (`code`, `transaction_id`, `token`, `date`, `amount`). When the customer asked to save the card, `provider.saved_card` says whether it was saved. There is no voucher.

## Timeouts and unknown results

* One attempt lasts up to 10 minutes (form, issuer, and OTP). It is never retried automatically: the API de Pago has no idempotency key, so a retry could charge twice.
* If PagoPlux does not answer within 45 seconds, or answers that the payment is pending, the tender ends `FAILED` with `AMBIGUOUS` and `needs_review`. The API de Pago has no status query, so someone must check the transaction in the PagoPlux dashboard.

## Refunds

Fire Spark voids a paid PagoPlux charge on the server when you call `order.cancel()` or `order.refund()`, with the payment's `secret_key` (PagoPlux reverse API by transaction id). The device does nothing: the adapter reports the reversal as `server`.

* **Whole transaction only.** A partial refund is not sent to PagoPlux: the ledger operation fails and you refund it by hand in the PagoPlux dashboard.
* **Same day only.** PagoPlux voids a transaction only before its daily cutoff (17:30 or midnight, depending on the merchant). After that the void fails with "fecha no permitida": refund it by hand in the PagoPlux dashboard.
* **Idempotent.** Voiding again answers "already voided" and counts as done.
* An attempt that was never charged is just discarded; if PagoPlux says it was never authorized, there is nothing to reverse.

A failed reversal stays in the order's payment ledger with PagoPlux's reason, for an operator to finish.

## Common errors

| Spark code | PagoPlux code | What to do |
| - | - | - |
| `CARD_DECLINED` | `2` (declined, or "Tarjeta Bloqueada") | Ask for another card or method |
| `INSUFFICIENT_FUNDS` | `2` ("Cupo no disponible") | Ask for another card or method |
| `EXPIRED_CARD` | `2` ("Tarjeta Expirada") | Ask for another card |
| `INVALID_CARD` | `2` (invalid card number) | Check the card number and try again |
| `INVALID_PIN` | `102` | The OTP was wrong 3 times. Start again |
| `INVALID_CREDENTIALS` | `1`, `302`, HTTP 401/403 | Check `client_id`, `secret_key`, `establishment_id`, and their environment in Connection Settings |
| `INVALID_REQUEST` | `301`, `303`, missing buyer data | Check the installment plans with PagoPlux, or send the missing buyer fields |
| `LIMIT_EXCEEDED` | `304` | Daily or monthly amount or count exceeded. Ask for another method |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429 | Try again with a new attempt |
| `CANCELLED_BY_USER` | — | The customer closed the card form |
| `AMBIGUOUS` | `103`, `2` ("ya fue procesada"), no answer, a 2xx answer in an unknown format | Flagged for review. Check the transaction in the PagoPlux dashboard |

The package exports the PagoPlux code map as `pagopluxErrors`. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md).

## Test in sandbox

Set `provider_environment` to `sandbox` (or use a sandbox merchant). PagoPlux test cards:

| Card | Number | Result |
| - | - | - |
| VISA | `4540639936908783` | Paid |
| Diners | `36417200103608` | Asks for OTP `123456`, then paid |
| Discover | `6011761603370843` | Asks for OTP `123456`, then paid |
| VISA | `4540633357674263` | Declined: "Cupo no disponible" (`INSUFFICIENT_FUNDS`) |

Use expiration `04/29` and CVV `123` (`1234` for Amex), and a valid Ecuadorian ID (cédula) as `document_number`: the sandbox rejects invented ones. When your sandbox merchant has 3-D Secure on, VISA, Mastercard, and Amex ask for the bank challenge; the test page shows the code. The same cards work for saving a card.

## Compatibility

| `@fire-spark/payments-pagoplux-card` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.13.1 (beta) | PagoPlux API de Pago 1.2 | Same version |
| 0.14.0 (beta) | PagoPlux API de Pago 1.3 (3-D Secure) | Same version |
| 0.18.0 (beta) | PagoPlux API de Pago 1.3 and card registration API 1.2 (saved cards) | Same version |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.