Skip to main content
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.

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

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:
  1. Optional: set installments to offer deferred payments (see 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. 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

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.
The OTP prompt uses your payment UI (input in order.setPaymentUI), and progress messages use message. See 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.

Options

The collector

collect(input) receives: It resolves with a PagopluxCardForm, or null if the customer cancelled (the tender ends FAILED with CANCELLED_BY_USER):
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:
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). 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: 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.
A payment with a saved card is voided like any PagoPlux payment (see Refunds).

Save only

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

List and delete

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.

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

The package exports the PagoPlux code map as pagopluxErrors. See Payment errors.

Test in sandbox

Set provider_environment to sandbox (or use a sandbox merchant). PagoPlux test cards: 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