Dịch vụ thanh toán là cầu nối giữa website và nhà cung cấp thanh toán (cổng thanh toán, ví điện tử, dịch vụ thông báo biến động số dư). Khi một dịch vụ được kích hoạt, trang giỏ hàng hiển thị nút Thanh toán qua <tên dịch vụ>, khách bấm vào nút để thanh toán và kết quả được nhà cung cấp gửi về website để cập nhật trạng thái đơn hàng.
Bài viết đi theo thứ tự thiết lập: tìm trang quản lý dịch vụ thanh toán trong admin, cấu hình một dịch vụ, nhân bản dịch vụ khi cần nhiều tài khoản cùng nhà cung cấp, rồi xem kết quả trên trang giỏ hàng.

Dịch vụ thanh toán đến từ đâu

E-Commerce không tự kết nối với nhà cung cấp nào. Mỗi dịch vụ thanh toán là một phần mã được plugin cài thêm cung cấp, ví dụ plugin EzyPayment cung cấp các dịch vụ VNPAY, PAYPAL, PAYFS, PAY2S. Vì vậy:
  • Danh sách dịch vụ gốc trong admin chính là các dịch vụ mà các plugin đã cài cung cấp, quản trị viên không tạo dịch vụ gốc từ giao diện.
  • Quản trị viên cấu hình thông tin kết nối (khoá, đường dẫn, loại tiền...) và bật/tắt từng dịch vụ.
  • Muốn dùng cùng một nhà cung cấp với nhiều tài khoản khác nhau, quản trị viên nhân bản dịch vụ đó (xem phần Nhân bản dịch vụ thanh toán).
Mỗi dịch vụ thuộc một trong hai loại:
  • Cổng thanh toán: khách được chuyển sang trang của nhà cung cấp (VNPAY, PAYPAL) để thanh toán, sau đó nhà cung cấp gọi lại website để báo kết quả.
  • Dịch vụ thông báo biến động số dư: nhà cung cấp (PAYFS, PAY2S) theo dõi tài khoản ngân hàng của cửa hàng và gọi về website khi có tiền chuyển vào, giúp tự động xác nhận các đơn hàng thanh toán bằng chuyển khoản.

Mở trang quản lý dịch vụ thanh toán

Trong admin, chọn E-Commerce > Các dịch vụ thanh toán. Con số bên cạnh menu là số dịch vụ gốc đang có.
Menu Các dịch vụ thanh toán
  1. Menu Các dịch vụ thanh toán trong nhóm E-Commerce.

Danh sách dịch vụ thanh toán gốc

Bảng đầu tiên của trang liệt kê các dịch vụ gốc do plugin cung cấp, sắp xếp theo mã. Dịch vụ chưa được cấu hình lần nào vẫn có trong bảng với trạng thái Chưa kích hoạt.
Danh sách dịch vụ thanh toán gốc
  1. Mã và Tên của dịch vụ. Mã do plugin đặt và không đổi được, tên là phần hiển thị trên nút thanh toán của website. Bấm vào mã hoặc tên để xem chi tiết.
  2. Loại tiền mà dịch vụ nhận và Quyền ưu tiên dùng để sắp xếp nút thanh toán trên website (số nhỏ đứng trước).
  3. Loại của dịch vụ: Cổng thanh toán hoặc Dịch vụ thông báo biến động số dư.
  4. Trạng thái của dịch vụ:
    • Đã kích hoạt: dịch vụ hiển thị nút thanh toán trên trang giỏ hàng.
    • Đang lắng nghe: không hiển thị nút thanh toán, dùng khi chỉ cần nhận thông báo từ nhà cung cấp, ví dụ PAYFS nhận thông báo biến động số dư cho các đơn chuyển khoản.
    • Chưa kích hoạt và Đã lưu trữ: không hiển thị nút thanh toán.
  5. Các hành động: xem chi tiết (biểu tượng con mắt), kích hoạt hoặc ngừng kích hoạt, và sửa. Nút kích hoạt/ngừng kích hoạt chỉ xuất hiện khi dịch vụ đã được lưu cấu hình ít nhất một lần, như PAYPAL và VNPAY trong ảnh.
Ô Tìm kiếm phía trên bảng lọc nhanh các dòng đang hiển thị.

Cấu hình một dịch vụ thanh toán

Bấm biểu tượng sửa ở cột Các hành động để mở form Sửa dịch vụ thanh toán. Ảnh dưới đây là form của dịch vụ PAYFS.
Form sửa dịch vụ thanh toán
  1. Tên (bắt buộc, không trùng với dịch vụ khác): tên hiển thị trên nút Thanh toán qua <tên> ở website.
  2. Loại tiền mà nhà cung cấp nhận và Quyền ưu tiên. Nếu đơn hàng dùng loại tiền khác, số tiền được quy đổi theo tỉ giá trước khi gửi sang nhà cung cấp. Danh sách loại tiền lấy từ các loại tiền đang kích hoạt ở menu Các loại tiền.
  3. Đường dẫn gọi lại: đường dẫn nhà cung cấp gọi về website để báo kết quả thanh toán, mặc định là /payment/callback/<mã dịch vụ>. Dòng bên dưới là đường dẫn đầy đủ theo tên miền website, bấm biểu tượng sao chép để lấy và khai báo đường dẫn này ở trang quản trị của nhà cung cấp.
  4. Khoá máy khách và Khoá bí mật do nhà cung cấp cấp cho cửa hàng (merchant id, API key, checksum key... tuỳ nhà cung cấp). Nút Ngẫu nhiên sinh một chuỗi 32 ký tự, dùng khi nhà cung cấp cho phép cửa hàng tự đặt khoá. Khoá bí mật được lưu riêng, để trống ô này khi lưu thì khoá cũ được giữ nguyên.
  5. Trạng thái của dịch vụ, ý nghĩa như ở phần danh sách.
Các trường còn lại:
  • Phiên bản: phiên bản API của nhà cung cấp, nếu nhà cung cấp yêu cầu.
  • Logo và Băng rôn: ảnh đại diện của dịch vụ, chọn từ thư viện media. Logo hiển thị ở cột Logo của danh sách, khi chưa có logo cột này hiển thị ###.
  • Ngân hàng: ngân hàng gắn với dịch vụ, chọn từ menu Các ngân hàng.
  • Đường dẫn dịch vụ và Đường dẫn API dịch vụ: địa chỉ trang thanh toán và API của nhà cung cấp (ví dụ địa chỉ sandbox khi chạy thử).
  • Các kiểu dáng và Các kịch bản: CSS và JavaScript bổ sung cho dịch vụ, dùng khi dịch vụ cần tuỳ biến giao diện thanh toán.
Bấm Lưu để lưu cấu hình. Ý nghĩa cụ thể của từng khoá và đường dẫn phụ thuộc vào nhà cung cấp, hãy xem tài liệu tích hợp của nhà cung cấp và tài liệu của plugin cung cấp dịch vụ.

Nhân bản dịch vụ thanh toán

Mỗi dịch vụ gốc chỉ có một bộ khoá. Khi cửa hàng cần dùng cùng nhà cung cấp với nhiều tài khoản, ví dụ hai tài khoản VNPAY cho hai thương hiệu, hoặc hai tài khoản PAYFS theo dõi hai tài khoản ngân hàng, hãy tạo một dịch vụ nhân bản. Dịch vụ nhân bản dùng lại cách xử lý của một dịch vụ gốc (gọi là Dịch vụ xử lý) nhưng có mã, tên, khoá và trạng thái riêng.

Danh sách dịch vụ đã nhân bản

Bảng Các dịch vụ thanh toán đã nhân bản nằm ngay dưới bảng dịch vụ gốc, trên cùng trang.
Danh sách dịch vụ thanh toán đã nhân bản
  1. Thêm mới: mở form tạo dịch vụ nhân bản.
  2. Bộ lọc: Tìm kiếm theo từ khoá (mã, tên, dịch vụ xử lý), lọc theo Dịch vụ xử lý, Trạng thái và số dòng mỗi trang (Giới hạn).
  3. Dịch vụ xử lý: dịch vụ gốc mà dịch vụ nhân bản dùng lại. Cột Loại lấy theo dịch vụ xử lý.
Các cột và hành động còn lại giống bảng dịch vụ gốc. Bảng có phân trang ở cuối.

Thêm dịch vụ nhân bản

Bấm Thêm mới để mở form Thêm dịch vụ thanh toán. Ví dụ dưới đây tạo dịch vụ payfs-03 dùng lại cách xử lý của PAYFS.
Form thêm dịch vụ thanh toán
  1. Mã (bắt buộc, không trùng với mã của dịch vụ gốc hay dịch vụ nhân bản khác), Dịch vụ xử lý (bắt buộc, chọn một dịch vụ gốc) và Tên (bắt buộc, không trùng).
  2. Logo và Băng rôn của dịch vụ.
  3. Ngân hàng, Loại tiền và Quyền ưu tiên.
  4. Đường dẫn dịch vụ, Đường dẫn API dịch vụ và Đường dẫn gọi lại. Đường dẫn gọi lại của dịch vụ nhân bản theo mã của chính nó, ví dụ /payment/callback/payfs-03.
  5. Các kiểu dáng và Các kịch bản.
  6. Khoá máy khách và Khoá bí mật của tài khoản thứ hai tại nhà cung cấp.
  7. Trạng thái ban đầu của dịch vụ.
Bấm Lưu để tạo. Sau khi tạo, mã được giữ nguyên, còn Dịch vụ xử lý và các trường khác sửa được qua biểu tượng sửa như dịch vụ gốc.

Nút thanh toán trên trang giỏ hàng

Trên website, trang giỏ hàng hiển thị một nút Thanh toán qua <tên dịch vụ> cho mỗi dịch vụ có trạng thái Đã kích hoạt, gồm cả dịch vụ gốc và dịch vụ nhân bản. Các nút được sắp xếp theo Quyền ưu tiên tăng dần, cùng quyền ưu tiên thì theo tên.
Nút thanh toán trên trang giỏ hàng
  1. Các nút thanh toán tương ứng với các dịch vụ đã kích hoạt trong ví dụ trên: VNPAY (quyền ưu tiên 1), PAYPAL (2) và dịch vụ nhân bản VNPAY Shop 2 (4). PAYFS và payfs-02 đang ở trạng thái Đang lắng nghe nên không có nút.
Khi khách bấm một nút, website tạo đơn hàng và chuyển khách sang trang thanh toán của dịch vụ. Sau khi khách thanh toán, nhà cung cấp gọi Đường dẫn gọi lại để website kiểm tra kết quả (chữ ký, số tiền đã quy đổi...) và cập nhật trạng thái đơn hàng.
Nút Thanh toán qua Chuyển khoản không phải dịch vụ thanh toán: nút này xuất hiện khi cửa hàng có tài khoản ngân hàng mặc định. Đây là trường hợp nên đặt PAYFS ở trạng thái Đang lắng nghe để đơn chuyển khoản được xác nhận tự động khi tiền vào tài khoản.

Tích hợp nhà cung cấp mới bằng lập trình

Khi cần một nhà cung cấp chưa có plugin, lập trình viên viết một plugin cung cấp dịch vụ thanh toán mới. Phần này tóm tắt các bước, để dịch vụ mới xuất hiện tự động trong danh sách dịch vụ gốc ở trên.
  1. Thêm thư viện ecommerce-sdk vào plugin và viết một lớp cài đặt interface PaymentService cho cả admin plugin và web plugin.
  2. Cài đặt các phương thức chính:
    • getCode(): mã dịch vụ, ví dụ MYPAY. Đây là mã hiển thị trong admin và là phần cuối của đường dẫn gọi lại mặc định.
    • getType(): PAYMENT_GATEWAY cho cổng thanh toán hoặc BALANCE_CHANGE_NOTIFICATION_SERVICE cho dịch vụ thông báo biến động số dư.
    • createPaymentUrl(...): tạo đường dẫn chuyển khách sang trang thanh toán, từ cấu hình của dịch vụ (khoá máy khách, đường dẫn dịch vụ...), khoá bí mật và thông tin đơn hàng.
    • verifyPaymentRequestParameters(...): kiểm tra yêu cầu nhà cung cấp gửi về đường dẫn gọi lại (chữ ký, khoá API).
    • extractPaymentOrder(...): lấy mã đơn hàng và số tiền từ yêu cầu gọi lại.
    • verifyPaymentResult(...): so sánh số tiền thanh toán với số tiền đơn hàng đã quy đổi và trả về kết quả thành công hay thất bại.
    • clone(newCode): trả về một bản sao của dịch vụ với mã mới. Chỉ khi cài đặt phương thức này, dịch vụ mới dùng được làm Dịch vụ xử lý cho dịch vụ nhân bản.
  3. Đăng ký lớp như một singleton của plugin. Khi plugin được cài và khởi động lại, dịch vụ xuất hiện trong danh sách với trạng thái Chưa kích hoạt.
  4. Cấu hình và kích hoạt dịch vụ trong admin như các phần trên, chạy thử với tài khoản sandbox của nhà cung cấp trước khi kích hoạt thật.

Lưu ý

  • Kiểm tra kỹ Khoá máy khách, Khoá bí mật và Đường dẫn gọi lại với cấu hình ở trang quản trị của nhà cung cấp. Sai một trong ba thông tin này, khách vẫn thanh toán được nhưng đơn hàng không được cập nhật.
  • Không chia sẻ khoá bí mật. Khi cần đổi khoá, cập nhật ở nhà cung cấp và trong admin cùng lúc để không bỏ lỡ các lần gọi lại.
  • Dùng Ngừng kích hoạt thay vì đổi khoá khi muốn tạm dừng một dịch vụ: nút thanh toán biến mất khỏi trang giỏ hàng ngay.
  • Đặt Loại tiền đúng với loại tiền nhà cung cấp nhận và khai báo tỉ giá ở menu Các tỉ giá nếu sản phẩm bán bằng loại tiền khác.