API 2Checkout: Hướng Dẫn Tích Hợp Toàn Diện Xử Lý Thanh Toán (2026)

Tóm tắt

API 2Checkout (nay là Verifone) cho phép các nhà phát triển xử lý thanh toán, quản lý đăng ký và xử lý các giao dịch thương mại điện tử một cách tự động. Nó hỗ trợ các điểm cuối RESTful cho đơn hàng, khách hàng, sản phẩm và webhook với xác thực dựa trên JSON bằng cách sử dụng khóa API. Hướng dẫn này bao gồm mọi thứ từ thiết lập ban đầu đến xử lý webhook nâng cao.

Giới thiệu

Xử lý thanh toán là xương sống của mọi doanh nghiệp trực tuyến. Nếu làm sai, bạn sẽ mất doanh thu. Nếu làm đúng, bạn sẽ mở khóa các thị trường toàn cầu. API 2Checkout (gần đây đã được đổi tên thành Verifone) xử lý thanh toán cho hơn 45.000 người bán trên toàn thế giới, xử lý hàng tỷ giao dịch hàng năm.

Đây là thực tế: 67% người mua hàng bỏ giỏ hàng do ma sát thanh toán. Việc tích hợp API thanh toán vững chắc tác động trực tiếp đến lợi nhuận của bạn.

Hướng dẫn này sẽ trình bày toàn bộ quy trình tích hợp API 2Checkout. Bạn sẽ tìm hiểu về xác thực, xử lý thanh toán, quản lý đăng ký, xử lý webhook và khắc phục sự cố. Đến cuối cùng, bạn sẽ có một tích hợp thanh toán sẵn sàng sản xuất.

API 2Checkout là gì?

2Checkout (hiện đang hoạt động với tên Verifone Digital Commerce) cung cấp API RESTful để xử lý thanh toán và quản lý đăng ký. API xử lý:

• Thanh toán một lần và định kỳ
• Quản lý khách hàng và sản phẩm
• Theo dõi vòng đời đơn hàng
• Xử lý hoàn tiền và tranh chấp
• Tự động hóa thuế và tuân thủ
• Hỗ trợ đa tiền tệ (hơn 100 loại tiền tệ)

Các tính năng chính

Tổng quan kiến trúc API

2Checkout sử dụng cấu trúc API REST có phiên bản:

https://api.2checkout.com/1/
https://api.2checkout.com/2/

Phiên bản 2 là phiên bản khuyến nghị hiện tại với khả năng quản lý đăng ký và xử lý webhook được cải thiện.

Bắt đầu: Thiết lập xác thực

Bước 1: Tạo tài khoản 2Checkout của bạn

Trước khi truy cập API, bạn cần có tài khoản người bán:

1. Truy cập trang đăng ký 2Checkout (Verifone)
2. Hoàn thành xác minh doanh nghiệp (yêu cầu tài liệu kinh doanh)
3. Chờ phê duyệt (thường là 24-48 giờ)
4. Truy cập Bảng điều khiển của bạn để lấy thông tin xác thực API

Bước 2: Lấy Khóa API

Điều hướng đến Tích hợp > Khóa API trong Bảng điều khiển của bạn:

• Khóa API riêng tư: Dùng để xác thực phía máy chủ (giữ bí mật này)
• Khóa API công khai: Dùng để mã hóa token phía máy khách (an toàn khi công khai)
• Bí mật Webhook: Dùng để xác minh chữ ký webhook

Lưu ý bảo mật: Không bao giờ đưa khóa API vào kiểm soát phiên bản. Sử dụng các biến môi trường:

# .env file
TWOCHECKOUT_PRIVATE_KEY="your_private_key_here"
TWOCHECKOUT_PUBLIC_KEY="your_public_key_here"
TWOCHECKOUT_WEBHOOK_SECRET="your_webhook_secret_here"

Bước 3: Môi trường Sandbox so với Sản xuất

2Checkout cung cấp các môi trường riêng biệt:

Sử dụng thông tin xác thực sandbox trong quá trình phát triển. Chỉ chuyển sang khóa sản xuất khi bạn sẵn sàng xử lý các khoản thanh toán thực.

Bước 4: Các phương pháp xác thực

2Checkout hỗ trợ hai phương pháp xác thực:

Phương pháp 1: Xác thực bằng Khóa API (Khuyến nghị)

Bao gồm khóa riêng tư của bạn trong tiêu đề yêu cầu:

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Phương pháp 2: Xác thực bằng Chữ ký HMAC

Để tăng cường bảo mật, hãy ký các yêu cầu bằng HMAC-SHA256:

const crypto = require('crypto');

function generateSignature(payload, privateKey) {
  const hash = crypto
    .createHmac('sha256', privateKey)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash;
}

// Usage
const payload = { order_id: '12345', amount: 99.99 };
const signature = generateSignature(payload, privateKey);

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Xử lý thanh toán: Các điểm cuối cốt lõi

Tạo một đơn hàng một lần

Xử lý một khoản thanh toán duy nhất với điểm cuối /orders:

const createOrder = async (customerData, productData) => {
  const payload = {
    currency: 'USD',
    customer: {
      email: customerData.email,
      first_name: customerData.firstName,
      last_name: customerData.lastName,
      phone: customerData.phone,
      billing_address: {
        address1: customerData.address,
        city: customerData.city,
        state: customerData.state,
        zip: customerData.zip,
        country: customerData.country
      }
    },
    items: [
      {
        name: productData.name,
        quantity: productData.quantity,
        price: productData.price,
        product_code: productData.sku
      }
    ],
    payment_method: {
      type: 'card',
      card_token: customerData.cardToken // From client-side tokenization
    }
  };

  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Phản hồi dự kiến

{
  "order_id": "ORD-2026-001234",
  "status": "approved",
  "amount": 99.99,
  "currency": "USD",
  "customer_id": "CUST-789456",
  "transaction_id": "TXN-9876543210",
  "created_at": "2026-03-20T10:30:00Z"
}

Xử lý lỗi thanh toán

Luôn triển khai xử lý lỗi đúng cách:

try {
  const result = await createOrder(customer, product);

  if (result.error) {
    // Handle specific error codes
    switch (result.error.code) {
      case 'CARD_DECLINED':
        // Prompt customer for different card
        break;
      case 'INSUFFICIENT_FUNDS':
        // Show appropriate message
        break;
      case 'INVALID_CVV':
        // Request CVV re-entry
        break;
      default:
        // Log and show generic error
        console.error('Payment failed:', result.error);
    }
  }
} catch (error) {
  // Network or server error
  console.error('API request failed:', error);
}

Các mã lỗi phổ biến

Quản lý khách hàng

Quản lý dữ liệu khách hàng là điều cần thiết cho các doanh nghiệp đăng ký và mua hàng lặp lại. 2Checkout cung cấp API khách hàng hoàn chỉnh.

Tạo một khách hàng

const createCustomer = async (customerData) => {
  const payload = {
    email: customerData.email,
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    phone: customerData.phone,
    company: customerData.company,
    billing_address: {
      address1: customerData.address,
      address2: customerData.address2 || '',
      city: customerData.city,
      state: customerData.state,
      zip: customerData.zip,
      country: customerData.country
    },
    shipping_address: customerData.shippingAddress || null,
    tax_exempt: false,
    language: 'en'
  };

  const response = await fetch('https://api.2checkout.com/1/customers', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Phản hồi khách hàng

{
  "customer_id": "CUST-2026-123456",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z",
  "payment_methods": [],
  "subscriptions": [],
  "order_history": []
}

Lấy thông tin chi tiết khách hàng

const getCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'GET',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return await response.json();
};

Cập nhật thông tin khách hàng

const updateCustomer = async (customerId, updates) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return await response.json();
};

Xóa một khách hàng

const deleteCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'DELETE',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY
      }
    }
  );

  return response.status === 204; // No content on success
};

Lưu ý: Việc xóa một khách hàng có đăng ký đang hoạt động hoặc số dư chưa thanh toán sẽ không thành công. Hãy hủy đăng ký trước.

Các mẫu tích hợp nâng cao

Tính bất biến cho các lần thử lại an toàn

Các API thanh toán nên hỗ trợ các yêu cầu bất biến để ngăn chặn các khoản phí trùng lặp:

const createIdempotentOrder = async (payload, idempotencyKey) => {
  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json',
      'X-Idempotency-Key': idempotencyKey // Unique per order
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

// Generate unique key per order (store in your database)
const idempotencyKey = `order_${userId}_${Date.now()}`;

Nếu yêu cầu hết thời gian chờ nhưng 2Checkout đã xử lý, việc thử lại với cùng một khóa sẽ trả về kết quả ban đầu thay vì tính phí hai lần.

Xử lý 3D Secure 2.0 (Tuân thủ EU)

Đối với khách hàng châu Âu, xác thực 3D Secure 2.0 là bắt buộc theo PSD2:

const createOrderWith3DS = async (payload) => {
  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...payload,
      three_ds: {
        enabled: true,
        challenge_required: 'preferred', // or 'mandatory' for EU
        notification_url: 'https://your-site.com/3ds-callback'
      }
    })
  });

  const result = await response.json();

  // Handle 3DS redirect
  if (result.three_ds_redirect_url) {
    // Redirect customer to their bank for authentication
    res.redirect(result.three_ds_redirect_url);
  }

  return result;
};

Định giá đa tiền tệ

Hiển thị giá bằng nội tệ trong khi thanh toán bằng tiền tệ cơ sở của bạn:

const getLocalizedPrice = async (basePrice, targetCurrency) => {
  const response = await fetch(
    `https://api.2checkout.com/1/rates?from=USD&to=${targetCurrency}`,
    {
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY
      }
    }
  );

  const rates = await response.json();
  return basePrice * rates.rate;
};

// Usage
const eurPrice = await getLocalizedPrice(99.99, 'EUR');
console.log(`Price: EUR ${eurPrice.toFixed(2)}`);

Tính toán prorate cho việc nâng cấp đăng ký

Khi khách hàng nâng cấp giữa chu kỳ, hãy tính toán các khoản phí prorate:

const upgradeSubscription = async (subscriptionId, newPlanId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/upgrade`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        plan_id: newPlanId,
        proration: 'immediate', // Charge difference now
        invoice_proration: true  // Show line item on invoice
      })
    }
  );

  return await response.json();
};

Khắc phục sự cố phổ biến

Vấn đề: Webhook không đến

Triệu chứng: Đơn hàng được xử lý nhưng hệ thống của bạn không cập nhật.

Chẩn đoán:

// Check webhook delivery logs in 2Checkout dashboard
// Look for failed delivery attempts or non-200 responses

Giải pháp:

1. Xác minh điểm cuối trả về 200 OK trong vòng 5 giây
2. Kiểm tra tính hợp lệ của chứng chỉ SSL (phải là HTTPS)
3. Cho phép các dải IP của 2Checkout trong tường lửa của bạn
4. Xem lại logic xác minh chữ ký webhook
5. Kiểm thử với trình giả lập webhook trước khi đưa vào sản xuất

Vấn đề: Thanh toán thử thất bại trong Sandbox

Triệu chứng: Tất cả các thẻ thử nghiệm bị từ chối trong môi trường sandbox.

Giải pháp:

1. Xác nhận đang sử dụng khóa API sandbox (không phải sản xuất)
2. Xác minh URL cơ sở sandbox: https://sandbox.2checkout.com/api/
3. Sử dụng số thẻ thử nghiệm chính xác (xem phần Kiểm thử)
4. Kiểm tra trạng thái tài khoản sandbox (có thể hết hạn sau khi không hoạt động)

Vấn đề: Gia hạn đăng ký thất bại âm thầm

Triệu chứng: Các đăng ký hiển thị đang hoạt động nhưng việc gia hạn không được xử lý.

Chẩn đoán:

// Query subscription payment history
const history = await fetch(
  `https://api.2checkout.com/1/subscriptions/${subId}/payments`,
  { headers: { 'X-Api-Key': privateKey } }
);

Giải pháp:

1. Kiểm tra ngày hết hạn phương thức thanh toán của khách hàng
2. Xem lại cài đặt dunning trong Bảng điều khiển
3. Xác minh việc gửi webhook cho subscription.payment_failed
4. Xác nhận cờ auto_renew đã được bật

Vấn đề: Sai lệch chuyển đổi tiền tệ

Triệu chứng: Số tiền bị tính khác với chuyển đổi dự kiến.

Nguyên nhân: 2Checkout sử dụng tỷ giá hối đoái hàng ngày, có thể biến động.

Giải pháp:

• Hiển thị chuyển đổi "xấp xỉ" với tuyên bố từ chối trách nhiệm
• Khóa tỷ giá khi tạo giỏ hàng với thời hạn 15 phút
• Lưu trữ giao dịch bằng nội tệ của khách hàng

Vấn đề: Lỗi AVS (Xác minh địa chỉ)

Triệu chứng: Thẻ hợp lệ bị từ chối do không khớp địa chỉ.

Giải pháp:

1. Sử dụng tính năng tự động hoàn thành địa chỉ (Google Places, Lob)
2. Yêu cầu nhập mã ZIP/bưu điện khi thanh toán
3. Triển khai AVS mềm (cảnh báo thay vì từ chối)
4. Cho phép khách hàng cập nhật địa chỉ thanh toán

Quản lý đăng ký

2Checkout nổi bật về thanh toán định kỳ. Dưới đây là cách quản lý đăng ký:

Tạo một đăng ký

const createSubscription = async (customerId, planId) => {
  const payload = {
    customer_id: customerId,
    plan_id: planId,
    start_date: new Date().toISOString(),
    billing_cycle: 'monthly', // or 'annual', 'weekly'
    payment_method: {
      type: 'card',
      card_token: 'tok_card_tokenized'
    },
    options: {
      trial_days: 14, // Optional free trial
      auto_renew: true
    }
  };

  const response = await fetch('https://api.2checkout.com/1/subscriptions', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Phản hồi đăng ký

{
  "subscription_id": "SUB-2026-567890",
  "status": "active",
  "plan_id": "PLAN-PREMIUM-MONTHLY",
  "customer_id": "CUST-789456",
  "current_period_start": "2026-03-20T00:00:00Z",
  "current_period_end": "2026-04-20T00:00:00Z",
  "trial_end": "2026-04-03T00:00:00Z",
  "amount": 29.99,
  "currency": "USD"
}

Cập nhật một đăng ký

Thay đổi gói, cập nhật phương thức thanh toán hoặc sửa đổi số lượng:

const updateSubscription = async (subscriptionId, updates) => {
  const payload = {
    ...updates
    // Examples:
    // plan_id: 'PLAN-ENTERPRISE-MONTHLY',
    // quantity: 5,
    // payment_method: { card_token: 'new_token' }
  };

  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );

  return await response.json();
};

Hủy một đăng ký

const cancelSubscription = async (subscriptionId, reason = '') => {
  const payload = {
    cancel_at_period_end: false, // true = cancel after current period, false = immediate
    reason: reason
  };

  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/cancel`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );

  return await response.json();
};

Tích hợp Webhook: Xử lý sự kiện theo thời gian thực

Webhook thông báo cho hệ thống của bạn về các sự kiện thanh toán mà không cần thăm dò. Điều này rất quan trọng đối với việc gia hạn đăng ký, thanh toán thất bại và hoàn tiền.

Bước 1: Cấu hình điểm cuối Webhook

Trong Bảng điều khiển 2Checkout của bạn:

1. Điều hướng đến Tích hợp > Webhook
2. Thêm URL điểm cuối của bạn (phải sử dụng HTTPS)
3. Chọn các sự kiện để đăng ký
4. Lưu và ghi chú Bí mật Webhook của bạn

Bước 2: Tạo trình xử lý Webhook

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/2checkout', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // Verify webhook signature
  const isValid = verifyWebhookSignature(payload, signature, process.env.TWOCHECKOUT_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(payload.toString());

  // Route to appropriate handler
  switch (event.type) {
    case 'order.created':
      await handleOrderCreated(event.data);
      break;
    case 'order.approved':
      await handleOrderApproved(event.data);
      break;
    case 'order.declined':
      await handleOrderDeclined(event.data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(event.data);
      break;
    case 'subscription.renewed':
      await handleSubscriptionRenewed(event.data);
      break;
    case 'subscription.cancelled':
      await handleSubscriptionCancelled(event.data);
      break;
    case 'refund.processed':
      await handleRefundProcessed(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  // Acknowledge receipt
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Các sự kiện Webhook quan trọng

Các phương pháp hay nhất về Webhook

1. Luôn xác minh chữ ký - Ngăn chặn webhook giả mạo
2. Trả về 200 OK nhanh chóng - 2Checkout thử lại khi phản hồi không phải 200
3. Xử lý không đồng bộ - Xếp hàng đợi các sự kiện để xử lý nền
4. Triển khai tính bất biến - Xử lý các lần gửi webhook trùng lặp
5. Ghi nhật ký mọi thứ - Gỡ lỗi các tranh chấp thanh toán bằng nhật ký có dấu thời gian

Kiểm thử tích hợp của bạn

Sử dụng môi trường Sandbox

Sandbox của 2Checkout cho phép bạn kiểm thử mà không phát sinh phí thực:

// Use sandbox base URL
const BASE_URL = 'https://sandbox.2checkout.com/api/1';

// Test card numbers
const TEST_CARDS = {
  APPROVED: '4111111111111111',
  DECLINED: '4000000000000002',
  INSUFFICIENT_FUNDS: '4000000000009995',
  EXPIRED_CARD: '4000000000000069'
};

// Test addresses
const TEST_ADDRESS = {
  country: 'US',
  zip: '90210' // Triggers AVS checks
};

Kiểm thử Webhook cục bộ

Sử dụng ngrok để công khai máy chủ cục bộ của bạn:

# Install ngrok
npm install -g ngrok

# Start your server on port 3000
node server.js

# Expose to internet
ngrok http 3000

# Copy the ngrok URL to 2Checkout webhook settings

Apidog để kiểm thử API

Apidog hợp lý hóa việc kiểm thử API 2Checkout:

1. Nhập Thông số kỹ thuật OpenAPI - Tải định nghĩa API của 2Checkout
2. Tạo Kịch bản kiểm thử - Xây dựng các bộ sưu tập cho từng điểm cuối
3. Mô phỏng Phản hồi - Kiểm thử mà không cần gọi API
4. Xác thực Webhook - Kiểm tra cấu trúc tải trọng
5. Chia sẻ với Nhóm - Cộng tác trong kiểm thử tích hợp

Tạo các biến môi trường cho khóa sandbox và sản xuất, sau đó chuyển đổi ngữ cảnh chỉ với một cú nhấp chuột.

Danh sách kiểm tra triển khai sản xuất

Trước khi chính thức hoạt động:

• [ ] Chuyển từ khóa API sandbox sang sản xuất
• [ ] Cập nhật URL cơ sở thành https://api.2checkout.com/
• [ ] Bật xác minh chữ ký webhook
• [ ] Thiết lập giám sát cho các khoản thanh toán thất bại
• [ ] Cấu hình logic thử lại cho các lỗi tạm thời
• [ ] Kiểm thử quy trình hoàn tiền và tranh chấp
• [ ] Xác minh tuân thủ PCI DSS (sử dụng mã hóa token)
• [ ] Bật 3D Secure 2.0 cho khách hàng EU
• [ ] Thiết lập ghi nhật ký cho dấu vết kiểm toán
• [ ] Tạo tài liệu hướng dẫn vận hành (runbook) cho các vấn đề thanh toán

Giám sát và cảnh báo

Theo dõi các chỉ số này:

// Example: Payment success rate
const successRate = approvedOrders / totalOrders * 100;

if (successRate < 95) {
  // Alert payment team
  sendAlert('Payment success rate dropped below 95%');
}

// Track specific error codes
const errorBreakdown = errors.reduce((acc, err) => {
  acc[err.code] = (acc[err.code] || 0) + 1;
  return acc;
}, {});

// Alert on spike in specific errors
if (errorBreakdown['CARD_DECLINED'] > threshold) {
  sendAlert('Spike in card declines detected');
}

Các trường hợp sử dụng thực tế

Tích hợp cửa hàng thương mại điện tử

Một nhà bán lẻ thời trang đã tích hợp 2Checkout để xử lý thanh toán toàn cầu. Kết quả:

• Tự động hỗ trợ hơn 100 loại tiền tệ
• Giảm 23% tỷ lệ bỏ giỏ hàng
• Tự động xử lý tuân thủ VAT của EU
• Xử lý hơn 2 triệu đô la trong năm đầu tiên

Việc triển khai mất 3 tuần, ban đầu sử dụng các trang thanh toán được lưu trữ của 2Checkout, sau đó chuyển sang tích hợp API trực tiếp để có UX tùy chỉnh.

Doanh nghiệp đăng ký SaaS

Một SaaS quản lý dự án đã sử dụng đăng ký 2Checkout:

• Quản lý hơn 5.000 đăng ký đang hoạt động
• Xử lý prorate cho việc nâng cấp gói
• Tự động hóa nhắc nhở thanh toán cho các lần gia hạn thất bại
• Giảm 15% tỷ lệ khách hàng bỏ dịch vụ với các lần thử lại thông minh

Tính năng chính: Kiểm soát quyền truy cập dựa trên Webhook. Khi subscription.renewed đến, ngay lập tức gia hạn quyền truy cập của người dùng. Khi subscription.cancelled, lên lịch thu hồi quyền truy cập.

Kết luận

API 2Checkout cung cấp mọi thứ cần thiết để xử lý thanh toán và quản lý đăng ký. Những điểm chính cần lưu ý:

• Sử dụng môi trường sandbox cho tất cả quá trình phát triển và kiểm thử
• Triển khai xác minh chữ ký HMAC cho webhook
• Xử lý lỗi một cách linh hoạt với việc xử lý mã lỗi cụ thể
• Kiểm thử kỹ lưỡng các luồng đăng ký (dùng thử, gia hạn, hủy)
• Giám sát các chỉ số thanh toán trong môi trường sản xuất
• Sử dụng Apidog để hợp lý hóa việc kiểm thử API và cộng tác nhóm

Phần Câu hỏi thường gặp

API 2Checkout là gì?

API 2Checkout (nay là Verifone) là một giao diện RESTful để xử lý thanh toán, quản lý đăng ký, xử lý hoàn tiền và tự động hóa các giao dịch thương mại điện tử. Nó hỗ trợ tải trọng JSON, xác thực HMAC và webhook theo thời gian thực.

2Checkout có giống Verifone không?

Có. 2Checkout đã được Verifone mua lại vào năm 2020 và đổi tên thành Verifone Digital Commerce. Các điểm cuối API và chức năng vẫn giữ nguyên, mặc dù một số tài liệu tham khảo Verifone.

Làm cách nào để lấy khóa API 2Checkout của tôi?

Đăng nhập vào Bảng điều khiển 2Checkout của bạn, điều hướng đến Tích hợp > Khóa API, và tạo khóa mới. Bạn sẽ nhận được khóa riêng tư (phía máy chủ) và khóa công khai (mã hóa token phía máy khách).

2Checkout có môi trường sandbox không?

Có. Sử dụng https://sandbox.2checkout.com/api/ để kiểm thử. Tạo một tài khoản sandbox riêng để lấy khóa API kiểm thử và xử lý các giao dịch kiểm thử mà không phát sinh phí thực.

2Checkout hỗ trợ những phương thức thanh toán nào?

2Checkout hỗ trợ thẻ tín dụng (Visa, Mastercard, Amex, Discover), PayPal, Apple Pay, Google Pay, chuyển khoản ngân hàng và các phương thức thanh toán địa phương trên hơn 100 quốc gia.

Làm cách nào để xử lý webhook một cách an toàn?

Luôn xác minh tiêu đề X-Webhook-Signature bằng HMAC-SHA256 với bí mật webhook của bạn. Xử lý các sự kiện không đồng bộ và trả về 200 OK ngay lập tức để ngăn chặn các lần thử lại.

Điều gì xảy ra khi thanh toán đăng ký thất bại?

2Checkout gửi một webhook subscription.payment_failed. Triển khai logic thử lại (thường là 3 lần thử trong 7 ngày) và gửi webhook subscription.cancelled nếu tất cả các lần thử lại đều thất bại.

2Checkout có tuân thủ PCI DSS không?

Có, 2Checkout được chứng nhận PCI DSS Cấp độ 1. Sử dụng mã hóa token phía máy khách để tránh xử lý dữ liệu thẻ thô, điều này giảm phạm vi tuân thủ PCI của bạn.

Tôi có thể kiểm thử đăng ký trong sandbox không?

Có. Sandbox hỗ trợ kiểm thử toàn bộ vòng đời đăng ký bao gồm dùng thử, gia hạn, nâng cấp, hạ cấp và hủy bỏ. Sử dụng thẻ kiểm thử 4111111111111111 cho các khoản thanh toán thành công.

Làm cách nào để xử lý hoàn tiền qua API?

Gửi yêu cầu POST tới /refunds với ID đơn hàng và số tiền hoàn lại. 2Checkout xử lý hoàn tiền một phần hoặc toàn bộ và gửi webhook refund.processed khi hoàn tất.