Tạo hóa đơn
Lời yêu cầu
Tham số truy vấn
Tên | Kiểu tham số | Giá trị mặc định | Sự định nghĩa |
---|---|---|---|
amount* | string | Số tiền phải trả.Nếu có xu trong số tiền, hãy gửi chúng với dấu phân cách '.' Ví dụ: 10.28 | |
currency* | string | Mã tiền tệ | |
order_id* | stringmin: 1max: 128alpha_dash | ID đơn hàng trong hệ thống của bạnTham số phải là một chuỗi bao gồm các ký tự chữ cái, số, dấu gạch dưới và dấu gạch ngang. Chuỗi không được chứa bất kỳ khoảng trắng hoặc ký tự đặc biệt nào. order_id phải là duy nhất trong hóa đơn của người bán/ví tĩnh/thanh toán định kỳKhi chúng tôi tìm thấy hóa đơn hiện có với order_id, chúng tôi sẽ trả về thông tin chi tiết của hóa đơn đó, hóa đơn mới sẽ không được tạo. | |
network | string | null | Mã mạng Blockchain |
url_return | stringmin: 6max: 255url | null | Trước khi thanh toán, người dùng có thể nhấp vào nút trên biểu mẫu thanh toán và quay lại trang cửa hàng tại URL này. |
url_success | stringmin: 6max: 255url | null | Sau khi thanh toán thành công, người dùng có thể nhấp vào nút trên biểu mẫu thanh toán và quay lại URL này. |
url_callback | stringmin: 6max: 255url | null | URL mà webhooks có trạng thái thanh toán sẽ được gửi đến |
is_payment_multiple | boolean | true | Cho phép người dùng thanh toán số tiền còn lại. Điều này hữu ích khi người dùng chưa thanh toán toàn bộ số tiền trên hóa đơn cho một giao dịch và bạn muốn cho phép họ thanh toán đến hết số tiền. Nếu bạn tắt tính năng này, hóa đơn sẽ được hoàn tất sau khi nhận được khoản thanh toán đầu tiên và bạn sẽ nhận được tiền vào số dư của mình. |
lifetime | integermin: 300max: 43200 | 3600 | Tuổi thọ của hóa đơn đã phát hành (tính bằng giây) |
to_currency | string | Tham số này được sử dụng để chỉ định loại tiền tệ mục tiêu để chuyển đổi số tiền trên hóa đơn. Khi tạo hóa đơn, bạn cung cấp số tiền và loại tiền tệ, và API sẽ chuyển đổi số tiền đó sang giá trị tương đương trong biến to_currency.Ví dụ, để tạo hóa đơn trị giá 20 USD bằng bitcoin: số tiền: 20 tiền tệ: USD to_currency: BTCAPI sẽ chuyển đổi số tiền 20 USD sang số tiền tương đương bằng BTC dựa trên tỷ giá hối đoái hiện tại và người dùng sẽ thanh toán bằng BTCto_currency phải luôn là mã tiền điện tử, không phải mã tiền pháp định. | |
subtract | integermin: 0max: 100 | 0 | Tỷ lệ phần trăm hoa hồng thanh toán được tính cho khách hàngNếu bạn có tỷ lệ là 1%, thì nếu bạn tạo hóa đơn cho 100 USDT với trừ đi = 100 (khách hàng trả 100% hoa hồng), thì khách hàng sẽ phải trả 101 USDT. |
accuracy_payment_percent | numericmin: 0max: 5 | 0 | Độ chính xác chấp nhận được trong thanh toán.Ví dụ, nếu bạn nhập giá trị 5, hóa đơn sẽ được đánh dấu là Đã thanh toán ngay cả khi khách hàng chỉ thanh toán 95% số tiền.Số tiền thanh toán thực tế sẽ được ghi có vào số dư |
additional_data | stringmax: 255 | null | Thông tin bổ sung dành cho bạn (không hiển thị cho khách hàng) |
currencies | array | Mảng tiền tệ khả dụng từ cài đặt của người bán sẽ được sử dụng (nếu tham số không được đặt, tất cả các loại tiền điện tử được hỗ trợ sẽ được sử dụng theo mặc định).Các loại tiền tệ khả dụng được thiết lập trong phần cài đặt của người bán. | Danh sách các loại tiền tệ được phép thanh toán. Điều này hữu ích nếu bạn muốn giới hạn danh sách các loại tiền mà khách hàng có thể sử dụng để thanh toán hóa đơn. Kết cấu |
except_currencies | array | null | Danh sách các loại tiền tệ không được thanh toán Kết cấu |
course_source | stringmin: 4max: 20Các giá trị có sẵn• Binance• BinanceP2P• Exmo• Kucoin | Nếu không được thông qua, tỷ giá hối đoái Cryptomus sẽ được sử dụng. | Dịch vụ lấy tỷ giá hối đoái để quy đổi trên hóa đơn. |
from_referral_code | string | null | Người bán đưa ra yêu cầu sẽ kết nối với người giới thiệu bằng mã.Ví dụ: bạn là một ứng dụng tạo hóa đơn thông qua API Cryptomus và khách hàng của bạn là các cửa hàng khác. Họ nhập khóa API và ID người bán vào ứng dụng của bạn, và bạn gửi yêu cầu kèm theo thông tin đăng nhập của họ và mã giới thiệu của bạn.Vì vậy, khách hàng của bạn sẽ trở thành người giới thiệu vào tài khoản Cryptomus của bạn và bạn sẽ nhận được thu nhập từ doanh thu của họ. |
discount_percent | integermin: -99max: 100 | null | Số dương: Cho phép bạn thiết lập mức chiết khấu. Để thiết lập mức chiết khấu 5% cho khoản thanh toán, bạn phải truyền giá trị: 5Số âm: Cho phép bạn thiết lập hoa hồng bổ sung tùy chỉnh.Để thiết lập thêm hoa hồng 10% cho khoản thanh toán, bạn phải truyền giá trị: -10Tỷ lệ chiết khấu khi tạo hóa đơn chỉ được tính đến nếu hóa đơn đó có loại tiền điện tử cụ thể. |
is_refresh | boolean | false | Sử dụng tham số này, bạn có thể cập nhật thời hạn tồn tại và nhận địa chỉ mới cho hóa đơn nếu thời hạn tồn tại đã hết.Để thực hiện điều đó, bạn cần truyền tất cả các tham số bắt buộc và hóa đơn có order_id được truyền sẽ được làm mới.Chỉ có address, payment_status và expired_at được thay đổi. Không có trường nào khác bị thay đổi, bất kể các tham số được truyền vào. |
Kiểu tham số
stringSự định nghĩa
Số tiền phải trả.Nếu có xu trong số tiền, hãy gửi chúng với dấu phân cách '.'
Ví dụ: 10.28Kiểu tham số
stringSự định nghĩa
Mã tiền tệKiểu tham số
stringmin: 1max: 128alpha_dashSự định nghĩa
ID đơn hàng trong hệ thống của bạnTham số phải là một chuỗi bao gồm các ký tự chữ cái, số, dấu gạch dưới và dấu gạch ngang. Chuỗi không được chứa bất kỳ khoảng trắng hoặc ký tự đặc biệt nào. order_id phải là duy nhất trong hóa đơn của người bán/ví tĩnh/thanh toán định kỳKhi chúng tôi tìm thấy hóa đơn hiện có với order_id, chúng tôi sẽ trả về thông tin chi tiết của hóa đơn đó, hóa đơn mới sẽ không được tạo.Kiểu tham số
stringSự định nghĩa
Mã mạng BlockchainKiểu tham số
stringmin: 6max: 255urlSự định nghĩa
Trước khi thanh toán, người dùng có thể nhấp vào nút trên biểu mẫu thanh toán và quay lại trang cửa hàng tại URL này.Kiểu tham số
stringmin: 6max: 255urlSự định nghĩa
Sau khi thanh toán thành công, người dùng có thể nhấp vào nút trên biểu mẫu thanh toán và quay lại URL này.Kiểu tham số
stringmin: 6max: 255urlSự định nghĩa
URL mà webhooks có trạng thái thanh toán sẽ được gửi đếnKiểu tham số
booleanSự định nghĩa
Cho phép người dùng thanh toán số tiền còn lại. Điều này hữu ích khi người dùng chưa thanh toán toàn bộ số tiền trên hóa đơn cho một giao dịch và bạn muốn cho phép họ thanh toán đến hết số tiền. Nếu bạn tắt tính năng này, hóa đơn sẽ được hoàn tất sau khi nhận được khoản thanh toán đầu tiên và bạn sẽ nhận được tiền vào số dư của mình.Kiểu tham số
integermin: 300max: 43200Sự định nghĩa
Tuổi thọ của hóa đơn đã phát hành (tính bằng giây)Kiểu tham số
stringSự định nghĩa
Tham số này được sử dụng để chỉ định loại tiền tệ mục tiêu để chuyển đổi số tiền trên hóa đơn. Khi tạo hóa đơn, bạn cung cấp số tiền và loại tiền tệ, và API sẽ chuyển đổi số tiền đó sang giá trị tương đương trong biến to_currency.Ví dụ, để tạo hóa đơn trị giá 20 USD bằng bitcoin:
số tiền: 20
tiền tệ: USD
to_currency: BTCAPI sẽ chuyển đổi số tiền 20 USD sang số tiền tương đương bằng BTC dựa trên tỷ giá hối đoái hiện tại và người dùng sẽ thanh toán bằng BTCto_currency phải luôn là mã tiền điện tử, không phải mã tiền pháp định.Kiểu tham số
integermin: 0max: 100Sự định nghĩa
Tỷ lệ phần trăm hoa hồng thanh toán được tính cho khách hàngNếu bạn có tỷ lệ là 1%, thì nếu bạn tạo hóa đơn cho 100 USDT với trừ đi = 100 (khách hàng trả 100% hoa hồng), thì khách hàng sẽ phải trả 101 USDT.Kiểu tham số
numericmin: 0max: 5Sự định nghĩa
Độ chính xác chấp nhận được trong thanh toán.Ví dụ, nếu bạn nhập giá trị 5, hóa đơn sẽ được đánh dấu là Đã thanh toán ngay cả khi khách hàng chỉ thanh toán 95% số tiền.Số tiền thanh toán thực tế sẽ được ghi có vào số dưKiểu tham số
stringmax: 255Sự định nghĩa
Thông tin bổ sung dành cho bạn (không hiển thị cho khách hàng)Kiểu tham số
arraySự định nghĩa
Danh sách các loại tiền tệ được phép thanh toán. Điều này hữu ích nếu bạn muốn giới hạn danh sách các loại tiền mà khách hàng có thể sử dụng để thanh toán hóa đơn. Kết cấuKiểu tham số
arraySự định nghĩa
Danh sách các loại tiền tệ không được thanh toán Kết cấuKiểu tham số
stringmin: 4max: 20
Các giá trị có sẵn- Binance- BinanceP2P- Exmo- KucoinSự định nghĩa
Dịch vụ lấy tỷ giá hối đoái để quy đổi trên hóa đơn.Kiểu tham số
stringSự định nghĩa
Người bán đưa ra yêu cầu sẽ kết nối với người giới thiệu bằng mã.Ví dụ: bạn là một ứng dụng tạo hóa đơn thông qua API Cryptomus và khách hàng của bạn là các cửa hàng khác.
Họ nhập khóa API và ID người bán vào ứng dụng của bạn, và bạn gửi yêu cầu kèm theo thông tin đăng nhập của họ và mã giới thiệu của bạn.Vì vậy, khách hàng của bạn sẽ trở thành người giới thiệu vào tài khoản Cryptomus của bạn và bạn sẽ nhận được thu nhập từ doanh thu của họ.Kiểu tham số
integermin: -99max: 100Sự định nghĩa
Số dương:
Cho phép bạn thiết lập mức chiết khấu.
Để thiết lập mức chiết khấu 5% cho khoản thanh toán, bạn phải truyền giá trị: 5Số âm:
Cho phép bạn thiết lập hoa hồng bổ sung tùy chỉnh.Để thiết lập thêm hoa hồng 10% cho khoản thanh toán, bạn phải truyền giá trị: -10Tỷ lệ chiết khấu khi tạo hóa đơn chỉ được tính đến nếu hóa đơn đó có loại tiền điện tử cụ thể.Kiểu tham số
booleanSự định nghĩa
Sử dụng tham số này, bạn có thể cập nhật thời hạn tồn tại và nhận địa chỉ mới cho hóa đơn nếu thời hạn tồn tại đã hết.Để thực hiện điều đó, bạn cần truyền tất cả các tham số bắt buộc và hóa đơn có order_id được truyền sẽ được làm mới.Chỉ có address, payment_status và expired_at được thay đổi. Không có trường nào khác bị thay đổi, bất kể các tham số được truyền vào.
* - tham số bắt buộc
Cấu trúc của Tiền tệ
Tên | Sự định nghĩa |
---|---|
currency* | Mã tiền tệ |
network | Mã mạng Blockchain |
Sự định nghĩa
Mã tiền tệSự định nghĩa
Mã mạng Blockchain
* - tham số bắt buộc
Cấu trúc của except_currencies
Tên | Sự định nghĩa |
---|---|
currency* | Mã tiền tệ |
network | Mã mạng Blockchain |
Sự định nghĩa
Mã tiền tệSự định nghĩa
Mã mạng Blockchain
* - tham số bắt buộc
Ví dụ yêu cầu
Dưới đây là một ví dụ mẫu với số lượng tham số tối thiểu cần thiết. Trong trường hợp này, hóa đơn sẽ được tạo bằng tiền pháp định USD. Trên trang thanh toán, người dùng sẽ có thể chọn loại tiền điện tử và mạng lưới để thanh toán hóa đơn này.
curl https://api.cryptomus.com/v1/payment \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
"amount": "15",
"currency": "USD",
"order_id": "1"
}'
Sao chépPhản ứng
Các thông số phản hồi
Tên | Sự định nghĩa |
---|---|
uuid | Hóa đơn uuid |
order_id | ID đơn hàng trong hệ thống của bạn |
amount | Số tiền của hóa đơn |
payment_amount | Số tiền khách hàng trả |
payer_amount | Số tiền theo tiền_thanh_toánmà khách hàng phải trả, bao gồm cả chiết khấu hoặc hoa hồng bổ sung. |
discount_percent | Tỷ lệ phần trăm chiết khấu hoặc hoa hồng bổ sung được truyền vào các tham số yêu cầu |
discount | Số tiền chiết khấu thực tế hoặc hoa hồng bổ sung bằng tiền điện tử.Ví dụ, nếu số tiền hóa đơn là 15 USDT và discount_percent là -5, giá trị chiết khấu sẽ là -0,75tức là số tiền + chiết khấu = số tiền người trả tiền |
payer_currency | Loại tiền tệ mà khách hàng phải sử dụng để thanh toán. |
currency | Mã tiền tệ hóa đơn |
merchant_amount | Số tiền bằng tiền điện tử sẽ được ghi có vào số dư của bạn. Nếu không chỉ định invoice payer_currency, giá trị sẽ là null. |
network | Mã mạng Blockchain |
address | Địa chỉ ví để thanh toán |
from | Địa chỉ ví mà khoản thanh toán được thực hiện |
txid | Băm giao dịch |
payment_status | Trạng thái thanh toán Tất cả trạng thái thanh toán |
url | Trang thanh toán URL |
expired_at | Dấu thời gian hết hạn của hóa đơn |
is_final | Hóa đơn đã được hoàn tất chưa.Khi hóa đơn được hoàn tất, không thể thanh toán hóa đơn (hóa đơn đã được thanh toán hoặc đã hết hạn) |
additional_data | Thông tin bổ sung |
created_at | Ngày tạo hóa đơn. Múi giờ là UTC+3 |
updated_at | Ngày cập nhật hóa đơn gần nhất. Múi giờ là UTC+3 |
Sự định nghĩa
Hóa đơn uuidSự định nghĩa
ID đơn hàng trong hệ thống của bạnSự định nghĩa
Số tiền của hóa đơnSự định nghĩa
Số tiền khách hàng trảSự định nghĩa
Số tiền theo tiền_thanh_toánmà khách hàng phải trả, bao gồm cả chiết khấu hoặc hoa hồng bổ sung.Sự định nghĩa
Tỷ lệ phần trăm chiết khấu hoặc hoa hồng bổ sung được truyền vào các tham số yêu cầuSự định nghĩa
Số tiền chiết khấu thực tế hoặc hoa hồng bổ sung bằng tiền điện tử.Ví dụ, nếu số tiền hóa đơn là 15 USDT và discount_percent là -5, giá trị chiết khấu sẽ là -0,75tức là số tiền + chiết khấu = số tiền người trả tiềnSự định nghĩa
Loại tiền tệ mà khách hàng phải sử dụng để thanh toán.Sự định nghĩa
Mã tiền tệ hóa đơnSự định nghĩa
Số tiền bằng tiền điện tử sẽ được ghi có vào số dư của bạn. Nếu không chỉ định invoice payer_currency, giá trị sẽ là null.Sự định nghĩa
Mã mạng BlockchainSự định nghĩa
Địa chỉ ví để thanh toánSự định nghĩa
Địa chỉ ví mà khoản thanh toán được thực hiệnSự định nghĩa
Băm giao dịchSự định nghĩa
Trạng thái thanh toán Tất cả trạng thái thanh toánSự định nghĩa
Trang thanh toán URLSự định nghĩa
Dấu thời gian hết hạn của hóa đơnSự định nghĩa
Hóa đơn đã được hoàn tất chưa.Khi hóa đơn được hoàn tất, không thể thanh toán hóa đơn (hóa đơn đã được thanh toán hoặc đã hết hạn)Sự định nghĩa
Thông tin bổ sungSự định nghĩa
Ngày tạo hóa đơn. Múi giờ là UTC+3Sự định nghĩa
Ngày cập nhật hóa đơn gần nhất. Múi giờ là UTC+3
Ví dụ phản hồi
1{
2 "state": 0,
3 "result": {
4 "uuid": "26109ba0-b05b-4ee0-93d1-fd62c822ce95",
5 "order_id": "1",
6 "amount": "15.00",
7 "payment_amount": null,
8 "payer_amount": null,
9 "discount_percent": null,
10 "discount": "0.00000000",
11 "payer_currency": null,
12 "currency": "USD",
13 "merchant_amount": null,
14 "network": null,
15 "address": null,
16 "from": null,
17 "txid": null,
18 "payment_status": "check",
19 "url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
20 "expired_at": 1689098133,
21 "status": "check",
22 "is_final": false,
23 "additional_data": null,
24 "created_at": "2023-07-11T20:23:52+03:00",
25 "updated_at": "2023-07-11T21:24:17+03:00"
26 }
27}
Sao chépThêm ví dụ
Yêu cầu dữ liệu để tạo hóa đơn 20 USDT trên mạng lưới Tron. Hóa đơn sẽ có địa chỉ tại thời điểm tạo.
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1",
5 "network": "tron"
6}
Sao chépYêu cầu dữ liệu để tạo hóa đơn trị giá 25 USD và cho phép khách hàng chỉ thanh toán bằng USDT trên bất kỳ mạng lưới nào.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT"
6}
Sao chépYêu cầu dữ liệu để tạo hóa đơn 25 USD và cho phép khách hàng chỉ thanh toán bằng USDT trên mạng lưới Tron. Hóa đơn sẽ có địa chỉ tại thời điểm tạo.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT",
6 "network": "tron"
7}
Sao chépYêu cầu dữ liệu để tạo hóa đơn trị giá 20 USDT và cho phép khách hàng thanh toán trên tất cả các mạng lưới khả dụng
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1"
5}
Sao chépYêu cầu dữ liệu để tạo hóa đơn 20 USD và chỉ cho phép khách hàng thanh toán bằng Bitcoin. Hóa đơn sẽ có địa chỉ tại thời điểm tạo.
1{
2 "amount": "20",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "BTC"
6}
Sao chépYêu cầu dữ liệu để tạo hóa đơn 0,5 BTC và chỉ cho phép khách hàng thanh toán bằng Bitcoin. Hóa đơn sẽ có địa chỉ tại thời điểm tạo.
1{
2 "amount": "0.5",
3 "currency": "BTC",
4 "order_id": "1"
5}
Sao chépLỗi có thể xảy ra
Lỗi xác thực
mã số : 422
ví dụ phản hồi:
Nếu một số tham số là bắt buộc và không được truyền:
1{
2 "state": 1,
3 "errors": {
4 "amount": ["validation.required"]
5 }
6}
Sao chépNếu bạn cung cấp mã mạng không được hỗ trợ
1{
2 "state": 1,
3 "message": "The network was not found"
4}
Sao chépNếu chúng tôi không hỗ trợ mã tiền tệ mà bạn cung cấp trong tham số currency:
1{
2 "state": 1,
3 "message": "The currency was not found"
4}
Sao chépNếu thanh toán của bạn bị chặn. Trong trường hợp này, bạn cần liên hệ với bộ phận hỗ trợ.
1{
2 "state": 1,
3 "message": "You are forbidden"
4}
Sao chépNếu chúng ta không tìm thấy dịch vụ thanh toán của loại tiền tệ được truyền vào tham số to_currency:
1{
2 "state": 1,
3 "message": "Not found service to_currency"
4}
Sao chépNếu vô tình có điều gì xảy ra khi chuyển đổi sang to_currency:
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}
Sao chépNếu số tiền thanh toán ít hơn số tiền tối thiểu được hỗ trợ cho tiền điện tử, bạn sẽ nhận được thông báo lỗi này:
1{
2 "state": 1,
3 "message": "Minimum amount 0.5 USDT"
4}
Sao chépNếu số tiền thanh toán lớn hơn số tiền tối đa được hỗ trợ cho tiền điện tử, bạn sẽ nhận được thông báo lỗi này:
1{
2 "state": 1,
3 "message": "Maximum amount 10000000 USDT"
4}
Sao chépNếu bạn không có ví thương mại đang hoạt động với loại tiền điện tử dùng để thanh toán, bạn sẽ nhận được lỗi này:
1{
2 "state": 1,
3 "message": "Wallet not found"
4}
Sao chépNếu xảy ra sự cố kỹ thuật và tạm thời không thể thanh toán, bạn có thể nhận được thông báo lỗi sau:
1{
2 "state": 1,
3 "message": "Gateway error"
4}
Sao chép
1{
2 "state": 1,
3 "message": "The terminal was not found"
4}
Sao chép
1{
2 "state": 1,
3 "message": "Server error"
4}
Sao chépLỗi máy chủ nội bộ
mã số : 500
ví dụ phản hồi:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}
Sao chép