Card Payment Overview

// =============================================================================
// CARD PAYMENT — BACKEND (Node.js). Never expose API secret to the client.
// =============================================================================

const PAYVESSEL_BASE = process.env.PAYVESSEL_BASE_URL || 'https://api.payvessel.com';
const API_KEY = process.env.PAYVESSEL_API_KEY;
const API_SECRET = process.env.PAYVESSEL_API_SECRET;

const headers = {
  'Content-Type': 'application/json',
  'api-key': API_KEY,
  'api-secret': `Bearer ${API_SECRET}`,
};

/**
 * Step 1 — Charge the card with encrypted payload from your frontend.
 * Frontend must encrypt card using the public key from GET /pms/checkout/card-payment/public-key/
 */
async function chargeCard(encryptedCardData, encryptionKey, reference) {
  const res = await fetch(`${PAYVESSEL_BASE}/pms/checkout/card-payment/charge/`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      cardData: encryptedCardData,  // from your frontend (encrypted with public key)
      key: encryptionKey,
      reference,                    // unique per transaction, e.g. txn_xxx
    }),
  });

  const data = await res.json();
  if (!res.ok) {
    throw new Error(data.message || 'Charge failed');
  }
  return data;
}

/**
 * Step 2 — If the issuer requires OTP, call this after the customer submits OTP.
 */
async function validateOtp(transactionRef, otp) {
  const res = await fetch(`${PAYVESSEL_BASE}/pms/checkout/card-payment/validate-otp/`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      transactionRef,
      otp,
    }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.message || 'OTP validation failed');
  return data;
}

/**
 * Step 3 — If the issuer requires PIN, call this with the card PIN.
 */
async function validatePin(transactionRef, pin) {
  const res = await fetch(`${PAYVESSEL_BASE}/pms/checkout/card-payment/validate-pin/`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      transactionRef,
      pin,
    }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.message || 'PIN validation failed');
  return data;
}

/**
 * Step 4 — Confirm final status (poll or call after redirect/callback).
 */
async function confirmPaymentStatus(transactionRef) {
  const res = await fetch(
    `${PAYVESSEL_BASE}/pms/checkout/card-payment/confirm-status/?reference=${encodeURIComponent(transactionRef)}`,
    { headers }
  );
  const data = await res.json();
  if (!res.ok) throw new Error(data.message || 'Confirm status failed');
  return data;
}

// Example usage (pseudo): charge → then if pending, validate OTP or PIN → then confirm status
// const chargeResult = await chargeCard(cardData, key, 'txn_123');
// if (chargeResult.status === 'pending' && chargeResult.requiresOtp) {
//   await validateOtp(chargeResult.transactionRef, userEnteredOtp);
// }
// const final = await confirmPaymentStatus(chargeResult.transactionRef);