Tích hợp API

Backend của bạn tạo một phiên Checkout cho mỗi đơn hàng và truy xuất phiên đó để xác minh thanh toán.

Với Node.js, SDK @tapayadot/checkout cung cấp các phương thức có kiểu create() và get() cho các endpoint này. SDK mặc định đọc TAPAYA_SECRET_KEY. Các ví dụ HTTP trên trang này truyền TAPAYA_CHECKOUT_API_KEY một cách tường minh.

Xác thực

Mọi lệnh gọi Checkout đều là giao tiếp giữa máy chủ với máy chủ và gửi key dưới dạng bearer token:

Authorization: Bearer <key>

Chọn chế độ phù hợp với bên vận hành backend. Dù dùng key nào, hãy giữ nó trên máy chủ; xem Bảo mật Checkout.

Chế độ merchant

Dùng chế độ này khi backend phục vụ một cửa hàng. Tạo một checkout key của merchant trong Cài đặt Checkout: mở merchant và chọn Create merchant key. Key bắt đầu bằng tapaya_test_ trong sandbox hoặc tapaya_live_ trong production và chỉ ứng với đúng merchant đó.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token là tùy chọn ở chế độ này. Nếu bạn gửi header này, nó phải chỉ đúng merchant đó.

Platform chỉ hiển thị key một lần và chỉ lưu bản hash. Để xoay vòng key, hãy tạo key thay thế trước khi thu hồi key cũ. Việc thu hồi một key không ảnh hưởng đến các key khác của merchant, các key của tổ chức hoặc các client secret đã được cấp cho trình duyệt.

Chế độ nền tảng

Dùng chế độ này khi một backend hoạt động thay mặt nhiều merchant, chẳng hạn một sàn thương mại điện tử hoặc nền tảng giao đồ ăn. Gửi Secret key của tổ chức từ trang API Keys và token của merchant trong mọi yêu cầu:

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

Không có merchant mặc định. Yêu cầu không có header này sẽ trả về HTTP 401. Merchant phải thuộc tổ chức của key. Sao chép merchant token từ bảng merchant trong Cài đặt Checkout. Token dùng để xác định merchant; nó không phải là thông tin bí mật.

Secret key của tổ chức chính là thông tin xác thực được gọi là Server Secret Token trong tài liệu Platform API. Checkout yêu cầu tiền tố Bearer. Các endpoint khác của Platform API nhận token trực tiếp. Onboarding merchant và quản lý tổ chức dùng Platform API.

Phần thân yêu cầu không chấp nhận merchantId.

Môi trường

Đặt TAPAYA_CHECKOUT_API_URL thành origin API của môi trường bạn dùng. Cả Hosted Checkout lẫn thanh toán nhúng đều khả dụng trên production. Mỗi merchant phải hoàn tất onboarding, được đơn vị xử lý thanh toán trực tuyến phê duyệt và có cổng thanh toán đã được cấu hình. Kiểm tra trạng thái sẵn sàng của merchant trong Cài đặt Checkout. Dùng nguyên URL phiên Hosted Checkout được trả về.

Phiên Checkout

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Quyền quản lý đơn hàng và thanh toán

ID phiên checkout xác định một phiên Hosted Checkout. merchantOrderId của phiên liên kết nó với đơn hàng của bạn, còn paymentReference xác định lần thử xác nhận gần nhất. Hãy lưu ID phiên cùng với đơn hàng để bạn có thể truy xuất kết quả ngay cả khi khách hàng đóng trình duyệt.

Trang Hosted Checkout dùng các endpoint công khai riêng để tải và xác nhận phiên. ID phiên của trang là thông tin xác thực truy cập cho các endpoint đó. Một tích hợp của merchant xác minh thanh toán qua endpoint merchant yêu cầu đăng nhập.

Một khoản thanh toán cho mỗi đơn hàng

Hosted Checkout và Embedded Checkout dùng chung một công cụ xử lý thanh toán. Một merchant có thể có tối đa một khoản thanh toán thành công cho mỗi merchantOrderId. ID đơn hàng có phạm vi theo merchant, nên các merchant khác nhau, kể cả khi thuộc cùng một tổ chức, có thể dùng cùng ID.

• Việc tạo phiên cho một đơn hàng chưa thanh toán sẽ thay thế phiên chưa thanh toán trước đó. URL cũ báo expired và không thể nhận thanh toán nữa.
• Việc tạo phiên cho một đơn hàng đã được thanh toán, hoặc đang có khoản thanh toán được xử lý, sẽ trả về HTTP 409.
• Sau khi bị từ chối, khách hàng có thể thử thẻ hoặc ví khác trong cùng phiên. Việc gửi lại cùng một token thẻ không bao giờ trừ tiền hai lần.
• Tapaya thiết lập chính sách 3-D Secure và luôn cố gắng thực hiện xác thực.

Idempotency và lỗi

Việc tạo phiên yêu cầu một Idempotency-Key không rỗng, dài tối đa 250 ký tự. Với cùng một merchant:

Thẻ bị từ chối là một kết quả thanh toán, không phải bằng chứng cho thấy yêu cầu HTTP đã thất bại.