Những gì bạn cần
| Trường | Nó làm gì |
|---|---|
| Access token | Cho phép chúng tôi gọi Square để tạo liên kết thanh toán. Bí mật. |
| Webhook signature key | Xác nhận một webhook thực sự đến từ Square. Bí mật. |
| Location ID | Địa điểm Square nhận khoản thanh toán. Đặt tiền tệ. |
| Success URL / Cancel URL | Nơi người mua đáp xuống sau khi trả tiền hoặc rút lui. |
Vì sao chúng tôi hỏi mỗi trường
Access token
Cho phép tạo liên kết thanh toán, để khoản phí chạy qua tài khoản của bạn.
Webhook signature key
Chứng minh một webhook đến thực sự từ Square, nên không ai có thể giả mạo một sự kiện "đã trả tiền". Nó là một giá trị riêng tách khỏi access token.
Location ID
Cho Square biết địa điểm nào nhận tiền, và đặt tiền tệ thanh toán. Không bí mật.
Success và Cancel URL
Cài đặt thông thường: nơi người mua đáp xuống sau khi trả tiền hoặc rút lui. Không bí mật.
Thiết lập
- Mở bảng điều khiển Square Developer
Đăng nhập tại developer.squareup.com. Mỗi ứng dụng có thông tin xác thực riêng, và một Sandbox miễn phí được tạo kèm theo để kiểm tra. Hướng dẫn này đi theo luồng Sandbox; luồng Live giống hệt, chỉ cần chuyển nút bật/tắt Sandbox / Production và dùng thông tin xác thực production của bạn. Để tạo ứng dụng mới, nhấp ô + trên màn hình Applications.
Square Developer → Applications - Đặt tên ứng dụng của bạn
Đặt tên ứng dụng bạn sẽ nhận ra (ví dụ "Coin Moebius"), rồi nhấp Next.
Square → Đặt tên ứng dụng - Sao chép access token của bạn
Mở ứng dụng và vào Credentials. Xác nhận nút bật/tắt Sandbox / Production ở trên cùng khớp với môi trường bạn đang thiết lập. Nhấp biểu tượng sao chép bên cạnh Access token và giữ lại.
Square → Credentials Access token là bí mật, hãy coi nó như mật khẩu. Sandbox và Production có token riêng, nên đừng trộn chúng.
- Sao chép Location ID của bạn
Trong menu bên trái, mở Locations. Sao chép Location ID của địa điểm sẽ nhận thanh toán. Nó đặt tiền tệ thanh toán, nên chọn địa điểm có tiền tệ bạn muốn tính phí.
Square → Locations - Mở Webhooks → Subscriptions
Square gọi một webhook endpoint là "subscription." Trong menu bên trái, mở rộng Webhooks, mở Subscriptions, và nhấp Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Thêm subscription và chọn sự kiện
Đặt tên cho nó (như "coin-moebius"). Trong Notification URL, dán địa chỉ webhook Square của dự án bạn (bên dưới). Rồi, dưới Events, tìm kiếm và chọn các sự kiện mà Coin Moebius lắng nghe, và nhấp Save.
- Thanh toán một lần: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Gói đăng ký (chỉ khi bạn bán chúng): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Nếu bạn không thanh toán định kỳ, hãy bỏ qua.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription ID dự án của bạn nằm dưới tên dự án trong bảng điều khiển Coin Moebius; điền vào địa chỉ ở trên. Sự kiện thừa là vô hại, chúng tôi bỏ qua những gì không dùng. Thẻ nhà cung cấp đã kết nối (bước cuối) hiển thị cùng URL đó để tham khảo.
- Mở subscription vừa tạo
Square lưu subscription và liệt kê nó dưới Webhooks với trạng thái Enabled. Nhấp tên của nó để mở bảng chi tiết nơi chứa signing key.
Square → Webhooks → subscription của bạn (Enabled) - Sao chép Signature key
Trong bảng Properties của subscription, nhấp biểu tượng sao chép bên cạnh Signature key. Đây là giá trị Coin Moebius dùng để xác nhận mỗi webhook thực sự đến từ Square. Nó chỉ tồn tại sau khi subscription được tạo, đó là lý do bước webhook đến trước bước kết nối.
Square → subscription của bạn → Signature key - Trong Coin Moebius: Thêm nhà cung cấp → Square
Trong dự án của bạn, mở tab Nhà cung cấp, nhấp Thêm nhà cung cấp, chọn Kết nối dịch vụ, và chọn Square. Đặt Success URL và Cancel URL của bạn. Trên tab Live, dán Access token, Webhook signature key và Location ID, rồi nhấp Save. Muốn thiết lập với thông tin xác thực sandbox trước? Dán chúng vào tab Test thay thế, rồi thêm thông tin xác thực live sau từ Chỉnh sửa.
Coin Moebius → Thêm nhà cung cấp → Square - Bạn đã kết nối
Square giờ xuất hiện trên tab Nhà cung cấp với ngày kết nối. Thẻ hiển thị cùng URL webhook bạn đã dán vào Square, cộng với Chỉnh sửa và Ngắt kết nối. Dùng nút bật/tắt Chế độ thử nghiệm để chạy một đơn hàng sandbox trọn vẹn đầu cuối trước khi đi vào live.
Coin Moebius → Nhà cung cấp → Square (đã kết nối) Thẻ sandbox không bao giờ tính phí thẻ thật. Dùng thẻ 4111 1111 1111 1111, CVV 111, bất kỳ ngày hết hạn tương lai nào, bất kỳ mã bưu chính hợp lệ nào (ví dụ 94103).
Sau khi bạn kết nối
Chạy một khoản thanh toán thử nghiệm trước khi chạy thật:
- Tạo một sản phẩm và đặt Môi trường của nó thành Testing. Việc đó chạy sản phẩm trên thông tin xác thực sandbox của bạn, nên bạn có thể đặt một đơn hàng đầy đủ mà không di chuyển tiền. (Nếu bạn bỏ qua bộ sandbox, một sản phẩm Testing sẽ quay về live, nên hãy thêm nó trước.)
- Đặt nút mua lên một trang (một tệp HTML cục bộ cũng được) trỏ về dự án của bạn.
- Hoàn tất thanh toán với thẻ thử nghiệm sandbox ở trên.
- Mở tab Giao dịch. Một hàng mới xuất hiện, gắn nhãn Testing. Khi trạng thái của nó đạt succeeded, thông tin xác thực và webhook của bạn đều hoạt động trọn vẹn đầu cuối.
Chuyển Môi trường sản phẩm sang Live khi bạn sẵn sàng cho thanh toán thật.
Khắc phục sự cố
Bắt đầu với Xác minh. Trong bảng điều khiển, nhấp Xác minh (hoặc Xác minh thông tin xác thực thử nghiệm) để kiểm tra access token và địa điểm của bạn.
Xác minh thất bại.
Sao chép lại access token và Location ID. Production và Sandbox có token riêng, nên đừng trộn chúng.
Xác minh chữ ký thất bại, hoặc đơn hàng vẫn đang chờ.
Square ký trên chính xác URL thông báo cộng với nội dung. URL bạn đăng ký trong Square phải khớp với URL webhook của bạn từng ký tự một, không có dấu gạch chéo cuối và không có chuỗi truy vấn thừa. Rồi sao chép lại signature key từ chính endpoint đó.
Xác nhận nó trọn vẹn đầu cuối.
Square Developer Console → Webhooks → đăng ký của bạn → Send Test Event, rồi quan sát đơn hàng cập nhật.
Cần biết
Tiền tệ đi theo địa điểm. Khâu thanh toán tính phí theo tiền tệ của địa điểm có id bạn cung cấp.
Xoay secret. Xoay access token hoặc signature key bất cứ lúc nào, rồi dán giá trị mới. Các trường bí mật vẫn để trống khi chỉnh sửa.
Câu hỏi? Join our Discord