Skip to main content
Beta. @fire-spark/payments-placetopay-checkout is in beta since SDK 0.17.0. Card payments work only on the web, PlacetoPay reverses only whole transactions by API (no partial refunds), and the PlacetoPay reason code catalog is still pending. Test in the PlacetoPay sandbox before going live.
PlacetoPay runs WebCheckout, a hosted payment page. Fire spark opens a WebCheckout session for the tender, your web template sends the customer to it, and Fire spark asks PlacetoPay for the session status when the customer comes back. The PlacetoPay secret key never reaches the channel: Fire spark signs every PlacetoPay call with it on the server. The card is typed in PlacetoPay’s own page and never reaches your channel or Fire spark.

How it works

  1. The adapter asks Fire spark to open a session (create_session). Fire spark calls PlacetoPay with the site login, a signed tranKey, the tender amount, and the attempt reference as the payment reference, and answers the WebCheckout URL (processUrl). The session lives 15 minutes.
  2. Your template’s bridge opens WebCheckout in a browser tab (a popup, a new tab, or a full-page redirect).
  3. The customer pays. PlacetoPay sends the browser back to your returnUrl, with placetopay_reference (the attempt reference) added by Fire spark.
  4. The adapter asks Fire spark for the session status (status). The tender is PAID only when PlacetoPay approved a transaction for this attempt, amount, and currency. The browser’s return is never taken as the result.
  5. If the customer closes the tab, or the attempt times out, Fire spark cancels the session (cancel_session) so it cannot be paid later. It reads the session first and never cancels one that was paid.

Requirements

  • A PlacetoPay WebCheckout site for Ecuador, with its login and secret key. Sandbox and production use separate sites (see Test).
  • A web template served over https (localhost works for development). Card payments are web only.
  • A returnUrl page that tells the bridge the customer is back (see The bridge).

Activate it

  1. In the dashboard, open your merchant, go to Payments, and create a payment with the provider PlacetoPay and the method CARD.
  2. In Connection Settings, fill in:
  1. Optional: set provider_environment to force sandbox or production. Without it, the environment follows the merchant’s.
There are no per-store settings.

Notification

In your PlacetoPay site settings, set the notification URL to:
Fire spark checks the signature with your secret key and queries the session from PlacetoPay again before changing the payment: the notice only triggers the query. A payment is confirmed even if the customer never came back to your store.

Use it in the SDK

Progress messages (“Confirmando pago…”) use message in order.setPaymentUI, and the session id is kept in your payment storage for a full-page redirect. See Terminal prompts and storage. payIntent({ payment }) places one real tender. To split PlacetoPay with another method, call order.setTenders with an allocation and then payIntent(). See Use payments in the SDK.

Options

The bridge

The bridge is your web template’s code. The package defines its shape (PlacetopayRedirectBridge), not its UI: The return page does not need to forward anything except “returned”: the result always comes from the session status that Fire spark reads from PlacetoPay. The package exports parsePlacetopayReturn(url), which reads the attempt reference (placetopay_reference) from a return URL, or null if it is not one. Use it to ignore returns of other attempts.
The code below is an example of your template’s own code, not part of the package. Adapt it to your router and UI.
Popup or new tab, with postMessage from the return page:
The returnUrl page tells the opener the customer is back, or, after a full-page redirect, goes back to your checkout:
After a redirected outcome the tender stays PENDING. When the adapter queries it, it reads the session id from the pending result (or from your payment storage) and asks Fire spark for the status. Give the order a payment storage that survives the page load. If you set cancelUrl, that page can resolve cancelled instead of returned, so Fire spark cancels the session right away. Resolving returned there also works: the status decides.

Amounts and taxes

Fire spark computes the amount on the server, in dollars with two decimals: the session total is the tender amount. When the order has taxed lines, Fire spark also sends the VAT (valueAddedTax) with its taxed base, both prorated to the tender amount. The device never sends an amount. Fire spark also sends the buyer from the order customer when it has them (name, surname, email, phone, and ID number), so PlacetoPay pre-fills its form. The document type follows the ID number: CI (10 digits), RUC (13 digits), otherwise PPN (passport). The customer’s IP address and browser (User-Agent) come from the storefront request.

Storefront endpoints

The adapter calls these through the payment server operations. They use the storefront session.

What the customer sees

WebCheckout in a browser tab, PlacetoPay’s result page (unless skipResult), then your returnUrl page. Meanwhile your checkout shows “Confirmando pago…”. A paid tender records details with the card brand, last 4 digits, and authorization code. The result metadata includes attempt_reference, payment (provider_transaction_id, authorization_code, reference, brand, last4), and provider (request_id, internal_reference, session_status, reason, franchise, payment_method, issuer_name, receipt). There is no voucher.

Timeouts and unknown results

  • One attempt lasts up to 15 minutes, the life of the session. It is not retried automatically: a retry is a new session.
  • A transaction PlacetoPay still has pending stays PENDING, and the adapter reads its status every 5 seconds.
  • When the attempt times out, Fire spark cancels the session if nobody paid it. Anything else stays for review.
  • If PlacetoPay does not answer within 30 seconds, the tender ends FAILED with AMBIGUOUS and needs_review. Check the session in the PlacetoPay console.
  • PlacetoPay’s notification confirms sessions the channel never read again, for example when the store page was closed during the payment. PlacetoPay sends it only once.

Refunds

Fire Spark reverses a paid PlacetoPay charge on the server when you call order.cancel() or order.refund(), with the site’s credentials (PlacetoPay reverse by internalReference). The device does nothing: the adapter reports the reversal as server.
  • Whole transaction only. A partial refund is not sent to PlacetoPay: the ledger operation fails and you refund it by hand in the PlacetoPay console.
  • An attempt that was never charged is just discarded.
A failed reversal stays in the order’s payment ledger with PlacetoPay’s message, for an operator to finish.

Common errors

The package exports the PlacetoPay code map as placetopayErrors. Codes it does not know fall back to CARD_DECLINED. See Payment errors.

Test

Ask PlacetoPay for a sandbox site and paste its login and secret key in Connection Settings, with provider_environment set to sandbox (or use a sandbox merchant). Fire spark then calls https://checkout-test.placetopay.ec.
  1. Pay a card tender from your web channel, with the test cards PlacetoPay gives you.
  2. Try closing the tab before paying: the session is cancelled and the tender ends CANCELLED_BY_USER.
  3. Review the sessions in the PlacetoPay sandbox console.
Card payments work from localhost during development.

Compatibility