Migration Guide: v1 → v2

This guide walks existing merchants through moving an integration built against the v1.0.0 documentation (./v1/index.html) to the current v2.0.0 documentation (./index.html). It covers exactly what changed, what stayed the same, and the order in which to make changes so nothing breaks in production.

Read this before you start

Only two things actually changed in a way that affects your code: the Web-SDK object/method names and the Node.js signature example. Every REST API endpoint (/api/v0/deposits/*, /api/v0/withdrawal/*) is unchanged. If you only use the API Integration (no Web-SDK modal), you can skip straight to Step 4 and Open Questions.

Quick reference
Item v1.0.0 v2.0.0 (latest)
SDK global object cpg abcsdk
Modal instance creation new cpg.Instance(config) new abcsdk.Instance(config)
Trigger a deposit instance.launch(callback, options) instance.deposit(callback, options)
Trigger a withdrawal instance.withdraw(callback, referenceId) instance.withdraw(callback, referenceId) — unchanged
REST API endpoints /api/v0/... /api/v0/... — unchanged
New endpoint — POST /api/v1/withdrawl/balances (optional, additive)
Node.js signature example Secret key hex-decoded before HMAC Secret key used as-is before HMAC — see Open Questions

Before You Begin

  1. Confirm which integration type you use. Merchants on the Web-SDK Integration need Steps 1–4 below. Merchants on the API Integration only (no in-page modal) only need Step 4 and can otherwise skip to What Did Not Change.
  2. Locate every place your codebase references cpg or CPGModal. A quick repo-wide search for cpg.Instance, cpgInstance, cpgmodal.js, .launch( will surface every call site that needs updating.
  3. Do this in a staging/sandbox environment first. Use test credentials so you can exercise the deposit and withdrawal modals end-to-end before touching production.
  4. Keep v1 available as a fallback while you validate — see Rollback Plan.

Migration Steps

Step 1: Update the SDK reference

The Web-SDK's global object was renamed from cpg to abcsdk. Rename your instance file and update the constructor call accordingly. The config object you pass in is unchanged.

Before (v1.0.0) — e.g. cpgmodal.js:

// cpgmodal.js
// Create an instance of CPGModal
const config = {
  // ...your configuration options
};
const cpgInstance = new cpg.Instance(config);
After (v2.0.0) — e.g. abcmodal.js:

// abcmodal.js
// Create an instance of abcSDK
const config = {
  // ...your configuration options
};
const abcModal = new abcsdk.Instance(config);

Note

Renaming the file and the local variable (cpgInstance → abcModal) is a documentation convention, not a requirement — what matters functionally is instantiating from abcsdk.Instance instead of cpg.Instance. Keep your own naming if you prefer, just update every call site consistently.

Step 2: Update the deposit trigger call

The method used to launch the modal for a deposit was renamed from .launch() to .deposit(). This applies to both the "Launch Modal with Options" flow and the transferReferenceId-based deposit flow.

Before (v1.0.0):

cpgInstance.launch(callback, options);
// or, for the transferReferenceId variant:
cpgInstance.launch(callback, transferReferenceId);
After (v2.0.0):

abcModal.deposit(callback, options);
// or, for the transferReferenceId variant:
abcModal.deposit(callback, transferReferenceId);

Warning

If you skip this rename, calling .launch() on an abcsdk.Instance object will fail because that method no longer exists on the new SDK object — it must be renamed to .deposit(), not just left as-is.

Step 3: Withdrawal call (no change)

The withdrawal trigger method keeps its name, .withdraw(callback, referenceId). You only need to call it on the renamed instance variable from Step 1. 


// v1.0.0
cpgInstance.withdraw(callback, referenceId);

// v2.0.0 — same method, renamed instance only
abcModal.withdraw(callback, referenceId);

Step 4: Verify your signature code

Applies to everyone, regardless of integration type. See Open Questions / Known Issues below before changing any production signing code — the v2 docs contain two examples that now disagree with each other, so this needs a deliberate decision, not a blind copy-paste.

Step 5: Adopt new APIs (optional)

v2.0.0 adds a new, purely additive endpoint: Fetch Withdrawals Balance.

Method: POST
Endpoint: ${BASE_URL}/api/v1/withdrawl/balances

This lets you query available/locked withdrawal balance directly instead of inferring it elsewhere. It requires no changes to existing flows — adopt it whenever it's useful. Full request/response details are in the API Integration → Fetch Withdrawals Balance section of the main documentation.

What Did Not Change

To scope your migration correctly, these are confirmed unchanged between v1.0.0 and v2.0.0:

  • Every REST endpoint under /api/v0/... (Initiate Deposit, UPI Transfer, Bank Transfer, Taka Transfer, Deposit/Withdrawal Status, Initiate/Process Withdrawal, Fetch Deposits/Withdrawals/Chargebacks Lists) — same paths, same request/response shapes.
  • Web-Redirection Integration flow.
  • Callback API Integration and callback URL behavior.
  • The signature algorithm (HMAC-SHA256 over the sorted, UTF-8 JSON body) and the steps to generate it. Only one language example's key-encoding step changed — see Open Questions.

Testing Checklist

Work through this in staging before deploying to production:

  • [ ] All references to cpg.Instance replaced with abcsdk.Instance
  • [ ] All .launch(...) calls replaced with .deposit(...)
  • [ ] .withdraw(...) calls still work against the renamed instance
  • [ ] Deposit modal opens and completes a test transaction end-to-end
  • [ ] Withdrawal modal opens and completes a test transaction end-to-end
  • [ ] Signature generation verified against a real API call (not just the doc example) — see Step 4
  • [ ] Callback URLs still received and processed correctly
  • [ ] (Optional) Fetch Withdrawals Balance integrated and returning expected values

Rollback Plan

The v1.0.0 documentation and its SDK object (cpg.Instance) remain published at ./v1/index.html. If your updated integration fails validation in staging, you can revert your local code changes (the abcsdk rename and the .deposit() rename) without needing any backend changes on our side, since the underlying REST APIs did not change.

Open Questions / Known Issues

Signature examples disagree — verify before you rely on this

In the v1.0.0 docs, the Node.js signature example hex-decoded the secret key before hashing: 


const keyBytes = Buffer.from(secret, 'hex');
const hmac = crypto.createHmac('sha256', keyBytes)...

In the current v2.0.0 docs, the Node.js example was changed to use the secret directly, with no hex decoding: 


const hmac = crypto.createHmac('sha256', secret)...

However, the CryptoJS browser example elsewhere on the same v2.0.0 page still hex-decodes the secret (CryptoJS.enc.Hex.parse(secret)), and the Java example has never hex-decoded it (key.getBytes() in both v1.0.0 and v2.0.0). These three examples do not all agree with each other in the current docs.

This looks like a documentation inconsistency rather than an intentional backend change, but we have not been able to confirm which behavior the backend actually expects from this file comparison alone. Before changing production signing code, verify directly against a real API call in staging (or confirm with the gateway support/backend team) which key encoding your account currently requires. If your existing v1 integration is already generating valid signatures, the safest path is to leave your signing code unchanged and re-verify it continues to work after your SDK migration — do not switch key encoding based on the doc example alone.

If you have questions about anything in this guide before proceeding — especially the signature behavior above, or which flows apply to your integration — raise them before rolling changes to production.