### Onboarding merchant của bạn [#onboard-your-merchant] Hoàn tất [onboarding merchant](/merchants/onboarding) với tính năng thanh toán trực tuyến, hoặc cả thanh toán trực tuyến lẫn thanh toán tại cửa hàng. Một merchant chỉ dùng Checkout không cần máy thanh toán. Cung cấp website của cửa hàng và thông tin kinh doanh trực tuyến, rồi chờ đơn vị xử lý thanh toán phê duyệt. Chỉ riêng việc tạo bản ghi merchant hoặc API key không kích hoạt thanh toán. Mở **Checkout** trong [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Các merchant yêu cầu thanh toán trực tuyến tự động xuất hiện, kể cả những merchant đang chờ phê duyệt. Tiếp tục khi merchant ở trạng thái **Ready**. Mở **Settings** của merchant. Trong **Merchant API key redirects**, thêm cửa hàng của bạn vào **Allowed websites** và đặt URL thành công và URL hủy mặc định. Một nền tảng dùng Secret key của tổ chức sẽ đặt các giá trị này trong **Organization defaults**. Các ví dụ dùng `https://shop.example`. Xem [Cài đặt Checkout](/online/integration/checkout_settings) để biết về ví và thương hiệu. ### Lưu key trên máy chủ [#store-your-key-on-the-server] Trong **Settings** của merchant, chọn **Create merchant key** và sao chép key `tapaya_test_…`. Key chỉ hiển thị một lần. Chỉ giữ key trong cấu hình phía máy chủ. Key không bao giờ được nằm trong mã trình duyệt hoặc hệ thống quản lý mã nguồn. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` SDK tự động đọc `TAPAYA_SECRET_KEY` và `TAPAYA_ENVIRONMENT`. Các ví dụ HTTP bên dưới dùng `TAPAYA_CHECKOUT_API_URL`. Hãy nạp các biến này vào tiến trình máy chủ của bạn; SDK không tải tệp `.env`. Gửi key dưới dạng `Authorization: Bearer `. Key của merchant tự xác định merchant của nó, nên không cần header nào khác. Một nền tảng phục vụ nhiều merchant sẽ dùng Secret key của tổ chức và gửi `X-Tapaya-Merchant-Token` trong mọi yêu cầu. Xem [Xác thực Checkout](/online/integration/api_integration#authentication). ### Tạo một phiên Checkout [#create-a-checkout-session] Khi khách hàng nhấn **Checkout** trong cửa hàng của bạn, hãy tính tổng tiền cuối cùng trên máy chủ, lưu đơn hàng cùng một key duy nhất cho lần thử thanh toán và tạo phiên. `merchantOrderId` là bắt buộc, và một đơn hàng chỉ có thể được thanh toán một lần. Số tiền được tính theo đơn vị nhỏ nhất của tiền tệ, nên `12100` là 121,00 EUR. Với Node.js 22.13.0 trở lên, hãy cài đặt ESM SDK trước khi dùng ví dụ **Node.js SDK**: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': order.checkoutAttemptKey, }, body: JSON.stringify({ merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Nếu yêu cầu hết thời gian chờ, hãy thử lại với **cùng** key và phần thân. API sẽ trả về lại phiên ban đầu thay vì tạo phiên thứ hai. ### Chuyển hướng khách hàng [#redirect-the-customer] Lưu `session.id` cùng với đơn hàng, sau đó chuyển trình duyệt đến `session.url` bằng HTTP 303. Dùng URL đúng như được trả về. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya hiển thị tóm tắt đơn hàng và biểu mẫu thanh toán bảo mật, đồng thời xử lý tokenization, 3-D Secure và việc trừ tiền. Sau khi bị từ chối, khách hàng có thể thử thẻ khác trên cùng trang. Các phiên nhận thanh toán mới trong 30 phút. ### Xác minh thanh toán trên máy chủ của bạn [#verify-the-payment-on-your-server] Khi khách hàng đến URL thành công hoặc URL hủy của bạn, hãy truy xuất phiên bằng Secret key và so sánh với đơn hàng đã lưu. Chỉ riêng một lần chuyển hướng không bao giờ chứng minh việc thanh toán. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` Với cả hai cách tích hợp, hãy so sánh kết quả với đơn hàng đã lưu trước khi hoàn tất đơn hàng: ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Nếu trạng thái vẫn là `unpaid` hoặc việc truy xuất thất bại, hãy giữ ID phiên và kiểm tra lại. Hiện chưa có webhook, vì vậy hãy chạy một tác vụ đối soát cho những khách hàng đóng tab trước khi quay lại.