Card Session SDK v2.0.0

Overview

The Card Session SDK is a JavaScript library that enables merchants to accept credit card payments securely through DOKU's payment gateway. Simply include the SDK in your webpage and start processing payments with just a few lines of code.

Integration Flow

The efficient payment flow involves four main steps: backend session, data collection (SDK), 3DS authentication, and backend confirmation.

1. Customer initiates payment - User fills payment form on your website
2. Generate payment session - Your backend calls DOKU API to create a session
3. Return session ID to frontend - Session ID is passed to the browser
4. Collect card data - SDK validates and encrypts card information
5. Submit to DOKU - Encrypted data sent to DOKU payment gateway
6. 3DS authentication - User completes Strong Customer Authentication if required
7. Payment completion - Result returned to your backend via webhook

Quick Start

1. Include the SDK

Add the DOKU Card Session SDK to your HTML page. Contact DOKU support to get the SDK URL for your environment:

            Copy
<!-- For sandbox/testing environment -->
<script src="https://cdn.doku.com/card-session/sandbox/v2.0.0/card-session.js"></script>

<!-- For production environment -->
<script src="https://cdn.doku.com/card-session/production/v2.0.0/card-session.js"></script>
          

2. Initialize the SDK

Initialize

            Copy
// Initialize SDK (environment is pre-configured in the SDK file)
PG.init().then((sdkInstance) => {
  // Verify environment
  console.log('Environment:', PG.getEnvironment());
  console.log('API URL:', PG.getApiBaseUrl());

  // Important: Chain the Device Data API status check
  return sdkInstance.isDeviceDataApiSuccessful();
})
.then(() => {
  // This block runs ONLY if both initialization AND the Device Data API check succeeded.

  // Proceed with secure payment flow (e.g., enabling the Pay button)
  document.getElementById('payButton').disabled = false;
})
.catch((error) => {
  // This block catches all failures (critical init error OR Device Data API error).
  
  // Proceed with secure payment flow (e.g., disable payment and alert the user/system)
  document.getElementById('payButton').disabled = true;
});

        

3. Process Payment

Collect and submit card data to DOKU:

            Copy
const cardData = {
  payment_session_id: 'ps_sandbox_xxxxxxxxxxxxx',
  card_number: '4111111111111111',
  expiry_month: '12',
  expiry_year: '25',
  cvn: '123',
  cardholder_first_name: 'John',
  cardholder_last_name: 'Doe',
  cardholder_email: 'john@example.com'
};

PG.payment.collectCardData(cardData, function(error, response) {
  if (error) {
    console.error('Payment failed:', error.message);
  } else if (response.requires_action) {
    // 3DS authentication required
    window.location.href = response.action_url;
  } else {
    console.log('Payment successful!', response);
  }
});
          

Integration Guide

1. Generate Payment Session

Before collecting card data, you must generate a payment session from your backend. This creates a secure session with DOKU and returns a session ID.

Backend Example (Node.js):

            Copy
// Your backend API endpoint
app.post('/api/create-payment-session', async (req, res) => {
  const response = await fetch('https://api.doku.com/payment-sessions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 100000,
      currency: 'IDR',
      customer: {
          name: 'John Doe',
          email: 'john@example.com'
      },
      // Additional session parameters...
    })
  });

  const data = await response.json();
  res.json({
    session_id: data.payment_session_id
  });
});
          

Frontend - Fetch Session ID:

            Copy
// Call your backend to get session ID
const response = await fetch('/api/create-payment-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 100000,
    customer_id: '12345'
  })
});

const { session_id } = await response.json();
console.log('Payment Session ID:', session_id);
          

2. Initialize SDK

Initialize the SDK with your DOKU Client ID. The environment and API URL are already configured in the SDK file you included:

            Copy
// Initialize
PG.init().then((sdkInstance) => {
  // Verify environment
  console.log('Environment:', PG.getEnvironment());
  console.log('API URL:', PG.getApiBaseUrl());

  // Important: Chain the Device Data API status check
  return sdkInstance.isDeviceDataApiSuccessful();
})
.then(() => {
  // This block runs ONLY if both initialization AND the Device Data API check succeeded.

  // Proceed with secure payment flow (e.g., enabling the Pay button)
  document.getElementById('payButton').disabled = false;
})
.catch((error) => {
  // This block catches all failures (critical init error OR Device Data API error).
  
  // Proceed with secure payment flow (e.g., disable payment and alert the user/system)
  document.getElementById('payButton').disabled = true;
});
          

3. Validate Card Data

Use built-in validation before submission:

            Copy
// Validate card number
if (!PG.card.validateCardNumber(cardNumber)) {
  alert('Invalid card number');
  return;
}

// Detect card brand
const brand = PG.card.detectBrand(cardNumber);
console.log('Card brand:', brand); // 'visa', 'mastercard', 'amex', 'discover', 'jcb', 'dinersclub', 'unionpay'

// Validate expiry
if (!PG.card.validateExpiry(month, year)) {
  alert('Invalid or expired card');
  return;
}

// Validate CVV
if (!PG.card.validateCvv(cvv, brand)) {
  alert('Invalid CVV');
  return;
}
          

4. Submit Payment

Submit the card data with the session ID from step 1:

            Copy
const cardData = {
  // Required: Session ID from your backend
  session_id: session_id,

  // Required: Card information
  card_number: '4111111111111111',
  expiry_month: '12',
  expiry_year: '25',
  cvv: '123',

  // Required: Cardholder information
  card_holder_first_name: 'John',
  card_holder_last_name: 'Doe',

  // Optional but recommended
  card_holder_email: 'john@example.com',
  card_holder_phone_number: '+6281234567890',

  // Optional: Billing information
  billing_information: {
    address: '123 Main St',
    city: 'Jakarta',
    postal_code: '12345',
    country: 'ID'
  }
};

PG.payment.collectCardData(cardData, function(error, response) {
  if (error) {
    console.error('Error:', error.message);
    showErrorMessage(error.message);
  } else {
    console.log('Payment completed!');
    console.log('Payment Request ID:', response.payment_request_id);
    showSuccessMessage('Payment successful!');
  }
});
          

5. Handle 3D Secure Authentication

When 3DS is required, the SDK provides an action URL for authentication:

            Copy
// After 3DS, user returns to your callback URL
const urlParams = new URLSearchParams(window.location.search);
const paymentRequestId = urlParams.get('payment_request_id');
const status = urlParams.get('status');

if (paymentRequestId) {
  if (status === 'success') {
    // Verify with your backend
    verifyPaymentStatus(paymentRequestId);
  } else {
    showErrorMessage('Payment authentication failed');
  }
}
          

API Reference

PG.init()

Initialize the SDK with client configuration.

            Copy
PG.init();
// Environment and API URL are pre-configured (no setup needed)

PG.getEnvironment()

Get the current environment (read-only, pre-configured in SDK).

            Copy
const env = PG.getEnvironment();
// Returns: 'sandbox' or 'production'

PG.getApiBaseUrl()

Get the current API base URL (read-only, pre-configured in SDK).

            Copy
const url = PG.getApiBaseUrl();
// Returns: 'https://sandbox.doku.com' or 'https://app.doku.com'

PG.getEnvironmentConfig()

Get complete environment configuration.

            Copy
const config = PG.getEnvironmentConfig();
// Returns: { environment: 'sandbox', apiBaseUrl: '...', buildTime: true }

PG.card.validateCardNumber(cardNumber)

Validate card number using Luhn algorithm.

            Copy
const isValid = PG.card.validateCardNumber('4111111111111111'); // true

PG.card.detectBrand(cardNumber)

Detect card brand from card number.

            Copy
const brand = PG.card.detectBrand('4111111111111111');
// Returns: 'visa', 'mastercard', 'amex', 'discover', 'jcb', 'dinersclub', 'unionpay'

PG.card.validateExpiry(month, year)

Validate card expiry date.

            Copy
const isValid = PG.card.validateExpiry('12', '25'); // true/false

PG.card.validateCvv(cvv, brand)

Validate CVV code.

            Copy
const isValid = PG.card.validateCvv('123', 'visa'); // true

PG.card.formatCardNumber(cardNumber)

Format card number with spaces.

            Copy
const formatted = PG.card.formatCardNumber('4111111111111111');
// Returns: '4111 1111 1111 1111'

PG.payment.collectCardData(cardData, callback)

Submit payment with encrypted card data.

            Copy
PG.payment.collectCardData(cardData, function(error, response) {
  if (error) {
    // Handle error
  } else {
    // Payment successful
  }
});

PG.getDeviceData()

Manually trigger device data collection.

            Copy
PG.collectDeviceData();
          

PG.isDeviceDataReady()

Check if device data collection is complete.

           Copy
if (PG.isDeviceDataReady()) {
  const deviceData = PG.getDeviceData();
}

Test Cards

Use these test cards in sandbox environment:

Live Demo

Try out the Card Session SDK with our interactive demo. Experience the complete payment flow including card validation, device data collection, and 3D Secure authentication.

Complete Integration Example

Here's a complete HTML page showing how to integrate the Card Session SDK:

             Copy
<!DOCTYPE html>
<html>
  <head>
    <title>Payment Page</title>
  </head>
  <body>
    <h1>Complete Your Payment</h1>

    <form id="paymentForm">
      <label>Card Number:</label>
      <input type="text" id="cardNumber" placeholder="4111 1111 1111 1111" required>

      <label>Expiry:</label>
      <input type="text" id="expMonth" placeholder="MM" maxlength="2" required>
      <input type="text" id="expYear" placeholder="YY" maxlength="2" required>

      <label>CVV:</label>
      <input type="text" id="cvv" placeholder="123" maxlength="4" required>

      <label>Name:</label>
      <input type="text" id="firstName" placeholder="First Name" required>
      <input type="text" id="lastName" placeholder="Last Name" required>

      <label>Email:</label>
      <input type="email" id="email" placeholder="email@example.com" required>

      <button type="submit" id="payButton">Pay Now</button>
    </form>

    <!-- Include DOKU Card Session SDK -->
    <script src="https://cdn.doku.com/card-session/sandbox/v2.0.0/card-session.js"></script>

    <script>
      // Initialize SDK
      PG.init().then((sdkInstance) => {
        return sdkInstance.isDeviceDataApiSuccessful();
      })
      .then(() => {
        document.getElementById('payButton').disabled = false;
      })
      .catch((error) => {
        document.getElementById('payButton').disabled = true;
      });

      // Handle form submission
      document.getElementById('paymentForm').addEventListener('submit', async function(e) {
          e.preventDefault();

          // Get form values
          const cardNumber = document.getElementById('cardNumber').value;
          const expMonth = document.getElementById('expMonth').value;
          const expYear = document.getElementById('expYear').value;
          const cvv = document.getElementById('cvv').value;

          // Validate before submission
          if (!PG.card.validateCardNumber(cardNumber)) {
            alert('Invalid card number');
            return;
          }

          if (!PG.card.validateExpiry(expMonth, expYear)) {
            alert('Invalid expiry date');
            return;
          }

          // Get payment session from your backend
          const response = await fetch('/api/create-payment-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ amount: 100000 })
          });

          const { session_id } = await response.json();

          // Prepare card data
          const cardData = {
            session_id: session_id,
            card_number: cardNumber,
            expiry_month: expMonth,
            expiry_year: expYear,
            cvv: cvv,
            card_holder_first_name: document.getElementById('firstName').value,
            card_holder_last_name: document.getElementById('lastName').value,
            card_holder_email: document.getElementById('email').value
          };

          // Submit to DOKU
          PG.payment.collectCardData(cardData, function(error, response) {
            if (error) {
              alert('Payment failed: ' + error.message);
            } else {
              alert('Payment successful!');
            }
          });
      });
    </script>
  </body>
</html>
          

Troubleshooting

Common Issues

1. "SDK not initialized" Error

Make sure you call PG.init() before using any payment methods:

PG.init();

2. "Invalid card number" Error

Validate the card number before submission:

if (!PG.card.validateCardNumber(cardNumber)) {
  alert('Please enter a valid card number');
  return;
}

3. Payment Session Expired

Payment sessions have a limited lifetime. Generate a new session if expired:

// If payment fails with "session expired" error
// Call your backend to generate a new session
const { session_id } = await generateNewPaymentSession();

4. 3DS Redirect Not Working

Ensure your 3DS callback URL is correctly configured in DOKU dashboard:

• Check callback URL is whitelisted
• Verify callback URL uses HTTPS
• Test callback URL is accessible

5. Device Data Not Collecting

Device data collection requires browser APIs. Check console for errors:

// Check if device data is ready
if (!PG.isDeviceDataReady()) {
  console.warn('Device data not ready yet');
}

// Manually trigger if needed
PG.collectDeviceData().then(data => {
  console.log('Device data collected:', data);
});

Getting Help

• DOKU Developer Documentation: https://developers.doku.com
• Technical Support: Contact your DOKU account manager
• API Status: Check DOKU status page for any service disruptions

Response Code Reference

This section provides a comprehensive reference of all HTTP status codes and error codes returned by the DOKU JavaScript SDK API endpoints. Use this reference to handle API responses correctly in your integration.

HTTP Status Codes by Endpoint

Detail Error Codes Reference

Complete list of all error codes that may be returned by the API, organized alphabetically.

Error Codes by Category

Error codes grouped by their common underlying issue.