> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/sessions/checkout-session.md).

# Checkout Session Integration

Use a checkout session when you want Plexo to host the payment step for your customer and create the payment as part of that hosted flow.

Use this guide to create the session, launch the hosted checkout, and handle the result in your application.

## What a checkout session is

A checkout session is a short-lived payment session created with `POST /v1/sessions` and `"type": "checkout"`.

Your backend creates the session. Plexo returns full-page and embedded checkout URLs in the `actions` array. Your frontend selects the entry point that matches your integration.

In practical terms, the flow looks like this:

```mermaid
sequenceDiagram
  participant Backend as Your backend
  participant Frontend as Your frontend
  participant Payer as Payer
  participant Plexo as Plexo hosted checkout

  Backend->>Plexo: POST /v1/sessions (type=checkout)
  Plexo-->>Backend: SessionDto with actions
  Backend-->>Frontend: REDIRECT and EMBEDDED checkout URLs
  Frontend->>Payer: Open the selected checkout entry point
  Payer->>Plexo: Enter payment details
  Plexo-->>Frontend: Redirect result
  Plexo-->>Backend: Payment callback
```

## Features

* Hosted payment collection, so your own backend does not need to handle raw card entry
* Full-page redirect and embedded iframe integration options returned in `actions`
* Support for callback notifications after the hosted flow progresses or finishes
* Support for browser redirects after success or cancellation
* Support for saved-instrument checkout by sending an existing `token`
* Support for fixed-amount and flexible-amount checkout configurations
* Session listing for audit and troubleshooting with `GET /v1/sessions`

## When teams usually choose this flow

This flow is usually the right choice when:

* you want a faster integration than building your own payment form
* you want Plexo to host the customer-facing payment UI
* you want to keep card entry inside a Plexo-controlled experience
* your product needs a clear redirect checkout step in the user journey

## What your application needs before starting

You need:

* a merchant ID that belongs to your API credentials
* Basic authentication credentials for the target environment
* a session `referenceId` that identifies the checkout session
* a `paymentRequest.referenceId` that identifies the payment
* a unique `paymentRequest.invoiceNumber`
* redirect URLs if you want the customer sent back to your product in the browser
* a callback URL if your backend needs asynchronous payment updates

## What your application is responsible for

Your application is responsible for:

* deciding when to create the checkout session
* providing business identifiers such as merchant ID, reference IDs, and invoice number
* selecting the `REDIRECT` or `EMBEDDED` action for the customer experience
* implementing the iframe handshake and event handler when using `EMBEDDED`
* handling redirects back to your product
* handling callback notifications in your backend
* reconciling the final payment outcome in your own domain model

Plexo is responsible for:

* hosting the secure payment form
* collecting payment details inside the hosted flow
* creating the payment within the checkout flow
* returning the session links your frontend should use

## Step 1: Create the checkout session

Create the session from your backend.

```http
POST /v1/sessions
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "checkout-session-1001",
  "type": "checkout",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentRequest": {
    "referenceId": "payment-1001",
    "invoiceNumber": "INV-1001",
    "installments": 1,
    "amount": {
      "total": 100.00,
      "currency": "UYU"
    },
    "expirationMinutes": 1440,
    "metadata": {
      "orderId": "1001"
    }
  },
  "browserDetails": {
    "ipAddress": "203.0.113.10",
    "userAgent": "Mozilla/5.0"
  },
  "settings": {
    "paymentMethodTypes": ["card"],
    "checkout": {
      "disableThreeds": false
    },
    "callbacks": {
      "paymentCallbackUrl": "https://merchant.example.com/callbacks/payments"
    },
    "redirects": {
      "defaultUrl": "https://merchant.example.com/checkout/result",
      "cancelUrl": "https://merchant.example.com/checkout/cancel"
    }
  }
}
```

This request shows a common integration payload, not every available field. For the full request surface, see [SessionRequest](/rest-api/api-reference/models.md#sessionrequest), [SessionSettings](/rest-api/api-reference/models.md#sessionsettings), [CheckoutSettingsRequest](/rest-api/api-reference/models.md#checkoutsettingsrequest), and [CheckoutPaymentRequest](/rest-api/api-reference/models.md#checkoutpaymentrequest).

`referenceId` values have separate meanings in a checkout session:

* The session-level `referenceId` identifies the checkout session.
* `paymentRequest.referenceId` identifies the payment that Plexo creates from the session. When it is non-empty, Plexo uses this value as the created payment's `referenceId`.
* When non-empty, `paymentRequest.referenceId` must be unique for the combination of `clientId` and `merchantId`. Plexo rejects session creation when the value is already used within that scope.
* Use the same reference for both objects when you want one business reference to identify the session and its payment. Otherwise, use `Payment.SessionId` to correlate the payment to its session.

### Important request details

* `paymentRequest` is required for checkout sessions
* `browserDetails` is optional, but recommended for fraud and browser-based authentication flows
* `token` can be sent when you want checkout to use an existing saved instrument
* `settings.checkout.amountMode` defaults to fixed behavior if you do not send it
* `settings.checkout.disableThreeds` defaults to `false`; when set to `true`, Plexo skips 3DS for payments created from that checkout session even if the merchant payment method has 3DS enabled
* when using flexible amounts, send `settings.checkout.flexibleAmount.allowedCurrencies`, and use `minAmount` and `maxAmount` when you want payer-entered bounds
* `paymentRequest.expirationMinutes` controls the payment-code lifetime for Abitab and Redpagos payments. It defaults to `1440` minutes (24 hours) when omitted and is ignored for other payment methods.
* Once Plexo assigns a payment to the session, the session status becomes `used` and the session cannot be used to create another payment. A cancelled session cannot be reused.

## Step 2: Open the hosted checkout

If session creation succeeds, Plexo returns a `SessionDto` with one or more hosted entry points in `actions`.

```json
{
  "id": "0d96b3f4d8f94c7bb6f5e8b6c7d8e9f0",
  "referenceId": "checkout-session-1001",
  "type": "checkout",
  "status": "pending",
  "expiresAt": "2026-03-30T15:00:00Z",
  "actions": [
    {
      "rel": "self",
      "href": "https://checkout.plexo.com.uy/0d96b3f4d8f94c7bb6f5e8b6c7d8e9f0?t={sessionToken}",
      "method": "REDIRECT"
    },
    {
      "rel": "self",
      "href": "https://checkout.plexo.com.uy/e/0d96b3f4d8f94c7bb6f5e8b6c7d8e9f0?t={sessionToken}",
      "method": "EMBEDDED"
    }
  ]
}
```

The public session `id` is a compact GUID string: 32 lowercase hexadecimal characters without hyphens. The created payment's `sessionId` uses the same string format and matches the session's `id`. The session's nullable `paymentId` identifies the associated payment and matches its `id`. See [SessionDto](/rest-api/api-reference/models.md#sessiondto) and [consumer identifier handling](/rest-api/api-reference/models.md#paymentdto).

Use the action with `method = REDIRECT` when the payer should leave your page and complete payment in a full-page hosted flow.

Use the action with `method = EMBEDDED` when checkout should remain inside your e-commerce page. Embedded checkout requires an iframe handshake and lifecycle-event handler; follow the [Embedded Checkout Integration](/rest-api/sessions/embedded-checkout.md) guide.

The important rule is simple: use the URL Plexo returns. Do not build these URLs yourself.

## Step 3: Handle what happens after payment

There are two common integration channels after the payer interacts with the hosted checkout.

### Browser return

Use session redirects when your frontend or product experience needs the customer sent back to your application.

* `settings.redirects.defaultUrl` is the success destination
* `settings.redirects.cancelUrl` is the cancel destination

This is useful for user experience, but it should not be the only source of truth for your backend.

### Server-to-server updates

Use `settings.callbacks.paymentCallbackUrl` when your backend needs asynchronous updates about the payment result.

Checkout session callbacks use the same payment payload documented in [Callbacks](/rest-api/operations/callbacks.md#payment-callbacks).

This is the preferred place to reconcile business state, such as marking an order as paid, authorized, pending, or failed.

## Step 4: Continue with the normal payment lifecycle

Once the session has produced a payment, the rest of the flow follows the normal payments contract. That means captures, cancellations, and payment-state interpretation belong to the [Payment Processing Guide](/rest-api/payments/payment-processing.md).

To find the payment created from this session, use the payment reference from `paymentRequest.referenceId` when querying payments. Payment lookup uses the payment's `referenceId`, not the session-level `referenceId`. Include `clientId` when the payment lookup endpoint requires it.

## Step 5: Troubleshoot or audit sessions

Use `GET /v1/sessions` when you need to review sessions created by your API key.

```http
GET /v1/sessions?merchantId=12345&referenceId=checkout-session-1001&page=1&size=20
Authorization: Basic {credentials}
```

Supported filters are:

* `merchantId`
* `referenceId`
* `page`
* `size`
* `minDate` and `maxDate` together for a date-range filter

## Best Practices

* Use distinct `referenceId` values for the session and underlying payment request in other flows. For OCA Pay hosted selection, the payment uses the session's top-level `referenceId`; see [OCA Pay with Plexo Checkout](/rest-api/wallets/oca-pay/oca-pay-hosted-checkout.md).
* Treat the URLs returned in `actions` as the only supported payer entry points
* Prefer callbacks for backend reconciliation instead of relying only on browser redirects
* Do not store PAN or CVV in your own systems
* Think about redirects as customer navigation, and callbacks as backend truth

## Related Resources

* [Sessions](/rest-api/sessions/sessions.md)
* [Embedded Checkout Integration](/rest-api/sessions/embedded-checkout.md)
* [Payment Processing Guide](/rest-api/payments/payment-processing.md)
* [Callbacks](/rest-api/operations/callbacks.md)
* [Authentication](/rest-api/getting-started/authentication.md)
* [SessionDto](/rest-api/api-reference/models.md#sessiondto)
* [OCA Pay with Plexo Checkout (limited beta, top-level only)](/rest-api/wallets/oca-pay/oca-pay-hosted-checkout.md)