Hướng dẫn tích hợp

Máy chủ của bạn tạo thanh toán qua API, và kokiwa gửi webhook khi tiền đến. Tiền đi thẳng vào ví của bạn trên chuỗi; kokiwa không giữ tiền.

Chuẩn bị

Tất cả được thực hiện trong trang quản trị người bán.

1. Đăng kýXác minh email, thiết lập ứng dụng xác thực và lưu mã khôi phục.
2. Tạo dự ánMột dự án ứng với một sản phẩm hoặc trang web của bạn, có địa chỉ nhận tiền, API key và webhook riêng.
3. Thiết lập nhận tiềnTrong trang Thiết lập nhận tiền của dự án, chọn chuỗi, phương thức nhận tiền và token, rồi đăng ký địa chỉ nhận tiền trên từng chuỗi bằng ví. Địa chỉ được ghi trên chuỗi và chỉ ví đã đăng ký mới đổi được. Đăng ký tốn một ít gas; một ví có thể đăng ký mọi chuỗi EVM.
4. Tạo API keyKey chỉ hiển thị một lần. Hãy lưu trong biến môi trường của máy chủ, không đặt ở front-end hay ứng dụng.
5. Thiết lập webhookTrong trang Webhook, nhập URL https, lưu khóa bí mật ký và bấm Gửi sự kiện thử để xác nhận đã nhận được.

Chọn cách nhận tiền

Bạn có thể dùng cả hai.

Thanh toán

Tạo thanh toán khi người dùng đặt hàng và mở checkout_url trả về cho họ. Yêu cầu dưới đây liệt kê mọi chuỗi mà dự án nhận USDT, người dùng chọn một.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Địa chỉ nạp

Đặt customer là ID người dùng trong hệ thống của bạn. Gọi lại với cùng người dùng sẽ trả về cùng địa chỉ.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Xác nhận thanh toán

Khi thanh toán được xác nhận trên chuỗi, kokiwa gửi webhook. Chỉ ghi có dựa trên webhook, đừng dựa vào việc người dùng quay lại success_url.

• Thanh toán: khi nhận payment_intent.paid, đánh dấu đơn hàng đã thanh toán.
• Địa chỉ nạp: khi nhận deposit.confirmed, cộng số dư cho data.deposit.customer.

Hãy xác minh chữ ký của mọi sự kiện và loại trùng theo id sự kiện, xem Webhook.

Số tiền

Mọi số tiền đều là chuỗi theo đơn vị token, ví dụ "25.00" hoặc "24.9125", giống nhau trong yêu cầu, phản hồi và webhook, nên không cần quy đổi theo chuỗi. Số tiền giữ nguyên độ chính xác trên chuỗi nên số chữ số thập phân có thể khác nhau. Đừng tính bằng số dấu phẩy động.

Hoàn tiền

Tiền đã ở trong ví của bạn nên kokiwa không có API hoàn tiền và không thể đảo ngược thanh toán. Để hoàn tiền, hãy gửi từ địa chỉ nhận tiền cho người dùng. Hãy hỏi người dùng địa chỉ hoàn tiền thay vì dùng transaction.from, vì đó là địa chỉ của sàn nếu họ rút từ sàn. Phí không được hoàn lại.

Kiểm tra trước khi ra mắt

• API key chỉ nằm trên máy chủ, không có trong kho mã và nhật ký.
• Webhook đã xác minh chữ ký, sự kiện lặp lại không bị ghi có hai lần.
• Thanh toán được tạo với Idempotency-Key, nên thử lại mạng không tạo ra hai thanh toán.
• Đã xử lý payment_intent.paid_late, nên khoản trả sau khi hết hạn không bị bỏ sót.
• Đã đăng ký địa chỉ nhận tiền trên mainnet và chuyển sang key bắt đầu bằng sk_live_.
• Đã sao lưu cụm từ khôi phục của địa chỉ nhận tiền.