@dimepay/web-sdk

v1.0.14

Published

4 months ago

Dime Pay JavaScript SDK for embedding payment widget

0High
0Medium
0Low

dimemgmt

dimepay payment sdk

🌐 Dime Pay - Web SDK

The official JavaScript SDK for embedding the Dime Pay secure payment widget into any web application.
Supports React, Angular, Vue, and plain JavaScript environments.

This sdk supports 2 flows.

Payment widget for embedded payment processing.
Saving cards for your customers

🚀 Installation

Install via npm:

npm install @dimepay/web-sdk
yarn add @dimepay/web-sdk

🧩 Usage

Step 1: Add a container to your HTML

<div id="dimepay-widget"></div>

Step 2: Initialize the SDK

Payment flow

import { initPayment } from '@dimepay/web-sdk';

const widget = initPayment({
  mountId: "dimepay-widget",
  total: 5000,
  currency: "JMD",
  test: false,
  order_id: "TEST-001",
  client_id: "ck_jtfEtqbrX2Nf7U_evqKVy",
  origin: window.origin,
  styles: {
    primaryColor: '#000000',
    buttonColor: '#000000',
    buttonTextColor: '#FFFFFF',
    noBorderRadius: false,
    backgroundColor: '#FFFFFF'
  },
  data: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IlRFU1QtMDAxIiwidG90YWwiOjUwMDAsInN1YnRvdGFsIjo1MDAwLCJkZXNjcmlwdGlvbiI6IlRoaXMgaXMgYW4gb3JkZXIgZnJvbSB0aGUgc2RrIiwidGF4IjowLCJjdXJyZW5jeSI6IkpNRCIsImZlZXMiOltdLCJpdGVtcyI6W10sImZ1bGZpbGxlZCI6dHJ1ZSwic2hpcHBpbmdQZXJzb24iOnsibmFtZSI6IlNoYW1pciBTYWRkbGVyIiwic3RyZWV0IjoiMSBUZXN0IEF2ZSIsImNpdHkiOiJLaW5nc3RvbiA2Iiwic3RhdGVPclByb3ZpbmNlTmFtZSI6IktpbmdzdG9uIiwicG9zdGFsQ29kZSI6IjAwMDAwIiwiY291bnRyeU5hbWUiOiJKYW1haWNhIn0sImJpbGxpbmdQZXJzb24iOnsibmFtZSI6IlNoYW1pciBTYWRkbGVyIiwic3RyZWV0IjoiMSBUZXN0IEF2ZSIsImNpdHkiOiJLaW5nc3RvbiA2Iiwic3RhdGVPclByb3ZpbmNlTmFtZSI6IktpbmdzdG9uIiwicG9zdGFsQ29kZSI6IjAwMDAwIiwiY291bnRyeU5hbWUiOiJKYW1haWNhIn0sImlhdCI6MTc0Njc2NDQ3NX0.PL18At7kR4i3i3TS2pR2_csKtlUT1EetLgV1z5PfL_g",
  onReady: (data) => console.log("✅ Ready:", data),
  onSuccess: (data) => console.log("✅ Success:", data),
  onFailed: (err) => console.log("❌ Failed:", err),
  onError: (err) => console.log("❌ Error:", err),
  onCancel: () => console.log("⚠️ Cancelled"),
  onLoading: () => console.log("⏳ Loading...")
});

Saving cards

import { initCard } from '@dimepay/web-sdk';

const payload = {
  id: 'CARD-001', //Generated from the requester
  webhookUrl: 'https://webhook.com/callback'
};

const signedData = jwt.sign(payload, 'sk_hokHTudA3hGsz_1rrs-70');

const finalPayload = {
  data: signedData
};

const resp = await fetch(
  `https://sandbox.api.dimepay.app/dapi/v1/card-request`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      client_key: "ck_jtfEtqbrX2Nf7U_evqKVy"
    },
    body: JSON.stringify(finalPayload)
  }
);

const cardRequestResponse = await resp.json();

const widget = initCard({
  mountId: "dimepay-widget",
  test: false,
  card_request_token: cardRequestResponse.token,
  client_id: "ck_jtfEtqbrX2Nf7U_evqKVy",
  origin: window.origin,
  styles: {
    primaryColor: '#000000',
    buttonColor: '#000000',
    buttonTextColor: '#FFFFFF',
    noBorderRadius: false,
    backgroundColor: '#FFFFFF'
  },
  data: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTc0ODAyOTk5MjcyOCwiY3VycmVuY3kiOiJVU0QiLCJjYXJkaG9sZGVyX2ZpcnN0X25hbWUiOiJKb2huIiwiY2FyZGhvbGRlcl9sYXN0X25hbWUiOiJEb2UiLCJjYXJkaG9sZGVyX2VtYWlsIjoiam9obi5kb2VAZXhhbXBsZS5jb20iLCJjYXJkX251bWJlciI6IjUxMDAyNzAwMDAwMDAwMjMiLCJjYXJkX2N2diI6IjEyMyIsImNhcmRfZXhwaXJ5IjoiMjUxMiIsImNhcmRfYWRkcmVzcyI6IjEyMyBNYWluIFN0cmVldCIsImNhcmRfY2l0eSI6Ik5ldyBZb3JrIiwiY2FyZF9jb3VudHJ5IjoiVVMiLCJjYXJkX3Bvc3RhbF9jb2RlIjoiMTAwMDEiLCJpYXQiOjE3NDgwMjk5OTJ9.xEDHEUojWibmT6Pxzo1nhd83Xtv-RPdmcUDZCE5i35w",
  onReady: (data) => console.log("✅ Ready:", data),
  onSuccess: (data) => console.log("✅ Success:", data),
  onFailed: (err) => console.log("❌ Failed:", err),
  onError: (err) => console.log("❌ Error:", err),
  onCancel: () => console.log("⚠️ Cancelled"),
  onLoading: () => console.log("⏳ Loading...")
});

🔐 Secure Flows with JWT

You must generate a signed JWT on your backend and pass it to the SDK.

Example data, JWT payload:

{
  "id": "ORDER-001",
  "total": 5000,
  "subtotal": 5000,
  "description": "This is an order from the sdk",
  "tax": 0,
  "currency": "JMD",
  "fees": [ ],
  "items": [
    {
      "id": "xxxx-xxxx-xxxx-xxxx",
      "price": 1060,
      "sku": "ABCA-IAC",
      "quantity": 1,
      "shortDescription": "",
      "name": "iMac",
      "imageUrl": "https://example.com/images/xxxxxx.jpg",
      "merchant_id": null, // Only required for Dime bridge
      "selectedOptions": [
        {
          "name": "Color",
          "value": "red",
          "type": "CHOICE"
        }
      ]
    }
  ],
  "fulfilled": true,
  "shippingPerson": {
    "name": "Michael Scott",
    "email": "[email protected]",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "billingPerson": {
    "name": "Michael Scott",
    "email": "[email protected]",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "split": null, // Only required for Dime bridge
  "webhookUrl": "https://your-service/path"
}

For Dime Bridge, add the block below to the payload:

      split: [
        {
          fee: 10,
          merchant_id: 'm4D8mQ1wMrdTUIg',
          amount: 500,
        },
        {
          fee: 30,
          merchant_id: 'm7UarSiV9zWxN6v',
          amount: 1500,
        }
      ]

Also for Dime bridge the corresponding item needs to be tagged with a merchant_id

Use a backend library like jsonwebtoken (Node.js) to sign the token using your Dime Pay secret. Please do not expose your secret token on the client for security reasons.

const jwt = require('jsonwebtoken'); const payload = { /* fields above */ }; const signedData = jwt.sign(payload, 'your_secret_key');

⚙️ Configuration Options

| Option |----------------------- | mountId | currency | total | data | client_id | order_id | card_request_token | payment_methods | styles | styles.primaryColor | styles.buttonColor | styles.buttonTextColor | styles.backgroundColor | styles.noBorderRadius | test | onReady | onSuccess | onFailed | onError | onLoading | Type | Required | Description | ---|-----------|---------|--------------------------------------------------------------------| | string | ✅ | The ID of the DOM element to mount the iframe | | string | ✅ | The Currency for the order | | string | ✅ | The total amount the customer is paying | | string | ✅ | JWT containing payment info | | string | ✅ | Client id provided by your pair of API keys | | string | ✅ | Order id for the payment request. Order Id and data.id is the same | | string | ✅ | Card request token for the card tokenization request | | object | optional | Defines payment methods to enable | | object | optional | Defines styles for the payment form | | string | optional | Primary color in hex format | | string | optional | Button color in hex format | | string | optional | Button text color in hex format | | string | optional | Background color in hex format | | boolean | optional | Border radius can be rounded or squared | | boolean | optional | Set to true if testing in sandbox | | func | optional | Callback when payment form is ready | | func | optional | Callback when payment is successful | | func | optional | Callback when a payment failed | | func | optional | Callback when an error occurs and payment form is invalid | | func | optional | Callback when widget starts loading |

💡 Example (Plain HTML + Script)

<script type="module">
  import { initPayment } from '@dimepay/web-sdk';

  initPayment({
    mountId: "dimepay-widget",
    total: 5000,
    currency: "JMD",
    test: false,
    order_id: "TEST-001",
    client_id: "ck_jtfEtqbrX2Nf7U_evqKVy",
    payment_methods: {
      apple_pay: true,
      google_pay: true,
      samsung_pay: true
    },
    origin: window.origin,
    styles: {
      primaryColor: '#000000',
      buttonColor: '#000000',
      buttonTextColor: '#FFFFFF',
      noBorderRadius: false,
      backgroundColor: '#FFFFFF'
    },
    data: { jwt_token },
    onReady: (data) => console.log("✅ Ready:", data),
    onSuccess: (data) => console.log("✅ Success:", data),
  });
</script>

Table: Test Card Numbers

| Card Brand | BIN | Card Number | Expiration Date | CVV | |-------------------|---------|-----------------|-----------------|------| | Visa | 411111 | 1111111111 | 12/2025 | 123 | | Mastercard | 555555 | 55555554444 | 02/2026 | 265 | | American Express | 378282 | 246310005 | 03/2026 | 7890 | | Cartes Bancaires | 436000 | 0001000005 | 04/2040 | 123 | | Carnet | 506221 | 0000000009 | 04/2024 | 123 | | China UnionPay | 627988 | 6248094966 | 04/2040 | 123 | | Diners Club | 305693 | 09025904 | 04/2040 | 123 | | Discover | 644564 | 4564456445 | 04/2040 | 123 | | JCB | 353011 | 13333 0000 | 04/2040 | 123 | | Maestro | 675964 | 9826438453 | 04/2040 | 123 | | Mada | 446404 | 0000000007 | 04/2040 | 123 | | ELO | 451416 | 0000000003 | 04/2040 | 123 | | JCrew | 515997 | 1500000005 | 04/2040 | 123 | | EFTPOS | 401795 | 000000000009 | 04/2040 | 123 | | Meeza | 507808 | 3000000002 | 04/2040 | 123 |

Using a CDN

The dimepay web-sdk script is also available on the unpkg CDN.

Option 1: Use type="module" in your HTML

If you're loading the SDK in a browser and want to use ESM syntax:

<script type="module">
  import { initPayment } from 'https://unpkg.com/@dimepay/[email protected]/dist/dimepay.es.js';

  initPayment({
    mountId: 'dimepay-widget',
  });
</script>

Option 2: Use UMD format in your HTML

UMD format is the most compatible format for usage via script tag in any browser.

<script type="module">
  import { initPayment } from 'https://unpkg.com/@dimepay/[email protected]/dist/dimepay.umd.js';

  initPayment({
    mountId: 'dimepay-widget',
  });
</script>

Test Card Numbers

🧾 Changelog

[1.0.11] - 2025-08-19

Add support for Dime Bridge

[1.0.10] - 2025-06-25

Add support for Apple Pay, Google Pay, Samsung Pay

[1.0.9] - 2025-05-27

Add support for ES and UMD usages

[1.0.7] - 2025-05-23

Add support for saving cards

[1.0.5] - 2025-05-14

Add support for webhook urls

[1.0.0] - 2025-05-06

🚀 Initial public release
🧱 iframe-based payment widget injection
✅ Supports onSuccess, onError callbacks
🧩 Configurable via mountId, data