Mô-đun zittme Pay
zittme Pay là mô-đun cổng thanh toán của Zittme. Mô-đun xử lý tập trung thanh toán của các mô-đun khác như thương mại · đặt chỗ, đồng thời cung cấp quản lý lịch sử thanh toán · hủy · nhật ký. Mô-đun của bên thứ ba cũng có thể gắn thanh toán qua zittme Pay nếu tuân theo quy ước đã định.
Cài đặt
- Cài mô-đun zittme Pay từ Cửa hàng.
- Dùng các tab Cài đặt · Cổng thanh toán · Lịch sử thanh toán · Nhật ký trong Quản trị > zittme Pay.
- Đăng ký tại panel.conekta.com rồi vào "Explorar panel" (khám phá bảng điều khiển), một công ty thử nghiệm sẽ được tạo mà không cần thẩm định doanh nghiệp.
- Bật "Modo pruebas" (chế độ thử nghiệm) ở góc dưới bên trái, rồi vào Desarrolladores > "Consultar API Keys de prueba" và tạo khóa bí mật bằng "Crear nueva llave privada". Khóa bí mật chỉ hiện một lần ngay lúc tạo nên hãy sao chép ngay.
- Nhập khóa bí mật vào tab Cổng thanh toán và bấm "Kiểm tra kết nối", chế độ (sandbox / giao dịch thật) sẽ được hiển thị. Khóa thử nghiệm không có tiền tố riêng nên chế độ được xác định dựa trên phản hồi của Conekta. Trước khi tạo đơn hàng lần đầu, trạng thái có thể hiện là "Cần kiểm tra".
- Vào Desarrolladores > Webhooks > "Crear Webhook", nhập địa chỉ webhook ở trên và bật tất cả sự kiện. Dù sự kiện nào đến, zittme Pay đều tra cứu lại đơn hàng qua API Conekta rồi mới xác nhận, nên thông báo giả mạo không thể xác nhận thanh toán.
- Thẻ được duyệt: 4242 4242 4242 4242 (Visa), 5555 5555 5555 4444 (Mastercard). Tên và CVC nhập giá trị bất kỳ, ngày hết hạn là một ngày trong tương lai.
- Thẻ bị từ chối: 4000 0000 0000 0002, không đủ số dư: 4000 0000 0000 0127.
- Với chuyển khoản (SPEI), gọi API thông báo nhận tiền sandbox của Conekta (
/sandbox/spei/payment_notifications) bằng CLABE đã cấp thì khoản tiền sẽ được xử lý đã nhận. Với tiền mặt (OXXO), sandbox sẽ tự động xử lý đã nhận sau một lúc. - Trong phiếu đặt hàng của mô-đun liên kết (thương mại, v.v.), khách chọn phương thức thanh toán và bấm Thanh toán.
- Thẻ: phê duyệt trong cửa sổ thanh toán Toss Payments → màn hình kết quả. / Chuyển khoản ngân hàng: màn hình kết quả hiển thị thông tin tài khoản và hạn chuyển khoản → Đã thanh toán khi quản trị viên xác nhận nhận tiền.
- Thay đổi trạng thái thanh toán được phản ánh ngay vào mô-đun liên kết, và được kiểm tra kép qua webhook của cổng thanh toán.
- Lịch sử thanh toán: tìm toàn bộ giao dịch thanh toán theo trạng thái · khoảng thời gian · phương thức thanh toán, và xem thông tin phê duyệt · mã đơn hàng của mô-đun liên kết · lịch sử xử lý của từng giao dịch.
- Hủy: thực hiện hủy toàn bộ hoặc hủy một phần (nếu được cho phép) từ giao dịch. Với thanh toán thẻ, yêu cầu hủy được gửi tới cổng thanh toán; với chuyển khoản ngân hàng, được ghi nhận là xử lý hoàn tiền. Lý do hủy được chọn từ danh sách lý do trong cài đặt.
- Giao dịch đã quá hạn tự động hủy qua PG: hệ thống hướng dẫn xử lý bằng hoàn tiền thủ công thay vì hủy qua PG.
- Nhật ký: ghi lại yêu cầu/phản hồi với cổng thanh toán và các webhook nhận được, và được dọn dẹp khi quá thời gian lưu. Hãy xem khi điều tra sự cố thanh toán.
- Nếu đơn vị trung gian gửi lý do thất bại, hệ thống hiển thị nguyên văn nội dung đó, ví dụ
카드 한도 초과,유효하지 않은 카드번호. - Với giao dịch chuyển khoản ngân hàng, hệ thống hiển thị gọn tài khoản đã cấp · tên người chuyển · hạn chuyển khoản.
- Nếu không có gì đáng tóm tắt, hệ thống hiển thị phần đầu của bản gốc.
- Khi gọi tạo thanh toán (createOrder), truyền mã đơn hàng của mô-đun mình vào tham số
source_code. - Khi đó, mã này sẽ được hiển thị làm "Mã đơn hàng" chính trên màn hình thanh toán · màn hình kết quả · lịch sử quản lý, còn mã của zittme Pay được ghi là "Mã thanh toán".
- Cập nhật trạng thái đơn hàng của mô-đun mình trong callback thanh toán hoàn tất · hủy.
- Thanh toán thử nghiệm không được: hãy kiểm tra chế độ thử nghiệm có bật không và khóa Toss Payments có phải khóa thử nghiệm không.
- Đơn chuyển khoản ngân hàng cứ ở trạng thái chờ thanh toán: với chuyển khoản ngân hàng, quản trị viên phải bấm xác nhận nhận tiền thì mới thành Đã thanh toán. Nếu đặt hạn chuyển khoản, các đơn chưa chuyển khoản bị bỏ quên sẽ được dọn tự động.
- Không thấy nút hủy một phần: nếu Cho phép hủy một phần đang tắt trong cài đặt, chỉ có thể hủy toàn bộ.
- Hủy thanh toán thẻ cũ bị thất bại: giao dịch đã quyết toán xong với PG sẽ bị chặn hủy thẻ. Hãy xử lý bằng hoàn tiền thủ công theo cài đặt Hạn tự động hủy qua PG.
- Webhook không đến: hãy kiểm tra xem IP của cổng thanh toán có bị thiếu trong Danh sách IP cho phép webhook không. Để trống thì nhận không giới hạn.
- Phương thức thanh toán mới không hiện trên màn hình thanh toán: phải bật phương thức đó trong tab Cổng thanh toán và nhập cả khóa thì mới hiện. Nếu khóa để trống, phương thức sẽ không hiện trong danh sách.
- PayPal bị vô hiệu: ngoài Client ID · Secret, tỷ giá của tiền tệ thanh toán (mặc định USD) phải được đăng ký trong tỷ giá chung.
- Đổi skin màn hình thanh toán nhưng lại trở về như cũ: đã được sửa trong 0.2.0. Hãy cập nhật mô-đun.
- Sau khi thanh toán xong và quay lại, hiện thông báo "Phương thức HTTP này không được dùng cho yêu cầu này": đây là sự cố ở phiên bản 0.2.9 trở xuống khi dùng PG như Conekta · PortOne, nơi cửa sổ thanh toán chuyển sang trang khác rồi quay lại bằng GET. Từ 0.2.10, callback nhận cả GET · POST, vì vậy hãy cập nhật zittme Pay tại Quản trị > Kho tài nguyên. Bản thân thanh toán đã được PG xử lý bình thường, nên với đơn hàng bị lỗi, bạn chỉ cần tra cứu lại trong Lịch sử thanh toán để đồng bộ về trạng thái đã phê duyệt.
Toàn bộ mục trong tab Cài đặt
| Mục | Mô tả |
|---|---|
| Sử dụng | Bật/tắt toàn bộ chức năng thanh toán |
| Chế độ thử nghiệm | Kiểm tra luồng thanh toán mà không phê duyệt thật. Hãy dùng cả khóa thử nghiệm cho cổng thanh toán |
| Tiền tệ | Mặc định KRW |
| Tiền tố mã đơn hàng | Dấu hiệu để nhận biết đơn hàng của bạn trong trang quản trị PG (tối đa 8 ký tự chữ Latin·số) |
| Cho phép hủy một phần | Có cho hủy một phần số tiền thanh toán hay không. Nếu tắt, chỉ có thể hủy toàn bộ |
| Danh sách lý do hủy | Các lý do để chọn khi hủy. Nhập mỗi dòng một lý do |
| Hạn tự động hủy qua PG (ngày) | Sau khoảng thời gian này kể từ khi thanh toán, hệ thống không thử hủy qua PG mà chuyển sang hoàn tiền thủ công. Lý do là thanh toán thẻ đã quyết toán xong sẽ bị chặn hủy qua PG. 0 nghĩa là không giới hạn |
| Cho phép hủy cưỡng bức giao dịch đã xác nhận | Cho phép quản trị viên hủy cả những thanh toán đã xác nhận mua. Nếu tắt, sau khi xác nhận sẽ không thể hủy bằng bất kỳ cách nào |
| Email thông báo cho quản trị viên | Địa chỉ nhận thông báo |
| Sự kiện thông báo | Có gửi khi thanh toán hoàn tất / khi hủy hay không (riêng từng loại) |
| Số ngày lưu nhật ký | Thời gian lưu nhật ký thanh toán (0=vô thời hạn) |
| Danh sách IP cho phép webhook | Giới hạn các IP được nhận webhook từ cổng thanh toán. Để trống thì không giới hạn |
| Nội dung thông báo trên màn hình thanh toán | Nội dung hiển thị ở cuối màn hình thanh toán, như số đăng ký kinh doanh thương mại điện tử |
| Skin màn hình thanh toán | Chọn skin cho màn hình thanh toán · kết quả |
Tab Cổng thanh toán (phương thức thanh toán)
Bật các phương thức thanh toán sẽ dùng và nhập thông tin cho từng phương thức.
Toss Payments (thẻ, v.v.)
| Mục | Mô tả |
|---|---|
| Client key | Cấp tại Trung tâm nhà phát triển Toss Payments |
| Secret key | Như trên. Tuyệt đối không để lộ ra bên ngoài |
Nên kiểm tra luồng bằng khóa thử nghiệm + chế độ thử nghiệm trước rồi mới chuyển sang khóa thật. Nếu loại khóa (thử nghiệm/thật) và chế độ không khớp, việc phê duyệt sẽ thất bại.
KG Inicis
| Mục | Mô tả |
|---|---|
| Mã cửa hàng (MID) | Cấp tại trang quản trị đại lý Inicis |
| Sign Key | Dùng để ký cửa sổ thanh toán |
| INIAPI Key | Khóa riêng cho hủy · hoàn tiền. Cấp riêng tại trang quản trị đại lý |
Ở chế độ thử nghiệm, bạn có thể dùng khóa của cửa hàng thử nghiệm công khai (mid INIpayTest) để kiểm tra đến tận cửa sổ thanh toán ngay cả trước khi ký hợp đồng. Nếu kết nối phê duyệt bị ngắt hoặc số tiền không khớp, giao dịch sẽ tự động được hủy mạng để tránh thanh toán hai lần.
NHN KCP
| Mục | Mô tả |
|---|---|
| Mã trang (site_cd) | Do KCP cấp. Thử nghiệm dùng T0000 |
| Chứng chỉ dịch vụ | Dán nguyên nội dung tệp PEM nhận từ Trung tâm chứng thực trong trang quản trị KCP |
| Khóa riêng của cửa hàng · mật khẩu | Chỉ dùng cho chữ ký điện tử của yêu cầu hủy · hoàn tiền |
NICEPAY
| Mục | Mô tả |
|---|---|
| Client ID | Cấp tại Trung tâm nhà phát triển NICEPAY (developers.nicepay.co.kr) |
| Secret Key | Như trên |
Chỉ cần đăng ký Trung tâm nhà phát triển là nhận được khóa sandbox, nên bạn có thể thử luồng thanh toán · hủy ngay cả trước khi ký hợp đồng. Khi chế độ thử nghiệm đang bật, hệ thống tự động kết nối tới máy chủ sandbox.
PortOne (V2)
| Mục | Mô tả |
|---|---|
| Store ID | Cấp tại bảng điều khiển PortOne (portone.io) |
| Channel key | Việc thanh toán qua PG nào được quyết định trong cài đặt kênh của bảng điều khiển PortOne |
| V2 API Secret | Dùng cho phê duyệt · hủy phía máy chủ |
Chỉ với một driver, bạn có thể dùng nhiều PG đã kết nối với PortOne. Để thử nghiệm, chỉ cần nhập khóa của kênh thử nghiệm.
PayPal (thanh toán quốc tế)
| Mục | Mô tả |
|---|---|
| Client ID · Secret | Cấp từ ứng dụng trong bảng điều khiển nhà phát triển PayPal (developer.paypal.com). Ở chế độ thử nghiệm, dùng khóa của ứng dụng sandbox |
| Tiền tệ thanh toán | PayPal không hỗ trợ KRW. Đơn hàng bằng won được quy đổi sang tiền tệ này để thanh toán (mặc định USD) |
Việc quy đổi dùng tỷ giá chung bên dưới, và hoàn tiền được xử lý theo tỷ giá tại thời điểm thanh toán. Đơn hàng ngoại tệ (đa tiền tệ của thương mại) được thanh toán trực tiếp bằng tiền tệ đó mà không quy đổi.
Conekta (Mexico · Mỹ Latinh)
Nhận thanh toán bằng thẻ, tiền mặt (cửa hàng tiện lợi OXXO), chuyển khoản (SPEI) qua trang thanh toán được lưu trữ (hosted) của Conekta, công ty thanh toán Mexico. Khi bấm Thanh toán, khách được chuyển tới trang thanh toán của Conekta và quay về trang web sau khi thanh toán xong. Tiền mặt và chuyển khoản sẽ quay về ở trạng thái "Chờ chuyển khoản" khi mới chỉ cấp mã tham chiếu hoặc tài khoản, và việc nhận tiền thực tế được xác nhận qua webhook.
| Mục | Mô tả |
|---|---|
| Khóa bí mật Conekta | Khóa bí mật (bắt đầu bằng key_) tạo ở bảng Conekta > Desarrolladores > API Keys. Không dùng khóa công khai |
| Địa chỉ webhook | Đăng ký địa chỉ hiển thị trên màn hình vào bảng Conekta > Desarrolladores > Webhooks. Bắt buộc để xác nhận nhận tiền mặt · chuyển khoản |
| Phương thức thanh toán | Chọn các phương thức mở trên trang thanh toán. Thẻ / Tiền mặt (OXXO) / Chuyển khoản (SPEI). Để trống là tất cả |
| Tiền tệ thanh toán | Tiền tệ để quy đổi đơn hàng bằng won. Mặc định MXN. OXXO và SPEI chỉ dùng MXN, còn thanh toán thẻ USD được mở tùy loại tài khoản Conekta |
| Cho phép đơn hàng bằng won | Khi bật, đơn hàng bằng won được quy đổi theo tỷ giá chung để thanh toán. Bảng tỷ giá phải có dòng cho tiền tệ thanh toán (MXN) |
Lấy khóa thử nghiệm
Thanh toán thử nghiệm
Khóa giao dịch thật
Theo điều khoản của Conekta, tài khoản giao dịch thật cần doanh nghiệp được thành lập theo pháp luật Mexico (có RFC) và tài khoản quyết toán tại Mexico. Sau khi thẩm định xong, bạn chỉ cần nhập khóa giao dịch thật từ bảng điều khiển vào cùng ô đó. Hoàn tiền qua API chỉ áp dụng cho thanh toán thẻ; thanh toán tiền mặt · chuyển khoản sẽ chuyển sang hoàn tiền thủ công.
Chuyển khoản ngân hàng
| Mục | Mô tả |
|---|---|
| Tài khoản nhận tiền | Đăng ký nhiều bộ ngân hàng · số tài khoản · chủ tài khoản. Người mua chọn tài khoản khi đặt hàng |
| Hạn chuyển khoản (ngày) | 1~30 ngày. Các đơn chưa chuyển khoản quá hạn sẽ thuộc diện tự động hủy |
Quản trị viên xác nhận đã nhận tiền trong Lịch sử thanh toán; khi xác nhận, đơn hàng của mô-đun liên kết sẽ chuyển sang Đã thanh toán.
Tỷ giá chung
Quản lý tỷ giá theo từng tiền tệ (KRW cho mỗi 1 đơn vị tiền tệ) trong tab Cổng thanh toán. Đây là chuẩn duy nhất mà cả việc quy đổi thanh toán của zittme Pay và giá đa tiền tệ của mô-đun thương mại cùng tham chiếu.
| Mục | Mô tả |
|---|---|
| Bảng tỷ giá | Đăng ký mã tiền tệ (USD, v.v.) và tỷ giá |
| Cố định thủ công | Tiền tệ được đánh dấu sẽ không bị cập nhật tự động ghi đè |
| Cập nhật tự động | Cập nhật mỗi ngày một lần. Chọn nguồn giữa open.er-api.com (không cần khóa) hoặc Ngân hàng Xuất nhập khẩu Hàn Quốc (cần khóa API) |
Kể cả khi cập nhật tự động thất bại, giá trị thành công gần nhất vẫn được giữ; đơn hàng lưu tỷ giá tại thời điểm thanh toán nên không bị ảnh hưởng bởi biến động tỷ giá sau đó.
Thanh toán ngoại tệ
Khi mô-đun liên kết như thương mại chuyển sang một đơn hàng ngoại tệ, thanh toán sẽ được thực hiện bằng tiền tệ đó. Phương thức thanh toán không hỗ trợ tiền tệ của đơn hàng sẽ không xuất hiện trên màn hình thanh toán (PG trong nước chỉ dùng KRW, PayPal hỗ trợ 24 tiền tệ chính). Cách hiển thị số tiền được xử lý tự động theo ký hiệu tiền tệ và số chữ số thập phân.
Luồng thanh toán
Mã đơn hàng và mã thanh toán
Vì người mua sẽ bối rối nếu thấy hai mã số, hệ thống hiển thị theo nguyên tắc sau.
| Mã | Nơi cấp | Cách hiển thị |
|---|---|---|
| Mã đơn hàng | Mô-đun yêu cầu thanh toán (thương mại · đặt chỗ, v.v.) | Hiển thị lớn làm mã chính trên màn hình thanh toán · màn hình kết quả · lịch sử |
| Mã thanh toán | zittme Pay | Hiển thị nhỏ làm mã phụ. Là căn cứ cho hỏi đáp về thanh toán · xử lý hủy |
Lịch sử thanh toán và hủy
Cách đọc nhật ký
Tab Nhật ký lưu theo thứ tự thời gian các nội dung trao đổi với đơn vị trung gian thanh toán. Khi thanh toán thất bại hoặc chưa xác nhận được tiền chuyển khoản, bạn hãy xem ở đây trước.
Ô phản hồi hiển thị bản tóm tắt một dòng thay cho bản gốc.
Nếu cần toàn bộ bản gốc, hãy di chuột lên dòng tóm tắt. Phản hồi do đơn vị trung gian gửi sẽ hiện nguyên văn. Khi gửi yêu cầu hỗ trợ, bạn chỉ cần đính kèm bản gốc này.
Nếu phản hồi trống, nghĩa là yêu cầu không đến được đơn vị trung gian. Hãy kiểm tra thông tin xác thực trong tab Cổng thanh toán và xem máy chủ có chặn kết nối ra bên ngoài hay không.
Liên kết mô-đun bên thứ ba (nhà phát triển)
Quy ước để gắn thanh toán zittme Pay từ mô-đun khác rất đơn giản.
Mô-đun thương mại và mô-đun đặt chỗ là bản triển khai tham chiếu của quy ước này. Về quy ước phát triển mô-đun nói chung, hãy xem thêm tài liệu "Xây dựng mô-đun" trong hướng dẫn dành cho nhà phát triển.