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

# PlacetoPay

> Charge cards on the web in Ecuador with PlacetoPay WebCheckout and @fire-spark/payments-placetopay-checkout.

> [!WARNING]
>
> **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.

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

| Method | Channel | What the customer does |
| - | - | - |
| Card (`CARD`) | Web | Pays in the PlacetoPay WebCheckout page opened in a browser tab, then comes back to your site |

## 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](#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](#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:

| Field | Key | Secret | Notes |
| - | - | - | - |
| Login | `placetopay_login` | No | Login of your PlacetoPay site (up to 32 characters) |
| Secret key | `secret_key` | Yes | Secret key of your PlacetoPay site. Signs every PlacetoPay request (`tranKey`). Stays in the Fire spark API; never sent to channels |

3. Optional: set `provider_environment` to force `sandbox` or `production`. Without it, the environment follows the merchant's.

| Environment | PlacetoPay host |
| - | - |
| `sandbox` | `https://checkout-test.placetopay.ec` |
| `production` | `https://checkout.placetopay.ec` |

There are no per-store settings.

### Notification

In your PlacetoPay site settings, set the notification URL to:

```
https://<Fire spark API>/api/webhooks/payments/place_to_pay
```

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

```bash theme={null}
pnpm add @fire-spark/payments-placetopay-checkout
```

```typescript theme={null}
import { placetopayCheckoutPayments } from "@fire-spark/payments-placetopay-checkout";

order.setPaymentAdapters([
  placetopayCheckoutPayments({
    bridge, // your template's PlacetopayRedirectBridge, see below
    returnUrl: "https://shop.example.com/placetopay/return"
  })
]);

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

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](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md#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](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md).

### Options

| Option | Required | Description |
| - | - | - |
| `bridge` | Yes | Opens WebCheckout in a browser tab and reports the return (`PlacetopayRedirectBridge`) |
| `returnUrl` | Yes | https page PlacetoPay sends the customer back to ("Volver al comercio"). Up to 255 characters |
| `cancelUrl` | No | https page for "No deseo continuar". Default: PlacetoPay's own page |
| `locale` | No | `es_EC` (default), `en_US`, or any `xx_YY` locale PlacetoPay supports. Language of WebCheckout |
| `skipResult` | No | `true` skips PlacetoPay's result page and returns straight to `returnUrl` |

### The bridge

The bridge is your web template's code. The package defines its shape (`PlacetopayRedirectBridge`), not its UI:

| Member | Description |
| - | - |
| `open({ url, attemptReference, returnUrl, signal })` | Opens `url` in a browser tab. Resolves `{ type: "returned" }` when the tab comes back to `returnUrl`, `{ type: "cancelled" }` if the customer closed it, or `{ type: "redirected" }` when it navigated the whole page away. Close the tab and resolve `cancelled` when `signal` aborts |

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.

> [!NOTE]
>
> 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:

```typescript theme={null}
import type {
  PlacetopayRedirectBridge,
  PlacetopayRedirectOutcome
} from "@fire-spark/payments-placetopay-checkout";

const MESSAGE = "placetopay:return";

export const bridge: PlacetopayRedirectBridge = {
  open: ({ url, attemptReference, signal }) =>
    new Promise(resolve => {
      const tab = window.open(url, "_blank");
      if (!tab) {
        // Popup blocked: fall back to a full-page redirect.
        resolve({ type: "redirected" });
        window.location.assign(url);
        return;
      }
      const finish = (outcome: PlacetopayRedirectOutcome) => {
        window.removeEventListener("message", onMessage);
        clearInterval(closed);
        signal.removeEventListener("abort", onAbort);
        resolve(outcome);
      };
      const onMessage = (event: MessageEvent) => {
        if (event.origin !== window.location.origin) return;
        if (event.data?.type !== MESSAGE) return;
        if (event.data.reference !== attemptReference) return;
        tab.close();
        finish({ type: "returned" });
      };
      const onAbort = () => {
        tab.close();
        finish({ type: "cancelled" });
      };
      const closed = setInterval(() => {
        if (tab.closed) finish({ type: "cancelled" });
      }, 1000);
      window.addEventListener("message", onMessage);
      signal.addEventListener("abort", onAbort);
    })
};
```

The `returnUrl` page tells the opener the customer is back, or, after a full-page redirect, goes back to your checkout:

```typescript theme={null}
import { parsePlacetopayReturn } from "@fire-spark/payments-placetopay-checkout";

const reference = parsePlacetopayReturn(window.location.href);

if (reference && window.opener) {
  // Popup or new tab: tell the checkout and close.
  window.opener.postMessage(
    { type: "placetopay:return", reference },
    window.location.origin
  );
  window.close();
} else if (reference) {
  // Full-page redirect: go back to your checkout, which resumes the
  // pending tender and reads the session status.
  window.location.replace("/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.

| Endpoint | Method | What it does |
| - | - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/create_session` | `CARD` | Opens the WebCheckout session for the current payment attempt and returns `request_id`, `process_url`, and `expiration`. Takes `return_url`, `cancel_url`, `locale`, `skip_result`, and `user_agent`; both URLs must be https (or `localhost`). The amount comes from the tender, never from the request |
| `POST /api/storefront/v1/payments/{payment_id}/operations/status` | `CARD` | Reads the session (`request_id`) and returns the outcome (`PAID`, `FAILED`, or `PENDING`) |
| `POST /api/storefront/v1/payments/{payment_id}/operations/cancel_session` | `CARD` | Cancels a session nobody paid (`request_id`). Answers the paid outcome instead if the session was approved |

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

| Spark code | PlacetoPay cause | What to do |
| - | - | - |
| `CARD_DECLINED` | Session rejected, reason `XN`, or a reason Fire spark does not know | Ask for another card or method |
| `CANCELLED_BY_USER` | The customer closed the tab, or reason `?C`, `MC` | Offer the method again |
| `AMBIGUOUS` | No answer, reason `PT`, a session accepted without a request id, or a session that does not match the tender | Flagged for review (`needs_review`). Check the session in the PlacetoPay console |
| `INVALID_CREDENTIALS` | Login rejected (HTTP 401), reason `401`, or `103` (the server clock is more than 5 minutes off PlacetoPay's) | Check `placetopay_login`, `secret_key`, and `provider_environment` in Connection Settings |
| `INVALID_REQUEST` | `returnUrl` or `cancelUrl` not https, `request_not_valid`, PlacetoPay refused the session | Fix the URLs and try again |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429, `transaction_request_error` | Try again with a new attempt |

The package exports the PlacetoPay code map as `placetopayErrors`. Codes it does not know fall back to `CARD_DECLINED`. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md).

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

| `@fire-spark/payments-placetopay-checkout` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.17.0 (beta) | PlacetoPay WebCheckout (Ecuador) | Same version |


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