# Upgrade from Frames for web

Follow this guide to upgrade your Frames for web integration to Flow.

---

## Before you start

Create a [public key and a secret key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) in the [Dashboard](https://dashboard.checkout.com), with the following key scopes:

- Public key – `payment-sessions:pay` and `vault-tokenization`
- Secret key – `payment-sessions`

[Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) to receive notifications for [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway).

---

## Remove existing Frames code

To prepare for the upgrade to Flow, remove all Frames code from your client-side and server-side integrations.

### Remove Frames library `Client side`

If you included the Frames JavaScript library in your HTML, remove the Frames `<script>` tag:

```html
<script src="https://cdn.checkout.com/js/framesv2.min.js"></script>
```

### Remove Frames initialization `Client side`

Remove any JavaScript code where you initialize Frames. For example:

```javascript
Frames.init("PUBLIC_KEY");

Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, onValidationChanged);
Frames.addEventHandler(Frames.Events.CARD_TOKENIZED, onCardTokenized);
```

### Remove Frames form `Client side`

Delete any HTML related to Frames. For example, the card input form:

```html
<form id="payment-form">
  <div id="card-frame"></div>
  <button id="pay-button">Pay</button>
</form>
```

### Remove payment logic `Server side`

Remove all server-side API calls to the following endpoints:

**Production**

`POST` `https://api.checkout.com/payments`

**Sandbox**

`POST` `https://api.sandbox.checkout.com/payments`

---

## Create a Flow Payment Session `Server side`

Update your server to create a `PaymentSession` for the Flow integration.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payment-sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions`

### Request example

```json
{
  "amount": 1000,
  "currency": "GBP",
  "reference": "ORD-123A",
  "display_name": "Online shop",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```
### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}
```

---

## Initialize and mount Flow `Client side`

### Add the Flow library

Include the Flow library in the project:

```html
<script src="https://checkout-web-components.checkout.com/index.js"></script>
```

### Initialize Flow

Configure Flow with your public key and the payment session data returned from the server:

```javascript
const publicKey = 'PUBLIC_KEY';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox', // Use 'production' for Production environment
});
```

### Mount Flow

Add the Flow component to a container in your HTML:

```html
<div id="flow-container"></div>
```

In your JavaScript, create and mount the component:

```javascript
const flowComponent = checkout.create('flow');
flowComponent.mount('#flow-container');
```

---

## Handle payment responses

You can use Flow to handle payment methods that require a redirect (asynchronous payments) and those that do not (synchronous payments).

### Asynchronous payments

Depending on the payment outcome, some payment methods and 3D Secure (3DS) authentication flows redirect the customer to a success or failure URL on your website.

We send a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process.

For payments submitted with Flow, the `PaymentSession` ID is returned in the webhook payload's `data.metadata.cko_payment_session_id` field.

Optionally, you can retrieve the payment result from your server by performing a [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) request using the `cko-payment-id` in the URL. For example:

```
https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd
```

### Synchronous payments

Payment methods that do not require a redirect initiate an `onPaymentCompleted` event when the payment is successfully completed.
You can use this to notify the customer of the payment's status.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process.

```javascript
const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  onPaymentCompleted: async (_self, paymentResponse) => {
    // Handle synchronous payment completion
    console.log('Payment successful', paymentResponse);
  },
});
```
---

## Customize the payment flow logic

Flow sends real-time card metadata events, which you can integrate with third-party systems to determine how to handle payment requests.

You can use these events to customize the payment session if you have more complex processes. For example, you can conduct a pre-payment risk check based on a card's issuing country and then decide to proceed with 3DS authentication or cancel the payment.

> **Information**
>
> For more information, see [Customize your payment process](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-payment-process.md).

---

## Test the Flow integration

Use [test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md) to simulate different payment flows to ensure your integration is set up correctly and behaving as expected.

> **Information**
>
> Ensure that you test every payment method that you plan to offer to your customers.

To check the status of a payment:

1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Go to _Payments_ > _Processing_ > _All payments_.

---

## Adjust Content Security Policy

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:

```
connect-src https://*.checkout.com;
frame-src https://*.checkout.com;
script-src https://*.checkout.com;
img-src https://*.checkout.com;
```

---

## Next steps

**[Customize your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md)**

Learn how to customize your Flow integration.

**[Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference.md)**

See the configuration options and error handling steps for Flow.

**[Tokenize credentials](https://www.checkout.com/docs/payments/store-and-manage-credentials/tokenize-credentials.md)**

Securely collect and tokenize credentials with Flow.