Kết nối Paddle
Dán một khóa API Paddle chỉ đọc để nhập doanh số phần mềm và SaaS, hoàn tiền và thuế theo sản phẩm và quốc gia.
Paddle là merchant of record cho phần mềm bạn bán ngoài các cửa hàng ứng dụng: ứng dụng máy tính, ứng dụng web, gói SaaS và giấy phép. Nó kết nối bằng một khóa API chỉ đọc duy nhất thay vì OAuth. Bạn tạo khóa trong bảng điều khiển Paddle, dán vào Revenue Sensor và chọn những sản phẩm Paddle cần đồng bộ. Khóa được lưu ở dạng mã hóa và không bao giờ rời khỏi máy chủ của chúng tôi; thông tin đăng nhập Paddle của bạn không bao giờ được dùng đến.
Trước khi bắt đầu
- Quyền truy cập bảng điều khiển Paddle của tài khoản người bán mà bạn muốn theo dõi doanh số, kèm quyền tạo khóa API trong Developer tools.
- Biết rõ bạn muốn tài khoản live hay sandbox. Paddle cấp khóa riêng cho từng môi trường, và chính khóa quyết định chúng tôi đọc môi trường nào; không cần chọn gì thêm.
Tạo khóa API chỉ đọc
- 1
Mở Developer tools
Trong bảng điều khiển Paddle, vào Developer tools → Authentication và tạo một khóa API mới. Đặt cho nó một cái tên bạn sẽ nhận ra sau này, chẳng hạn "Revenue Sensor".
- 2
Chỉ cấp quyền đọc
Tích quyền đọc cho Transactions, Adjustments, Products và Addresses. Addresses nằm dưới mục Customers và cho chúng tôi biết quốc gia của người mua, nên hãy giữ lại dù nghe có vẻ không liên quan. Không cần bất kỳ quyền ghi nào.
- 3
Sao chép khóa một lần duy nhất
Paddle chỉ hiển thị khóa đúng một lần khi tạo. Hãy sao chép ngay; nếu làm mất, hãy thu hồi và tạo khóa khác.
Kết nối tài khoản
- 1
Dán khóa vào
Vào Integrations → Paddle → Connect trong bảng điều khiển Revenue Sensor và dán khóa API. Revenue Sensor đọc tiền tố của khóa để phân biệt khóa live với khóa sandbox và xác nhận sẽ dùng môi trường nào trước khi bạn tiếp tục.
- 2
Chọn sản phẩm của bạn
Đơn vị bạn đồng bộ là sản phẩm Paddle, không phải ứng dụng trên cửa hàng. Chọn những sản phẩm bạn muốn có trong sổ cái; mỗi sản phẩm hiện thành một dòng doanh thu riêng và có thể được gán cho một ứng dụng nếu nó thuộc về ứng dụng đó. Chỉ những gì bạn chọn mới được lấy về, và chỉ những gì bạn chọn mới tính vào gói của bạn.
- 3
Để lần đồng bộ đầu tiên chạy xong
Paddle lưu toàn bộ lịch sử của bạn, nên lần đồng bộ đầu tiên sẽ lấy lại tới một năm giao dịch đã thanh toán và hoàn tiền. Thường mất vài phút và bạn có thể rời trang trong lúc nó chạy.
Những gì được nhập
| Trường | Ghi chú |
|---|---|
| Doanh thu | Các giao dịch đã thanh toán, ghi nhận vào ngày tiền được thu thay vì ngày phát hành hóa đơn. Hiển thị theo sản phẩm, theo ngày và theo quốc gia người mua, chưa gồm thuế. Phí của Paddle không bị trừ, giống như Google Play được hiển thị ở mức gộp trước phí của Google. |
| Thuế | Paddle thu thuế bán hàng và VAT với tư cách merchant of record và ghi rõ trên từng dòng, nên thuế được nhập riêng và chế độ xem gồm thuế có sẵn cho nguồn này. |
| Hoàn tiền và bồi hoàn | Các khoản hoàn tiền và bồi hoàn (chargeback) được duyệt sẽ làm giảm doanh thu vào ngày được duyệt, đồng thời số tiền cũng được ghi thành con số hoàn tiền để tham khảo. Một bồi hoàn bị đảo ngược sẽ trả tiền lại. Tín dụng và cảnh báo bồi hoàn không được coi là hoàn tiền. |
| Quốc gia | Lấy từ địa chỉ thanh toán của khách hàng. Chỉ dùng mã quốc gia. |
Mọi loại tiền tệ của Paddle đều được xử lý
Giao dịch được nhập bằng đúng loại tiền đã tính phí và được quy đổi như mọi nguồn khác. Các loại tiền không có phần thập phân như JPY và KRW được đọc chính xác, nên một đơn hàng ở Nhật sẽ không bị báo cáo bằng một phần trăm giá trị thực.
Cập nhật theo thời gian thực (tùy chọn)
Revenue Sensor đồng bộ Paddle mỗi 30 phút. Nếu bạn muốn thấy một đơn hàng hay khoản hoàn tiền mới chỉ sau một hai phút, hãy trỏ một notification destination của Paddle về chúng tôi. Số liệu vẫn đến từ API của Paddle; webhook chỉ báo cho chúng tôi đồng bộ sớm hơn.
- 1
Sao chép URL webhook
Mở kết nối Paddle trong bảng điều khiển Revenue Sensor. Bảng "Real-time updates" hiển thị một URL dành riêng cho kết nối này; hãy sao chép nó.
- 2
Tạo một notification destination
Trong Paddle, vào Developer tools → Notifications → New destination. Dán URL, chọn loại Webhook và đăng ký các sự kiện transaction, adjustment và subscription.
- 3
Lưu secret
Paddle hiển thị một signing secret khi destination được tạo. Dán nó vào bảng "Real-time updates" và lưu. Chúng tôi dùng nó để xác minh mọi lần gửi và loại bỏ bất cứ thứ gì không có chữ ký; nó được lưu mã hóa và không bao giờ hiển thị lại.
Khắc phục sự cố
- Khóa bị từ chối: kiểm tra xem khóa có quyền đọc cả bốn mục Transactions, Adjustments, Products và Addresses không. Khóa thiếu Addresses vẫn qua được kiểm tra cơ bản nhưng sẽ thất bại khi đồng bộ.
- Không có sản phẩm nào được liệt kê: khóa thuộc về một tài khoản khác, hoặc thuộc sandbox trong khi bạn mong đợi live (hoặc ngược lại). Tiền tố của khóa cho bạn biết là môi trường nào.
- Thiếu một đơn hàng: chỉ các giao dịch đã thanh toán và hoàn tất mới được nhập. Bản nháp, hóa đơn chưa thanh toán và giao dịch đã hủy chưa phải là doanh thu.
- Doanh thu có vẻ cao hơn số tiền bạn nhận được: điều đó là bình thường. Thuế được tách riêng và phí của Paddle không bị trừ, nên con số này là doanh thu gộp trước phần của Paddle.
- Một khoản hoàn tiền hiện ở ngày khác với ngày bán: hoàn tiền được ghi nhận vào ngày được duyệt, không lùi về ngày mua ban đầu.