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

> Cobra tarjetas en Ecuador con la API de Pago de PagoPlux, tu propio formulario de tarjeta y @fire-spark/payments-pagoplux-card.

> [!WARNING]
>
> **Beta.** `@fire-spark/payments-pagoplux-card` está en beta desde el SDK 0.13.1. PagoPlux solo anula por API transacciones completas del mismo día, y no tiene consulta de estado. Prueba en sandbox antes de salir a producción.

PagoPlux (pagoplux.com) es un procesador de tarjetas de Ecuador. Fire spark usa su **API de Pago** (tarjeta no presente): tu canal muestra su propio formulario de tarjeta en web, app o kiosco, el paquete cifra la tarjeta en el dispositivo y Fire spark la cobra con tus credenciales de PagoPlux. La tarjeta nunca llega a Fire spark en texto plano y la clave secreta de PagoPlux nunca llega al canal.

| | |
| - | - |
| Países | Ecuador |
| Monedas | USD |
| Estado | Disponible (beta) |
| Paquete | `@fire-spark/payments-pagoplux-card` |

| Método | Qué hace el cliente |
| - | - |
| Tarjeta (`CARD`) | Escribe la tarjeta en tu formulario. Las tarjetas Diners, Interdin y Discover además piden un código de un solo uso que el banco envía por SMS o email |

## Cómo funciona

1. Tu canal muestra su formulario de tarjeta y devuelve lo que escribió el titular.
2. El paquete cifra cada campo de la tarjeta en el dispositivo con AES-256-ECB y una llave de 32 caracteres de un solo uso, y cifra esa llave con RSA usando la `encryption_public_key` del pago. PagoPlux exige que la tarjeta salga cifrada del cliente.
3. Fire spark cobra la tarjeta cifrada con el `client_id` y el `secret_key` del pago. El monto sale del tender, nunca del dispositivo.
4. Si la tarjeta necesita un código de un solo uso, el paquete lo pide y vuelve a enviar la misma tarjeta cifrada con el código.

El paquete nunca guarda ni registra la tarjeta, y la API de Fire spark nunca registra la tarjeta cifrada ni la sesión OTP.

## Requisitos

* Una cuenta de comercio en PagoPlux con acceso a la API de Pago, y sus claves de acceso de API por entorno (sandbox y producción están separados).
* Una llave pública de cifrado generada en el dashboard de PagoPlux. **PagoPlux debe habilitar el permiso de llave pública** en tu cuenta antes de que puedas generarla. Hay una sola llave por comercio.
* Tu propio formulario de tarjeta. Fire spark no lo dibuja; lo hace tu canal.
* En React Native, `crypto.getRandomValues`: instala `react-native-get-random-values` o `expo-crypto` (ver [React Native](#react-native)).

## Activarlo

1. En el dashboard, abre tu comercio, ve a **Payments** y crea un pago con el proveedor **PagoPlux** y el método `CARD`.
2. En **Connection Settings**, completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Id de cliente | `client_id` | No | "Id Cliente" en las claves de acceso de API's del dashboard de PagoPlux |
| Clave secreta | `secret_key` | Sí | "Clave Secreta". Queda en la API de Fire spark; nunca llega a los canales |
| Id de establecimiento | `establishment_id` | No | El número de establecimiento que entrega el administrador de PagoPlux (ej. `57`). Fire Spark lo envía en base64; un valor ya en base64 también funciona |
| Llave pública de cifrado | `encryption_public_key` | No | Llave pública RSA (PEM) del botón **Generar** del dashboard de PagoPlux. Se envía al canal para cifrar la tarjeta |
| Tarjetas guardadas | `saved_cards` | No | Opcional. `enabled` y `max_per_customer` (1 a 10). Ver [Tarjetas guardadas](#tarjetas-guardadas) |

3. Opcional: define `installments` para ofrecer pagos diferidos (ver [Cuotas](#cuotas)) y `provider_environment` para forzar `sandbox` o `production`. Sin él, el entorno sigue al del comercio.

### Por tienda

Cada tienda puede sobrescribir estos datos en **Store settings** del formulario del pago. Todo es opcional: lo que una tienda deja vacío usa los Connection Settings de arriba.

| Campo | Cuándo |
| - | - |
| Id de establecimiento (`establishment_id`) | Cada tienda con su propio establecimiento PagoPlux (el caso normal) |
| Id de cliente + Clave secreta (`client_id`, `secret_key`) | Una tienda que cobra con su propia cuenta PagoPlux. Llena los dos: un id de cliente solo se ignora. La clave secreta nunca sale de la API de Fire Spark, ni siquiera a los kioscos |
| Llave pública de cifrado (`encryption_public_key`) | La llave pública de la cuenta de esa tienda |

Fire Spark cobra y anula con los datos de la tienda de la orden, y el adaptador le pide a Fire Spark la llave pública de la tienda (operación `encryption_key`) antes de cifrar la tarjeta.

## Usarlo en el SDK

```bash theme={null}
pnpm add @fire-spark/payments-pagoplux-card
# Solo React Native (una de las dos)
pnpm add react-native-get-random-values
npx expo install expo-crypto
```

Tu canal implementa un **collector**: abre tu formulario de tarjeta y resuelve con lo que escribió el titular, o `null` si canceló. El adaptador hace el resto: cifra la tarjeta, pide a Fire spark que la cobre y pide el OTP cuando el banco lo exige.

```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 => {
    // Tu formulario: muestra input.amount e input.currency, y ofrece
    // input.installmentOptions cuando no esté vacío.
    return openCardForm({
      amount: input.amount,
      currency: input.currency,
      installmentOptions: input.installmentOptions,
      signal: input.signal
    }).then(values => {
      if (!values) return null; // canceló
      return {
        card: {
          number: values.cardNumber,
          expirationMonth: values.month, // "MM" o "M"
          expirationYear: values.year, // "YY" o "YYYY"
          cvv: values.cvv
        },
        buyer: {
          name: values.cardholderName,
          document_number: values.cedula // cédula o RUC, solo dígitos
        },
        installments: values.installments ?? 0,
        interests: values.withInterest ?? false
      };
    });
  }
};

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

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

La pregunta del OTP usa tu UI de pagos (`input` en `order.setPaymentUI`) y los mensajes de progreso usan `message`. Ver [Preguntas del terminal y almacenamiento](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md#preguntas-del-terminal-y-almacenamiento).

`payIntent({ payment })` crea un tender real. Para dividir PagoPlux con otro método, llama `order.setTenders` con una asignación y luego `payIntent()`. Ver [Usar pagos en el SDK](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

### Opciones

| Opción | Requerida | Descripción |
| - | - | - |
| `collector` | Sí | Tu formulario de tarjeta (`PagopluxCardCollector`) |
| `otpLabel` | No | Etiqueta de la pregunta del OTP. Por defecto: `Código enviado por tu banco (SMS o email)` |
| `random` | No | Fuente aleatoria segura. Por defecto: `crypto.getRandomValues` |

### El collector

`collect(input)` recibe:

| Campo | Descripción |
| - | - |
| `amount`, `currency` | Lo que cobra el tender. Muéstralo en el formulario |
| `installmentOptions` | Las cuotas configuradas en el pago, o `[]` si las cuotas están apagadas |
| `canSaveCard` | `true` cuando el pago tiene las tarjetas guardadas activas: muestra la casilla "Guardar tarjeta" |
| `error` | Un mensaje para mostrar cuando un envío anterior falló. `null` en la primera llamada |
| `signal` | Se aborta cuando el intento se cancela o vence. Cierra el formulario |

Resuelve con un `PagopluxCardForm`, o `null` si el cliente canceló (el tender termina `FAILED` con `CANCELLED_BY_USER`):

| Campo | Requerido | Descripción |
| - | - | - |
| `card.number`, `card.expirationMonth`, `card.expirationYear`, `card.cvv` | Sí | Tal como se escribieron. Se quitan los caracteres que no son dígitos del número; del año solo se envían los dos últimos dígitos |
| `buyer` | No | `name` (nombre del titular, se separa en nombres y apellidos) o `first_name` y `last_name`, `document_number`, `phone`, `email` |
| `shippingAddress` | No | `country`, `city`, `street`, `number` |
| `installments` | No | Meses de diferido. `0` (por defecto) es pago corriente |
| `interests` | No | `true` para diferido con intereses |
| `saveCard` | No | `true` si el cliente marcó "Guardar tarjeta" (ver [Guardar y pagar](#guardar-y-pagar)). Se ignora si `canSaveCard` es `false` |

> [!WARNING]
>
> Nunca guardes, registres ni envíes la tarjeta a ningún otro lado. Resuelve la promesa y limpia el formulario: el adaptador cifra la tarjeta de inmediato.

PagoPlux exige el comprador completo: número de documento (cédula o RUC), nombres y apellidos, teléfono, email, ciudad, país y calle. Fire spark los toma del cliente de la orden (datos del cliente, dirección y facturación). Lo que el formulario envía en `buyer` y `shippingAddress` gana, así que pide el nombre del titular y su cédula cuando pueden ser distintos a los del cliente. Si aún falta un campo, el cobro se rechaza con `INVALID_REQUEST`.

### React Native

El paquete cifra con `crypto.getRandomValues`, que React Native no trae. Haz una de estas:

```typescript theme={null}
// Opción 1: polyfill una vez, al inicio de la entrada de tu app
import "react-native-get-random-values";

// Opción 2: pasa expo-crypto como fuente aleatoria
import * as Crypto from "expo-crypto";

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

Sin ninguna de las dos, el cobro falla antes de enviar nada a PagoPlux.

## Código de un solo uso (OTP)

Las tarjetas Diners, Interdin y Discover piden un código que el banco envía al titular por SMS o email:

1. Fire spark cobra la tarjeta y PagoPlux responde que se necesita un OTP.
2. El adaptador pide el código con `ui.input` (etiqueta `otpLabel`).
3. Vuelve a enviar la misma tarjeta cifrada con el código. El titular no vuelve a escribir la tarjeta.
4. Un código incorrecto se puede volver a escribir hasta **3 veces** en total. Después, el tender termina `FAILED` con `INVALID_PIN`.

## 3-D Secure

Cuando el banco del titular lo exige, PagoPlux responde con un desafío del banco en vez de cobrar:

1. El adaptador lo muestra con `ui.challenge` de tu UI de pagos (ver [Desafíos del banco](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md#desafíos-del-banco-3-d-secure)). 3DS v1 envía un formulario al banco; 3DS v2 abre la URL del banco.
2. El titular aprueba el pago en la página del banco.
3. El banco envía el navegador a Fire spark, que confirma el pago con PagoPlux y registra el tender `PAID` o `FAILED`.
4. El adaptador lee ese resultado y lo devuelve.

Si tu UI de pagos no tiene `challenge`, el tender termina `FAILED` con `INVALID_REQUEST` y no se cobra nada. Si el cliente cierra el desafío antes de que el banco responda, el tender termina `FAILED` con `AMBIGUOUS` y queda marcado para revisión: revisa el dashboard de PagoPlux.

## Tarjetas guardadas

El cliente puede guardar su tarjeta en PagoPlux y pagar con ella después sin volver a escribirla. PagoPlux tokeniza la tarjeta (API de Registro de Tarjeta); Fire spark guarda solo una referencia cifrada al token, la marca, los últimos 4 dígitos y el vencimiento. El token nunca llega al canal.

### Activarlas

En **Connection Settings** del pago PagoPlux:

| Campo | Clave | Por defecto | Notas |
| - | - | - | - |
| Tarjetas guardadas | `saved_cards.enabled` | Apagado | Apagado, guardar una tarjeta y pagar con una guardada responden `SAVED_CARDS_DISABLED`. Eliminar una tarjeta siempre funciona |
| Máximo de tarjetas por cliente | `saved_cards.max_per_customer` | `5` | De 1 a 10 tarjetas activas por cliente. Bajarlo no borra tarjetas: quien quede sobre el límite elimina una antes de guardar otra |

Guardar una tarjeta necesita un cliente con sesión en el storefront. Al registrarla, PagoPlux autoriza un monto mínimo para validar la tarjeta y lo reversa de inmediato: Fire spark no cobra ni reversa nada por la tokenización.

### Guardar y pagar

Cuando el pago tiene las tarjetas guardadas activas, el collector recibe `canSaveCard: true`. Muestra una casilla "Guardar tarjeta" y devuelve `saveCard: true` si el cliente la marca. El adaptador:

1. Guarda la tarjeta con la misma tarjeta cifrada. El OTP o el 3-D Secure de la tarjeta se piden aquí si el banco los exige.
2. Cobra el tender con la tarjeta guardada, con las cuotas elegidas.

| Situación | Resultado |
| - | - |
| Pagado | `PAID`, y `metadata.provider.saved_card` es `{ saved: true, id, brand, last4 }` |
| El cliente ya tiene el máximo, el pago tiene las tarjetas guardadas apagadas o no hay sesión | Se cobra igual sin guardar la tarjeta. `metadata.provider.saved_card` es `{ saved: false, reason }` |
| El banco rechaza la tarjeta al guardarla, el OTP fue incorrecto 3 veces o el 3-D Secure falló | `FAILED`, sin cobro |
| La tarjeta se guardó pero el cobro con ella se rechazó | `FAILED` con `CARD_DECLINED`. La tarjeta queda guardada |

Un cobro con tarjeta guardada se anula igual que cualquier cobro de PagoPlux (ver [Reembolsos](#reembolsos)).

### Solo guardar

Para una pantalla de "mis tarjetas", sin orden ni cobro:

```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 para el OTP, challenge para 3-D Secure
  collector // el mismo formulario; recibe amount 0
});

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

| Resultado | Qué hacer |
| - | - |
| `REGISTERED` | `card` trae `id`, `brand`, `last4`, `expiry_month`, `expiry_year` |
| `CANCELLED` | El cliente cerró el formulario, la pregunta del OTP o el desafío |
| `FAILED` + `SAVED_CARDS_DISABLED` | El comercio tiene las tarjetas guardadas apagadas. Oculta la opción |
| `FAILED` + `SAVED_CARDS_LIMIT` | El cliente ya tiene el máximo. Pídele que elimine una |
| `FAILED` + `CARD_DECLINED` | El banco rechazó la tarjeta |
| `FAILED` + `INVALID_PIN` | El OTP fue incorrecto 3 veces |
| `FAILED` + `UNAUTHENTICATED` | No hay cliente con sesión |
| `FAILED` + `AMBIGUOUS` | No hubo respuesta del banco o de PagoPlux. Lista las tarjetas para revisar |

### Listar y eliminar

| Endpoint | Qué hace |
| - | - |
| `GET /api/storefront/v1/saved-cards` | Tarjetas activas del cliente con sesión: `id`, `brand`, `last4`, `expiry_month`, `expiry_year`, `provider` |
| `POST /api/storefront/v1/saved-cards/{card_id}/revoke` | Elimina la tarjeta en PagoPlux y en Fire spark y libera el cupo |

## Cuotas

Activa `installments` en la configuración del pago (`enabled` y `options`) para ofrecer pagos diferidos. El adaptador pasa las opciones a tu formulario como `installmentOptions`; devuelve la cantidad elegida en `installments` e `interests` para diferido con intereses. El máximo es 48 meses. Las tarjetas de débito siempre son pago corriente (`0`).

## Montos e impuestos

Fire spark calcula los montos en el servidor: la parte gravada de las líneas de la orden se prorratea al monto del tender y se envía como monto con IVA, el resto como monto sin IVA. Ambos suman el monto del tender. El dispositivo nunca envía un monto.

## Endpoint del storefront

El adaptador lo llama con la operación de servidor del pago. Usa la sesión del storefront.

| Endpoint | Qué hace |
| - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/charge` | Cobra la tarjeta cifrada del intento de pago actual, con el OTP cuando PagoPlux lo pidió. Devuelve el resultado (`PAID`, `FAILED`, `PENDING`, `OTP_REQUIRED` o `THREE_DS_REQUIRED` con el `challenge` del banco). El monto sale del tender, nunca de la solicitud |
| `POST /api/storefront/v1/payments/{payment_id}/operations/encryption_key` | Llave pública con la que se cifra la tarjeta: la de la tienda de la orden, si no la de los Connection Settings |
| `POST /api/storefront/v1/payments/{payment_id}/operations/three_ds_result` | Después de un desafío 3-D Secure: el estado del tender y el resultado que Fire spark guardó cuando el banco devolvió al cliente |
| `GET /api/webhooks/payments/pagoplux/3ds-return/{ref}` | A donde el banco envía al cliente después del desafío (público, `ref` firmado por Fire spark). Nunca lo llamas |
| `POST /api/storefront/v1/payments/{payment_id}/operations/register_card` | Guarda la tarjeta cifrada del cliente con sesión. Devuelve `REGISTERED` con la tarjeta, `OTP_REQUIRED`, `OTP_INVALID`, `THREE_DS_REQUIRED` con el `challenge` y un `registration_ref`, o `FAILED`. Nunca devuelve el token |
| `POST /api/storefront/v1/payments/{payment_id}/operations/register_card_result` | Después del desafío 3-D Secure de un registro: `PENDING`, `REGISTERED` con la tarjeta, o `FAILED` |
| `POST /api/storefront/v1/payments/{payment_id}/operations/charge_with_token` | Cobra el intento de pago actual con una tarjeta guardada (`card_ref`, `confirmed_total`, `installments`, `interests`) |
| `GET /api/webhooks/payments/pagoplux/card-3ds-return/{ref}` | A donde el banco envía al cliente después del desafío de un registro (público, `ref` firmado por Fire spark). Nunca lo llamas |

## Qué ve el cliente

Tu formulario de tarjeta y, cuando el banco lo exige, la pregunta del OTP o el desafío del banco de tu UI de pagos. Un tender pagado guarda `details` con la marca, los últimos 4 dígitos, el código de autorización y las cuotas cuando son más de una. La metadata del resultado incluye `attempt_reference`, `payment` (`provider_transaction_id`, `authorization_code`, `brand`, `card_type`, `last4`, `acquirer`) y `provider` (`code`, `transaction_id`, `token`, `date`, `amount`). Cuando el cliente pidió guardar la tarjeta, `provider.saved_card` dice si se guardó. No hay voucher.

## Tiempos y resultados desconocidos

* Un intento dura hasta 10 minutos (formulario, emisor y OTP). Nunca se reintenta solo: la API de Pago no tiene llave de idempotencia, así que un reintento podría cobrar dos veces.
* Si PagoPlux no responde en 45 segundos, o responde que el pago está pendiente, el tender termina `FAILED` con `AMBIGUOUS` y `needs_review`. La API de Pago no tiene consulta de estado, así que alguien debe revisar la transacción en el dashboard de PagoPlux.

## Reembolsos

Fire Spark anula un cobro pagado de PagoPlux en el servidor cuando llamas `order.cancel()` u `order.refund()`, con el `secret_key` del pago (API de reversos por id de transacción de PagoPlux). El dispositivo no hace nada: el adaptador reporta el reverso como `server`.

* **Solo la transacción completa.** Una devolución parcial no se envía a PagoPlux: la operación del ledger falla y la devuelves a mano en el dashboard de PagoPlux.
* **Solo el mismo día.** PagoPlux anula una transacción solo antes de su corte diario (17h30 o medianoche, según el comercio). Después, la anulación falla con "fecha no permitida": devuélvela a mano en el dashboard de PagoPlux.
* **Idempotente.** Anular de nuevo responde "ya fue anulada previamente" y cuenta como hecho.
* Un intento que nunca se cobró solo se descarta; si PagoPlux dice que nunca se autorizó, no hay nada que reversar.

Un reverso fallido queda en el ledger de pagos de la orden con el motivo de PagoPlux, para que un operador lo termine.

## Errores comunes

| Código Spark | Código PagoPlux | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | `2` (rechazo, o "Tarjeta Bloqueada") | Pide otra tarjeta u otro método |
| `INSUFFICIENT_FUNDS` | `2` ("Cupo no disponible") | Pide otra tarjeta u otro método |
| `EXPIRED_CARD` | `2` ("Tarjeta Expirada") | Pide otra tarjeta |
| `INVALID_CARD` | `2` (número de tarjeta inválido) | Revisa el número de tarjeta e intenta de nuevo |
| `INVALID_PIN` | `102` | El OTP fue incorrecto 3 veces. Empieza de nuevo |
| `INVALID_CREDENTIALS` | `1`, `302`, HTTP 401/403 | Revisa `client_id`, `secret_key`, `establishment_id` y su entorno en Connection Settings |
| `INVALID_REQUEST` | `301`, `303`, faltan datos del comprador | Revisa los planes de cuotas con PagoPlux, o envía los datos del comprador que faltan |
| `LIMIT_EXCEEDED` | `304` | Se superó el monto o la cantidad diaria o mensual. Pide otro método |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429 | Intenta de nuevo con un nuevo intento |
| `CANCELLED_BY_USER` | — | El cliente cerró el formulario de tarjeta |
| `AMBIGUOUS` | `103`, `2` ("ya fue procesada"), sin respuesta, respuesta 2xx en un formato desconocido | Marcado para revisión. Revisa la transacción en el dashboard de PagoPlux |

El paquete exporta el mapa de códigos de PagoPlux como `pagopluxErrors`. Ver [Errores de pago](https://firespark.cloud/docs/es/guides/payments/errors.md).

## Probar en sandbox

Define `provider_environment` en `sandbox` (o usa un comercio de sandbox). Tarjetas de prueba de PagoPlux:

| Tarjeta | Número | Resultado |
| - | - | - |
| VISA | `4540639936908783` | Pagado |
| Diners | `36417200103608` | Pide OTP `123456`, luego pagado |
| Discover | `6011761603370843` | Pide OTP `123456`, luego pagado |
| VISA | `4540633357674263` | Rechazado: "Cupo no disponible" (`INSUFFICIENT_FUNDS`) |

Usa vencimiento `04/29` y CVV `123` (`1234` para Amex), y una cédula ecuatoriana válida como `document_number`: el sandbox rechaza las inventadas. Si tu comercio de sandbox tiene 3-D Secure activo, VISA, Mastercard y Amex piden el desafío del banco; la página de prueba muestra el código. Las mismas tarjetas sirven para guardar una tarjeta.

## Compatibilidad

| `@fire-spark/payments-pagoplux-card` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.13.1 (beta) | PagoPlux API de Pago 1.2 | Misma versión |
| 0.14.0 (beta) | PagoPlux API de Pago 1.3 (3-D Secure) | Misma versión |
| 0.18.0 (beta) | PagoPlux API de Pago 1.3 y API de Registro de Tarjeta 1.2 (tarjetas guardadas) | Misma versión |


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