Node.js SDK

@tapayadot/checkout là SDK TypeScript phía máy chủ cho Tapaya Checkout. Tài liệu tham khảo này mô tả phiên bản 0.3.0.

npm install @tapayadot/checkout

import { Tapaya } from '@tapayadot/checkout';

const tapaya = new Tapaya();

Client đọc TAPAYA_SECRET_KEY từ môi trường máy chủ. Gói này cũng chứa trình tải cho trình duyệt (browser loader) và React hook cho Embedded Checkout. Trình tải lấy Tapaya.js 0.2.0 từ https://js.tapaya.com/checkout/0.2.0/checkout.js; phiên bản script trình duyệt độc lập với phiên bản của gói này. Gói không tải tệp .env. Hãy giữ key và client trong mã chỉ chạy trên máy chủ. Hướng dẫn Hosted Checkout trình bày cách tạo đơn hàng, chuyển hướng khách hàng và xác minh thanh toán.

Cấu hình

const tapaya = new Tapaya(apiKey, {
	environment: 'sandbox',
	timeoutMs: 30_000,
	maxRetries: 2,
})

Để dùng một endpoint API tùy chỉnh, hãy đặt TAPAYA_BASE_URL=https://api.example.com trên máy chủ của bạn. baseUrl được chỉ định tường minh sẽ được ưu tiên hơn TAPAYA_BASE_URL; cả hai đều ghi đè lựa chọn môi trường.

Client xác định API key và URL API một lần, khi được khởi tạo. Hãy dùng key khớp với môi trường đã chọn. URL API, URL trả về và URL Hosted Checkout phải dùng HTTPS, ngoại trừ việc HTTP được phép cho localhost, 127.0.0.1 và [::1] khi không ở NODE_ENV=production. SDK kiểm tra NODE_ENV hiện tại mỗi lần kiểm tra tính hợp lệ của một URL HTTP cục bộ.

timeoutMs phải là số nguyên từ 1 đến 2.147.483.647. maxRetries phải là một số nguyên an toàn không âm. Số lần thử lại mặc định cho phép tối đa ba lần thử cho mỗi lệnh gọi, mỗi lần có thời gian chờ riêng.

Mỗi phương thức cũng chấp nhận signal, timeoutMs và maxRetries cho một yêu cầu riêng lẻ:

const current = await tapaya.checkout.sessions.get(sessionId, {
	signal: request.signal,
	timeoutMs: 5_000,
})

Khi signal bị hủy (abort), phương thức dừng ngay lập tức, không thử lại, và bị từ chối (reject) với lý do của signal.

Phiên Checkout

Chọn merchant

Ở chế độ merchant, checkout key của merchant tự xác định merchant của nó. Dùng new Tapaya() mà không cần merchantToken.

Ở chế độ nền tảng, một Secret key của tổ chức phục vụ nhiều merchant. Mọi yêu cầu đều cần merchant token; không có merchant mặc định, và yêu cầu không có token sẽ thất bại với TapayaAuthenticationError. Sao chép token từ bảng merchant trong Cài đặt Checkout và truyền token của đơn hàng khi tạo cũng như khi truy xuất phiên:

const tapaya = new Tapaya(process.env.TAPAYA_SECRET_KEY)
const session = await tapaya.checkout.sessions.create(params, {
	merchantToken: order.merchantToken,
	idempotencyKey: order.checkoutAttemptKey,
})
const current = await tapaya.checkout.sessions.get(session.id, {
	merchantToken: order.merchantToken,
})

Bạn cũng có thể đặt giá trị mặc định bằng new Tapaya(key, { merchantToken }). Token áp dụng cho các lệnh gọi Hosted Checkout và thanh toán nhúng. Tapaya từ chối các token không thuộc tổ chức của key. Với key của merchant, token là tùy chọn và phải chỉ đúng merchant của chính key đó. Xem Xác thực Checkout.

Tạo một phiên

tapaya.checkout.sessions.create(params, options?) yêu cầu merchantOrderId, amount và currency. merchantOrderId là mã tham chiếu đơn hàng của bạn, dài từ 1 đến 200 ký tự. Một đơn hàng chỉ có thể được thanh toán một lần; một phiên mới cho đơn hàng chưa thanh toán sẽ thay thế phiên trước đó. Xem Một khoản thanh toán cho mỗi đơn hàng. amount là tổng tiền cuối cùng, bao gồm thuế và phí giao hàng, là một số nguyên từ 1 đến 2.147.483.647 đơn vị nhỏ nhất của tiền tệ. currency là mã ISO 4217 gồm ba chữ cái. Tapaya lưu và trả về mã này ở dạng chữ hoa.

Các trường tùy chọn:

Trước khi gửi, SDK kiểm tra kiểu dữ liệu, các trường bắt buộc, số tiền là số nguyên, định dạng loại tiền tệ và độ dài email tối đa 254 ký tự. URL trả về phải là URL HTTPS tuyệt đối, với ngoại lệ HTTP cục bộ được mô tả trong phần Cấu hình. Tapaya kiểm tra các quy tắc nghiệp vụ như định dạng email, giới hạn địa chỉ và mã quốc gia, và báo lỗi dưới dạng TapayaInvalidRequestError. Xem Phiên Checkout để biết quy tắc của các trường, tổng tiền thuế và giới hạn địa chỉ khách hàng.

Truy xuất một phiên

tapaya.checkout.sessions.get(id, options?) trả về trạng thái hiện tại của một phiên. ID phải là chuỗi không rỗng, dài tối đa 200 ký tự; . và .. không hợp lệ. SDK mã hóa URL cho ID.

Việc tạo và truy xuất phiên Hosted Checkout trả về một HostedCheckoutSession. Với các phương thức nhúng prepare(), verify() và configuration(), xem Embedded Checkout.

Các trường của phiên Hosted Checkout:

Hãy xử lý các giá trị status và paymentStatus không xác định, ví dụ bằng cách coi chúng là chưa thanh toán. Chỉ có paymentStatus: 'successful' mới chứng minh việc thanh toán.

Thẻ bị từ chối là một kết quả thanh toán, không phải lỗi. Phiên vẫn ở trạng thái open với paymentStatus: 'failed', và khách hàng có thể thử lại. Trong khi Tapaya xác nhận một kết quả chưa chắc chắn, phiên vẫn ở trạng thái open và unpaid. Hiện chưa có webhook; hãy thăm dò get() từ một tác vụ đối soát.

Idempotency và thử lại

Mọi yêu cầu tạo phiên đều gửi một Idempotency-Key. Key được chỉ định tường minh phải là chuỗi không rỗng gồm các ký tự ASCII in được. Tapaya chấp nhận tối đa 250 ký tự. Nếu bạn bỏ qua idempotencyKey, SDK sẽ tạo một key ngẫu nhiên cho mỗi lệnh gọi. Trong cùng lệnh gọi đó, các lần thử lại dùng lại key này, nên một lần thử lại không bao giờ tạo phiên thứ hai.

Để an toàn giữa các lệnh gọi riêng biệt và khi tiến trình khởi động lại, hãy lưu một key cùng với đơn hàng và truyền key đó mỗi khi bạn tạo phiên cho lần thử đó, với cùng các tham số. Tapaya sẽ trả về phiên ban đầu thay vì tạo phiên mới. Chỉ dùng key mới cho một lần thử checkout mới, không bao giờ dùng để thử lại khi kết quả chưa chắc chắn.

Một yêu cầu tạo phiên Hosted Checkout lặp lại sẽ trả về cùng phiên đó với status và paymentStatus hiện tại. Hãy gọi tapaya.checkout.sessions.get(session.id) để kiểm tra lại trạng thái trước khi hoàn tất đơn hàng.

Với cùng một merchant, các lần thử lại Hosted Checkout phải dùng cùng phần thân yêu cầu và cùng chế độ thông tin xác thực: checkout key của merchant hoặc Secret key của tổ chức. Thay đổi một trong hai sẽ trả về HTTP 409 với mã API-0025. Việc chuyển đổi chế độ thông tin xác thực gây xung đột ngay cả khi phần thân giống hệt, vì mỗi chế độ dùng cài đặt chuyển hướng riêng.

SDK thử lại cả hai phương thức sau lỗi mạng, hết thời gian chờ và HTTP 429, 502, 503 và 504. SDK cũng thử lại một yêu cầu tạo phiên thất bại với HTTP 409 API-0024. Các lần thử lại gửi cùng key và phần thân, nên chúng trả về phiên ban đầu. SDK chờ giữa các lần thử theo cơ chế exponential backoff có jitter, và tuân theo Retry-After tối đa 10 giây. Khi Tapaya yêu cầu chờ lâu hơn, SDK ngừng thử lại và ném lỗi tương ứng với mã trạng thái HTTP đó: TapayaRateLimitError cho 429, TapayaServerError cho 502, 503 hoặc 504, hoặc TapayaConflictError cho 409. Chỉ TapayaRateLimitError cung cấp khoảng chờ được yêu cầu qua retryAfterMs; các lỗi HTTP khác giữ header Retry-After trong headers. Mọi lần thử lại dùng chung hạn mức maxRetries. Đặt maxRetries: 0 để tắt thử lại.

Không bao giờ chuyển sang key mới để vượt qua một kết quả chưa chắc chắn. Yêu cầu ban đầu có thể đã tạo một phiên; với key mới và cùng đơn hàng chưa thanh toán, phiên mới sẽ thay thế phiên đó.

Lỗi

Các lớp lỗi của SDK kế thừa TapayaError. Một yêu cầu bị hủy sẽ bị từ chối (reject) với lý do của signal.

Các lỗi HTTP mang status, code lỗi của Tapaya, fieldErrors ({ field, message, code? }[]), các headers của phản hồi và requestId từ header X-Request-Id, nếu có. Backend hiện chưa đặt header này. Hãy đưa ID phiên hoặc mã tham chiếu đơn hàng và thời điểm gửi yêu cầu vào yêu cầu hỗ trợ, kèm theo requestId nếu có. TapayaResponseError cũng mang status, headers và requestId. TapayaValidationError cũng mang fieldErrors, với field được đặt thành đường dẫn tham số, ví dụ customer.email.

import { TapayaConnectionError, TapayaError, TapayaValidationError } from '@tapayadot/checkout'

try {
	const session = await tapaya.checkout.sessions.create(params, { idempotencyKey })
	return Response.redirect(session.url, 303)
} catch (error) {
	if (error instanceof TapayaValidationError) {
		console.error(error.fieldErrors)
	} else if (error instanceof TapayaConnectionError) {
		// The outcome is unknown. Retry later with the same idempotency key.
	} else if (error instanceof TapayaError) {
		console.error(error.message)
	}
	throw error
}

Các kiểu được export

Gói export TapayaEnvironment, TapayaOptions, RequestOptions, CreateSessionOptions, CreateCheckoutSessionParams, CheckoutSessions, CheckoutSession, CheckoutSessionStatus, CheckoutPaymentStatus, CheckoutItem, TaxBreakdownEntry, CheckoutCustomer, CheckoutContactAddress và TapayaFieldError.

VERSION chứa phiên bản SDK. Các kiểu dùng named import với import type:

import type { CheckoutSession, CreateCheckoutSessionParams } from '@tapayadot/checkout';

Nâng cấp từ 0.2.x

• Trình tải cho trình duyệt tải Tapaya.js 0.2.0, phiên bản hỗ trợ Apple Pay và Google Pay. Trình tải từ chối một script 0.1.x đã được tải trước đó. Hãy cập nhật mọi thẻ script do bạn quản lý thành https://js.tapaya.com/checkout/0.2.0/checkout.js.
• environment: 'production' hỗ trợ cả Hosted Checkout lẫn thanh toán nhúng. configuration() trả về environment: 'production' cùng các key của cổng thanh toán chính thức.
• Khi không chỉ định môi trường tường minh hoặc TAPAYA_ENVIRONMENT, key tapaya_live_ sẽ chọn production. Thông tin xác thực không khớp với môi trường đã chọn sẽ gây lỗi khi khởi tạo client. baseUrl vẫn ghi đè URL API.