How it works
- The adapter asks Fire spark to open a session (
create_session). Fire spark calls PlacetoPay with the site login, a signedtranKey, the tender amount, and the attempt reference as the payment reference, and answers the WebCheckout URL (processUrl). The session lives 15 minutes. - Your template’s bridge opens WebCheckout in a browser tab (a popup, a new tab, or a full-page redirect).
- The customer pays. PlacetoPay sends the browser back to your
returnUrl, withplacetopay_reference(the attempt reference) added by Fire spark. - The adapter asks Fire spark for the session status (
status). The tender isPAIDonly when PlacetoPay approved a transaction for this attempt, amount, and currency. The browser’s return is never taken as the result. - 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 (
localhostworks for development). Card payments are web only. - A
returnUrlpage that tells the bridge the customer is back (see The bridge).
Activate it
- In the dashboard, open your merchant, go to Payments, and create a payment with the provider PlacetoPay and the method
CARD. - In Connection Settings, fill in:
- Optional: set
provider_environmentto forcesandboxorproduction. 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:Use it in the SDK
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.
postMessage from the return page:
returnUrl page tells the opener the customer is back, or, after a full-page redirect, goes back to your checkout:
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 sessiontotal 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 (unlessskipResult), 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
FAILEDwithAMBIGUOUSandneeds_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 callorder.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.
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, withprovider_environment set to sandbox (or use a sandbox merchant). Fire spark then calls https://checkout-test.placetopay.ec.
- Pay a card tender from your web channel, with the test cards PlacetoPay gives you.
- Try closing the tab before paying: the session is cancelled and the tender ends
CANCELLED_BY_USER. - Review the sessions in the PlacetoPay sandbox console.
localhost during development.