> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paytring.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Checkout Integration

> Integrate Paytring Quick Checkout with your store.

# 🛠️ **Integration Guide**

This guide will help you seamlessly integrate **Paytring Quick Checkout** into your Shopify/Other store, replacing platform’s default checkout buttons & keeping the user experience smooth.

***

## 1️⃣ Add Paytring CDN scripts to `theme.liquid`

Paste these lines **inside** your `theme.liquid` file, ideally before the closing `</body>` tag:

```html theme={null}
<script src="https://cdn.paytring.com/js/quick/shopify/quick-iframe-shopify.v1.0.0.js" defer></script>
<script src="https://cdn.paytring.com/js/quick/shopify/quick-shopify.v1.0.0.js?env=prod&iframe=true" defer></script>
```

**Optional query parameters:**

| Parameter | Values                     | Purpose                                                     |
| :-------- | :------------------------- | :---------------------------------------------------------- |
| env       | `prod` \| `uat` \| `local` | Choose your environment                                     |
| iframe    | `true` \| `false`          | Whether to render checkout in an iframe                     |
| style     | `phone`                    | Apply preset button styling whether it's mobile view or not |

## 2️⃣ Create a Shopify App with required permissions

### ✅ Admin API access scopes (32 total)

```
read_cart_transforms, write_cart_transforms, read_discounts, write_order_edits,
read_order_edits, write_orders, read_orders, read_payment_customizations,
write_payment_customizations, write_payment_terms, read_payment_terms,
write_product_listings, read_product_listings, write_price_rules, read_price_rules,
write_products, read_products, write_script_tags, read_script_tags, write_shipping,
read_shipping, write_assigned_fulfillment_orders, read_assigned_fulfillment_orders,
write_third_party_fulfillment_orders, read_third_party_fulfillment_orders,
read_custom_fulfillment_services, write_returns, read_returns, read_inventory,
read_all_cart_transforms, read_customers, read_publications
```

### 🌐 Storefront API access scopes

```
unauthenticated_write_checkouts, unauthenticated_read_checkouts,
unauthenticated_write_customers, unauthenticated_read_customers,
unauthenticated_read_customer_tags, unauthenticated_read_product_listings,
unauthenticated_read_product_inventory, unauthenticated_read_product_pickup_locations,
unauthenticated_read_product_tags, unauthenticated_write_bulk_operations,
unauthenticated_read_bulk_operations
```

### 📦 **Step 2.1: Store and share app credentials**

Once the app is created, **securely store** the following four parameters:

| Parameter                     | Purpose                                                   |
| ----------------------------- | :-------------------------------------------------------- |
| `Admin API access token`      | Use your access token to request data from the Admin API  |
| `API key`                     | Public key for your Shopify app                           |
| `API secret key`              | Private secret used for app authentication                |
| `Storefront API access token` | Use your access token to request data from Storefront API |

✅ **After saving**, share these securely with the **Paytring team**
so they can complete the integration on your behalf.

***

## 3️⃣ Replace the default checkout button

### 🔍 Step 1: Locate your checkout buttons

Shopify usually has two main places with checkout buttons:

* **Main cart page**
  Files: `cart.liquid`, `cart-template.liquid`, or sections like `main-cart-footer.liquid`
* **Cart drawer / mini cart**
  Files: `cart-drawer.liquid`, `sections/cart-drawer.liquid`, `snippets/cart-drawer-footer.liquid`

Use Shopify’s code search to look for:

* `checkout`
* `btn--checkout`
* `name="checkout"`

***

### ✏ Step 2: Identify the button code

The button could look like:

```html theme={null}
<a href="/checkout" name="checkout" class="btn btn--checkout">Checkout</a>
```

or

```html theme={null}
<button type="submit" name="checkout" class="btn btn--checkout">Checkout</button>
```

etc ...

***

### ⚙ Step 3: Replace it with your custom button

#### If it’s an `<a>` tag → replace with `<button>`:

```html theme={null}
<button id="magic-checkout-button" type="button" class="btn btn--checkout">
  Checkout
</button>
```

Optionally add:

```html theme={null}
onclick="TRIGGER_QUICK_CHECKOUT()"
```

to trigger Paytring checkout.

#### If it’s already a `<button>`:

* Keep it a `<button>`
* Change `type` to `"button"`
* Add `id="magic-checkout-button"`
* Add `onclick="TRIGGER_QUICK_CHECKOUT()"` if your id is not triggering checkout

**Example final button:**

```html theme={null}
<button id="magic-checkout-button" type="button" class="btn btn--checkout" >
  Checkout
</button>
```

***

### ⚠ Step 4: Do this for **both**:

* The main cart page (`cart.liquid` or similar)
* The cart drawer (`cart-drawer.liquid` or similar)

***

## ✅ Checklist

* [ ] Find checkout buttons
* [ ] Replace `<a>` with `<button>` (or adjust `<button>`)
* [ ] Add `id="magic-checkout-button"` and `type="button"`
* [ ] Add `onclick="TRIGGER_QUICK_CHECKOUT()"` if needed

***

## 4️⃣ Add Buy Now button (Product Page)

Let your customers buy directly from the product page, skipping the cart.

### 🔍 Step 1: Find Shopify’s dynamic checkout button

Typically:

```liquid theme={null}
{{ form | payment_button }}
```

or sometimes:

```html theme={null}
<button type="submit" name="checkout">Buy it now</button>
```

Files are usually `product.liquid`, `sections/main-product.liquid`, or similar.

***

### ✏ Step 2: Remove or comment out Shopify’s default button

```liquid theme={null}
{%- comment -%}{{ form | payment_button }}{%- endcomment -%}
```

***

### 📦 Step 3: Add the placeholder for Paytring button

```html theme={null}
<div id="quick-checkout-div"></div>
```

Place it **exactly where the removed button was**.

***

### ⚙ Step 4: Render your Buy Now button

Right after including the Paytring CDN scripts, add:

```html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function() {
    QUICK_RENDER_BUY_BUTTON({
      backgroundColor: "#003c23"
    });
   // Only add the next line if the button isn’t working normally:
    // SET_VARIANT_SELECTOR('select[name="id"]');
  });
</script>
```

#### We have multiple styling options for this buy button

| Option          | Example                | Notes                                   |
| :-------------- | :--------------------- | :-------------------------------------- |
| backgroundColor | `"#003c23"` (hex code) | Button background color                 |
| borderRadius    | `"1rem"`               | CSS border radius property              |
| padding         | `"0px 0px 0px 0px"`    | CSS padding; usually in px              |
| fontSize        | `"16px"`               | Button font size                        |
| width           | `"100%"`               | Width in percentage                     |
| gap             | `"8px"`                | Space between internal elements, if any |

***

## ✅ Quick summary:

* [ ] Find and remove Shopify’s default payment button
* [ ] Add `<div id="quick-checkout-div"></div>`
* [ ] Include CDN scripts
* [ ] Add JS to render your Buy Now button

***

## 5️⃣ Notify business team & set webhook into paytring dashboard

* Notify the business team after each shop integration
* Set webhook URL to:

```
https://quick.paytring.com/quick/<SHOP_ID>/webhook/success
```

***

## 6️⃣ Pass your shopify logged-in customer data to Paytring

Above your CDN scripts, add below js snipet in `theme.liquid`:

```html theme={null}
<script>
 var QUICK_CUSTOMER = {
   email : '',
   address : {},
 };
</script>
{% if customer %}
<script>
 QUICK_CUSTOMER.email = '{{ customer.email }}';
 QUICK_CUSTOMER.address = {{ customer.addresses | json }};
</script>
{% endif %}
```

***

## 7️⃣ Restrict Paytring checkout to certain countries

Also in `theme.liquid`, add:

```html theme={null}
<script>
 QUICK_RESTRICT_COUNTRIES(["US", "IN"]);
</script>
```

Replace with your target country codes.

This ensures:
✅ Only users from allowed countries see Paytring checkout
✅ Others see Shopify’s default checkout

***

## 8️⃣ Listen to detected country and add custom logic

If your store already uses a geo‑detection script or service, it may **automatically** dispatch a custom event named:

```js theme={null}
"current_country"
```

with the visitor’s detected country code.

You **only** need to add a listener to react when this happens.

***

### ✏ **How to add the listener**

Add this script **after** your Paytring CDN scripts (for example, in `theme.liquid`):

```html theme={null}
<script>
  document.addEventListener("current_country", function(e) {
    const countryCode = e.detail.code;
    console.log("Detected country code:", countryCode);

    // 👉 Add your custom logic here, such as:
    // - Show or hide the Paytring checkout button
    // - Change button text, labels, or styling
    // - Fallback to Shopify's default checkout if needed
    // Example: if (countryCode === "US") { ... }
  });
</script>
```

***

### 📍 **Why add this**

This lets your shop:

* React dynamically whenever the visitor’s country is detected or changes
* Add custom UX behavior per country
* Keep your checkout flow flexible and localized for different regions

***

⚠ **Important:**
You do **not** need to dispatch or emit the event yourself.
Your geo‑detection system or script will already emit it automatically.

***

✅ **Tip:**

* You can combine this listener with Paytring’s built‑in method:

  ```js theme={null}
  QUICK_RESTRICT_COUNTRIES(["US", "IN", ...]);
  ```

  to:

  * Automatically limit Paytring checkout to specific countries
  * And add extra client‑side behaviors — like showing custom messages, changing styling, or falling back to Shopify’s native checkout when the detected country isn’t supported
* You can add your custom script to update the button visibility

***

## 9️⃣ Handle dynamic or shadow DOM checkout buttons (advanced)

In some Shopify themes or custom storefronts, checkout buttons may:

* Be added dynamically after page load
* Appear inside **shadow DOM elements**
* Or change based on product or cart updates

In these cases, your initial DOM updates (like replacing or hiding the button) might **not work immediately**, because the elements don’t yet exist in the HTML.

***

### ⚙ **Solution: Run a script at custom intervals**

You can add a script that **runs every few milliseconds** to repeatedly check for the target button and update it when it appears.

Here’s an example:

```html theme={null}
<script>
  // Runs every 200 milliseconds
  const intervalId = setInterval(() => {
    // Example: look for Shopify's default Buy It Now button
    const dynamicBtnContainer = document.querySelector('.dynamic-btn');

    if (dynamicBtnContainer) {
      const buyItNow = dynamicBtnContainer.querySelector('shopify-buy-it-now-button');

      if (buyItNow) {
        // Hide or replace it
        buyItNow.style.display = 'none';

        // Or insert your custom Paytring checkout button here
        // ...

        console.log("Updated dynamic Buy Now button");

        // Optionally, stop checking if done:
        clearInterval(intervalId);
      }
    }
  }, 200);
</script>
```

***

### 📍 **Why add this**

* Handles buttons rendered **after** initial page load
* Works even when elements are created dynamically by JavaScript
* Useful when you don’t have direct access to edit theme code deeply

***

⚠ **Important:**
Keep the interval reasonably short (e.g., 100–500 ms) to avoid performance issues.
Optionally, stop the interval once your changes succeed (using `clearInterval`).

***

✅ **Tip:**
This method is especially useful for:

* Custom themes with heavy JavaScript
* Themes using **shadow DOM** or **dynamic cart drawers**
* When default liquid template changes alone aren’t enough

***