Tạo hóa đơn

post
https://api.cryptomus.com/v1/payment
Sao chép

Lời yêu cầu

Tham số truy vấn

TênKiểu tham sốGiá trị mặc địnhSự định nghĩa
amount*stringSố 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*stringMã tiền tệ
order_id*stringmin: 1max: 128alpha_dashID đơ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.
networkstringnullMã mạng Blockchain
url_returnstringmin: 6max: 255urlnullTrướ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_successstringmin: 6max: 255urlnullSau 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_callbackstringmin: 6max: 255urlnullURL mà webhooks có trạng thái thanh toán sẽ được gửi đến
is_payment_multiplebooleantrueCho 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.
lifetimeintegermin: 300max: 432003600Tuổi thọ của hóa đơn đã phát hành (tính bằng giây)
to_currencystringTham 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: BTC
API 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.
subtractintegermin: 0max: 1000Tỷ 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_percentnumericmin: 0max: 50Độ 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_datastringmax: 255nullThông tin bổ sung dành cho bạn (không hiển thị cho khách hàng)
currenciesarrayMả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_currenciesarraynullDanh sách các loại tiền tệ không được thanh toán Kết cấu
course_sourcestringmin: 4max: 20Các giá trị có sẵnBinanceBinanceP2PExmoKucoinNế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_codestringnullNgườ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_percentintegermin: -99max: 100nullSố 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ị: 5
Số â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_refreshbooleanfalseSử 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_statusexpired_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ố

string

Sự đị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.28

Kiểu tham số

string

Sự định nghĩa

Mã tiền tệ

Kiểu tham số

stringmin: 1max: 128alpha_dash

Sự đị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ố

string

Sự định nghĩa

Mã mạng Blockchain

Kiểu tham số

stringmin: 6max: 255url

Sự đị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: 255url

Sự đị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: 255url

Sự định nghĩa

URL mà webhooks có trạng thái thanh toán sẽ được gửi đến

Kiểu tham số

boolean

Sự đị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: 43200

Sự đị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ố

string

Sự đị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: BTC
API 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: 100

Sự đị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: 5

Sự đị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: 255

Sự đị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ố

array

Sự đị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ấu

Kiểu tham số

array

Sự định nghĩa

Danh sách các loại tiền tệ không được thanh toán Kết cấu

Kiểu tham số

stringmin: 4max: 20
Các giá trị có sẵn
- Binance- BinanceP2P- Exmo- Kucoin

Sự đị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ố

string

Sự đị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: 100

Sự đị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ị: 5
Số â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ố

boolean

Sự đị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_statusexpired_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ênSự định nghĩa
currency*Mã tiền tệ
networkMã 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ênSự định nghĩa
currency*Mã tiền tệ
networkMã 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

Hóa đơn sẽ có một loại tiền điện tử và địa chỉ cụ thể tại thời điểm tạo chỉ khi tham số currency hoặc to_currency là một loại tiền điện tử và tham số mạng được truyền (hoặc một loại tiền điện tử chỉ có một mạng, ví dụ: BTC).

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ép

Phản ứng

Các thông số phản hồi

TênSự định nghĩa
uuidHóa đơn uuid
order_idID đơn hàng trong hệ thống của bạn
amountSố tiền của hóa đơn
payment_amountSố tiền khách hàng trả
payer_amountSố 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_percentTỷ 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
discountSố 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_currencyLoại tiền tệ mà khách hàng phải sử dụng để thanh toán.
currencyMã tiền tệ hóa đơn
merchant_amountSố 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.
networkMã 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
txidBăm giao dịch
payment_statusTrạng thái thanh toán Tất cả trạng thái thanh toán
urlTrang thanh toán URL
expired_atDấu thời gian hết hạn của hóa đơn
is_finalHó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_dataThông tin bổ sung
created_atNgày tạo hóa đơn. Múi giờ là UTC+3
updated_atNgà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 uuid

Sự định nghĩa

ID đơn hàng trong hệ thống của bạn

Sự định nghĩa

Số tiền của hóa đơn

Sự đị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ầu

Sự đị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ền

Sự đị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 đơn

Sự đị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 Blockchain

Sự định nghĩa

Địa chỉ ví để thanh toán

Sự định nghĩa

Địa chỉ ví mà khoản thanh toán được thực hiện

Sự định nghĩa

Băm giao dịch

Sự định nghĩa

Trạng thái thanh toán Tất cả trạng thái thanh toán

Sự định nghĩa

Trang thanh toán URL

Sự định nghĩa

Dấu thời gian hết hạn của hóa đơn

Sự đị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ổ sung

Sự định nghĩa

Ngày tạo hóa đơn. Múi giờ là UTC+3

Sự đị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ép

Thê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ép

Yê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ép

Yê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ép

Yê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ép

Yê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ép

Yê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ép

Lỗ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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Nế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ép

Lỗ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