---
title: Migrate to Pine Labs Payment Gateway
slug: use-cases/migrate-to-pinelabs
excerpt: >-
  Step-by-step guide to migrating from another payment gateway to Pine Labs
  Online — with zero downtime and no customer disruption.
sidebar_order: 6
hidden: false
metadata:
  title: Migrate to Pine Labs — Zero Downtime Gateway Migration | Pine Labs
  description: >-
    Complete migration guide for switching from your current payment gateway to
    Pine Labs Online. Run integrations in parallel, transition customers
    smoothly with no payment disruption, and achieve full operational readiness.
  keywords: >-
    payment gateway migration, migrate to Pine Labs, switch payment provider,
    zero downtime migration, gateway transition
  robots: index
---
Move from your current payment gateway to Pine Labs Online without losing customers, transaction history, or uptime.

---

## What you're building

By the end of this guide, you'll have:

- A migration plan tailored to your current setup
- Pine Labs integration running in parallel with your existing gateway
- Customers transitioned smoothly with no payment disruption
- Full operational readiness on Pine Labs Online

---

## Before you begin

| Requirement | Details |
|---|---|
| Pine Labs account | [Sign up →](https://dashboardv2.pluralonline.com/signup) |
| API credentials | Client ID + Client Secret from [Dashboard → Settings](dashboard/settings) |
| Current gateway access | To run both gateways in parallel during migration |
| Technical team | Backend developers for integration work |

---

## Migration overview

```mermaid
flowchart TD
    A[Phase 1<br/>Plan & Prepare] --> B[Phase 2<br/>Integrate Pine Labs]
    B --> C[Phase 3<br/>Test on UAT]
    C --> D[Phase 4<br/>Parallel Run]
    D --> E[Phase 5<br/>Full Cutover]
    E --> F[Phase 6<br/>Decommission Old Gateway]

    style A fill:#003434
    style B fill:#003434
    style C fill:#003434
    style D fill:#003434
    style E fill:#003434
    style F fill:#003434
```

---

## Phase 1 — Plan & prepare

### Audit your current setup

Document what you're migrating:

| Item | Questions to answer |
|---|---|
| **Payment methods** | Which methods are active? Cards, UPI, Netbanking, Wallets, EMI? |
| **Integration type** | Hosted checkout, server-to-server, SDK, or plugin? |
| **Recurring payments** | Do you have active subscriptions? How many? |
| **Saved cards** | Are customers using tokenised cards for repeat payments? |
| **Webhooks** | Which events are you listening to? What actions do they trigger? |
| **Refund flows** | How are refunds currently processed? Automated or manual? |
| **Settlement schedule** | Daily, weekly, or custom? |
| **Plugins** | Shopify, WooCommerce, Magento, or custom? |

### Map features to Pine Labs equivalents

| Your current feature | Pine Labs equivalent | Notes |
|---|---|---|
| Hosted checkout page | [Hosted Checkout](/hosted-checkout) | Similar redirect-based flow |
| Custom payment form | [Custom Checkout](/custom-checkout) | Requires PCI compliance |
| Embedded checkout | [iFrame Checkout](/iframe-checkout) | Overlay on your page |
| Payment links | [Payment Links](/payment-links) | Dashboard + API |
| Recurring billing | [Subscriptions](/subscriptions) | Plans + subscription API |
| EMI / instalments | [Affordability Suite](/affordability-suite) | Credit, Debit, Cardless EMI |
| Split payments | [Split Settlements](/split-settlements) | Marketplace distributions |
| Webhooks | [Webhooks](/webhooks) | Configurable event notifications |

### Get Pine Labs credentials

1. [Sign up](https://dashboardv2.pluralonline.com/signup) for a Pine Labs Online account
2. Complete KYC verification
3. Get UAT credentials from **Dashboard → Settings → API Keys**

<!-- SCREENSHOT: Dashboard → Settings showing API Keys section with Client ID and Secret -->
> **Screenshot:** *Dashboard → Settings → API Keys — Your migration starts here*

---

## Phase 2 — Integrate Pine Labs

### Update your backend

Replace your current gateway's API calls with Pine Labs equivalents:

| Operation | Typical gateway | Pine Labs Online |
|---|---|---|
| **Authentication** | API key in header | [Generate Token](/api/authentication/generate-token) → Bearer token |
| **Create order** | Create charge/session | [Create Order](/api/orders/create-order) |
| **Process payment** | Charge/confirm | [Create Payment](/api/payments/create-payment) |
| **Capture** | Capture charge | [Capture Order](/api/orders/capture-order) |
| **Refund** | Create refund | [Create Refund](/api/refunds/create-refund) |
| **Get status** | Retrieve charge | [Get Order](/api/orders/get-order) |

### Example: Replacing a checkout flow

**Before (generic gateway):**

```javascript
// Old gateway
app.post('/checkout', async (req, res) => {
  const session = await oldGateway.createSession({
    amount: req.body.amount,
    currency: 'INR',
    successUrl: '/success',
    cancelUrl: '/cancel'
  });
  res.redirect(session.url);
});
```

**After (Pine Labs Online):**

```javascript
// Pine Labs Online
app.post('/checkout', async (req, res) => {
  // Generate token
  const token = await getPineLabsToken();

  // Create order
  const order = await axios.post(
    'https://pluraluat.v2.pinepg.in/api/pay/v1/orders',
    {
      merchant_order_reference: `MIG-${Date.now()}`,
      order_amount: { value: req.body.amount, currency: 'INR' },
      pre_auth: false,
      allowed_payment_methods: ['CARD', 'UPI', 'NETBANKING', 'WALLET'],
      callback_url: 'https://your-domain.com/success',
      failure_callback_url: 'https://your-domain.com/cancel',
      purchase_details: {
        customer: {
          email_id: req.body.email,
          first_name: req.body.name,
          mobile_number: req.body.phone,
          country_code: '91'
        }
      }
    },
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'Request-ID': crypto.randomUUID(),
        'Request-Timestamp': new Date().toISOString()
      }
    }
  );

  res.redirect(order.data.checkout_url);
});
```

### Update webhook handlers

Map your existing webhook events to Pine Labs events:

| Common event | Pine Labs event |
|---|---|
| Payment succeeded | `ORDER_AUTHORIZED` → `ORDER_CAPTURED` |
| Payment failed | Callback with `payment_status: FAILED` |
| Refund processed | `REFUND_PROCESSED` |
| Subscription charged | `SUBSCRIPTION_CHARGED` |
| Subscription cancelled | `SUBSCRIPTION_CANCELLED` |

### E-commerce plugin migration

If you're using a platform plugin:

| Platform | Action |
|---|---|
| **Shopify** | Install [Pine Labs Shopify plugin](/e-commerce-plugins/shopify), configure in Shopify admin |
| **WooCommerce** | Install [Pine Labs WooCommerce plugin](/e-commerce-plugins/woocommerce), activate and configure |
| **Magento** | Install [Pine Labs Magento extension](/e-commerce-plugins/magento) via Composer |
| **OpenCart** | Upload [Pine Labs OpenCart extension](/e-commerce-plugins/opencart) |

---

## Phase 3 — Test on UAT

Run your full payment lifecycle on the Pine Labs UAT environment:

| Test | What to verify |
|---|---|
| **Happy path** | Order → Payment → Capture → success page |
| **Card payments** | Use [test card details](/test-card-details) for success and failure |
| **UPI payments** | UAT UPI is real-time — use ₹1 amounts |
| **Netbanking** | SBI netbanking available on UAT |
| **Webhook delivery** | Webhooks received and processed correctly |
| **Signature verification** | Callback signatures match |
| **Refund flow** | Full and partial refunds work |
| **Error handling** | Graceful handling of declined payments, timeouts |


---

## Phase 4 — Parallel run

Run both gateways simultaneously to de-risk the migration:

```mermaid
flowchart LR
    A[Your App] --> B{Feature flag or % split}
    B -->|10% traffic| C[Pine Labs Online]
    B -->|90% traffic| D[Old Gateway]

    C --> E[Monitor]
    D --> E
    E --> F{All good?}
    F -->|Yes| G[Increase Pine Labs %]
    F -->|Issues| H[Investigate & fix]
```

### Recommended rollout

| Week | Pine Labs traffic | What to monitor |
|---|---|---|
| Week 1 | 10% | Success rates, latency, webhook delivery |
| Week 2 | 25% | Settlement accuracy, refund processing |
| Week 3 | 50% | Full payment method coverage, edge cases |
| Week 4 | 100% | Complete cutover |

### What to monitor during parallel run

| Metric | Acceptable | Action if off |
|---|---|---|
| **Payment success rate** | ≥ 95% | Check error codes, contact support |
| **API response time** | < 2 seconds | Verify network, retry config |
| **Webhook delivery** | 100% | Check endpoint availability, verify signatures |
| **Settlement timing** | T+1 or T+2 | Verify bank account config |

---

## Phase 5 — Full cutover

Once the parallel run is stable:

1. **Switch 100% traffic** to Pine Labs Online
2. **Update production credentials** — replace UAT URLs with production
3. **Configure production webhooks** — point to live endpoints
4. **Verify first live transactions** — make a real payment and refund
5. **Update monitoring** — point alerts to Pine Labs Dashboard

### Go live checklist

- [ ] Production base URL: `https://api.pluralonline.com`
- [ ] Production Client ID and Client Secret configured
- [ ] Production webhook endpoints registered
- [ ] Signature verification working with production keys
- [ ] TLS 1.2+ enforced on all API calls
- [ ] Error handling tested for all payment methods
- [ ] Settlement bank account verified
- [ ] Statement descriptor configured

---

## Phase 6 — Decommission old gateway

After running successfully on Pine Labs for 2–4 weeks:

| Action | Details |
|---|---|
| **Keep old gateway read-only** | Maintain access for historical transaction lookups |
| **Handle pending refunds** | Process any remaining refunds through the old gateway |
| **Export transaction history** | Download reports for your records |
| **Remove old webhook endpoints** | Prevent duplicate processing |
| **Cancel old gateway subscription** | Stop paying for the old service |

---

## Migrating subscriptions

Active subscriptions require special handling:

### Option A: Gradual migration (recommended)

1. Stop creating new subscriptions on the old gateway
2. Create new subscriptions on Pine Labs
3. As old subscriptions come up for renewal, migrate them to Pine Labs
4. Notify customers of the payment processor change

### Option B: Bulk migration

1. Export all active subscriptions from the old gateway
2. Create corresponding plans and subscriptions on Pine Labs
3. Send customers a one-time authorization for the new processor
4. Cut over all subscriptions simultaneously

> **Customer communication:** Always inform customers when changing payment processors. A simple email explaining the transition prevents confusion and disputes.

---

## FAQ

<details>
<summary>Will there be any downtime during migration?</summary>

No. The parallel run approach ensures your existing gateway keeps processing payments while Pine Labs is tested. There's no downtime during the transition.
</details>

<details>
<summary>Can I migrate saved card tokens?</summary>

Card tokens are gateway-specific and cannot be transferred directly. Customers will need to re-enter their card details for the first transaction on Pine Labs. The card is then tokenised for future use.
</details>

<details>
<summary>How long does the migration typically take?</summary>

For a standard integration: 2–4 weeks including testing and parallel run. Complex setups with subscriptions and multiple plugins may take 4–6 weeks.
</details>

<details>
<summary>What if I use a Shopify/WooCommerce plugin?</summary>

Install the Pine Labs plugin alongside your existing one. Test with Pine Labs in sandbox mode, then switch the active payment gateway in your platform settings. This is usually a single toggle.
</details>

<details>
<summary>Will my settlement schedule change?</summary>

Pine Labs offers T+1 and T+2 settlement options. Discuss your preferred schedule with your account manager during onboarding.
</details>

---

## Need help with migration?

For complex migrations or enterprise setups, Pine Labs offers dedicated migration support:

- **Email:** pgsupport@pinelabs.com
- **Migration support team:** Contact your account manager for a dedicated migration engineer
- **Technical documentation:** [API Reference](/api/authentication)

---

## Next steps

- [Quickstart Guide](/quick-start-guide) — core API concepts
- [Checkout options](/checkout-options) — choose the right integration type
- [Webhooks](/developer-tools/webhooks) — configure payment event notifications
- [Dashboard](/dashboard) — monitor your payments