> 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 a hosted session URL in the `actions` array. Your frontend then sends the payer to that hosted flow as a full-page redirect.

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: Hosted session URL
  Frontend->>Payer: Open redirect checkout
  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
* Redirect integration option 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 unique session `referenceId`
* a unique `paymentRequest.referenceId`
* 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
* sending the customer to the hosted checkout redirect URL
* 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"
    },
    "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).

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

## 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"
    }
  ]
}
```

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

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

## 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 the underlying payment request
* Treat the hosted session URL in `actions` as the only supported payer entry point
* 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)
* [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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/sessions/checkout-session.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.