3DS And Card Tokenization

Our SDK lets your checkout tokenize cards and run 3D Secure (3DS 2.x) when required by the issuer — internally, with no extra scripts for the integrator.

Important: The integrator does not need to know which acquirer or 3DS provider is used. That’s resolved internally by the SDK and/or by your primary server.

🚀 How to include

Option A — Modern Mode (ES Modules)

Option B — Global Mode (`window.ch`)

⚙️ API

`createCh(): ChInstance`

Creates a new SDK instance.

`.setBackendUrl(url: string): this`

Sets your primary server URL .

`.setPublicToken(token: string): this`

Sets the Public Token for the store/seller.

`.encrypt(card: CardData, context: PaymentContext): Promise<PaymentResult>`

Tokenizes card data and, if needed, runs the 3DS flow internally.

// Card data
type CardData = {
  number: string;    // PAN
  expMonth: string;  // "01".."12"
  expYear: string;   // "29" | "2029"
  cvv?: string;
};

// Payment context
type PaymentContext = {
  amount: number;     // in cents
  currency: string;   // "BRL", "USD", ...
  orderId: string;    // order id
  customer?: { email?: string; name?: string; phone?: string; };
  returnUrl?: string; // thank-you page (optional)
};

// Expected result
type PaymentResult = {
  token: string;      // secure card token
  status?: 'authenticated' | 'frictionless' | 'attempted' | 'failed' | 'error';
  eci?: string;
  cavv?: string;
  xid?: string;
  version?: string;   // "2.1.0" | "2.2.0"
  [extra: string]: any;
};

🔐 3DS behavior (what integrators need to know)

You call encrypt(card, context) as usual.

The SDK resolves which acquirer and 3DS provider to use.

If the issuer requires it, the 3DS challenge opens as an overlay/iframe on the same page.

Finally, encrypt() resolves with { token, status, eci, cavv, xid, ... }.

You send the token to your backend to complete the charge.

No additional steps are required in the checkout beyond what’s shown above.

✅ Checkout requirements

HTTPS in production.

Provide these minimum context fields: amount, currency, orderId, customer.email.

Handle the encrypt() result to continue your order flow.

📦 Minimal complete example (HTML)

🔒 Security & Best Practices

Never log PAN/CVV to the console or any logs.

If your security policy blocks external resources, add the needed sources to your CSP (see example below).

🧰 Troubleshooting

“Started encrypt… but nothing happens”
Ensure you don’t trigger multiple flows in parallel (disable the button while processing) and allow the page to open third-party iframes.

Intermittent failure on the first attempt
Could be initial 3DS provider load time. Update to the latest SDK (modules wait for readiness before authenticating) and avoid calling encrypt() in parallel.

CORS errors when loading the SDK
Make sure your CDN replies with Access-Control-Allow-Origin for .js/.mjs and Content-Type: application/javascript, especially when using <script type="module">.

📌 Summary

Include the SDK (ESM or global).

Configure .setBackendUrl() and .setPublicToken().

Call encrypt(card, context) and use the returned data.

3DS is handled internally — no extra steps in the checkout.

3DS And Card Tokenization

🚀 How to include#

Option A — Modern Mode (ES Modules)#

Option B — Global Mode (window.ch)#

⚙️ API#

createCh(): ChInstance#

.setBackendUrl(url: string): this#

.setPublicToken(token: string): this#

.encrypt(card: CardData, context: PaymentContext): Promise<PaymentResult>#

🔐 3DS behavior (what integrators need to know)#

✅ Checkout requirements#

📦 Minimal complete example (HTML)#

🔒 Security & Best Practices#

🧰 Troubleshooting#

📌 Summary#