建立發票

post
https://api.cryptomus.com/v1/payment
複製

要求

查詢參數

姓名參數類型預設值定義
amount*string待付金額。如果金額中有便士，則使用分隔符號“.”發送。
例如：10.28
currency*string貨幣代碼
order_id*stringmin: 1max: 128alpha_dash您系統中的訂單 ID參數應為由字母、數字、底線和短劃線組成的字串，不能包含空格和特殊字元。 order_id 在商家發票/靜態錢包/定期付款中必須是唯一的當我們找到帶有 order_id 的現有發票時，我們會返回其詳細信息，不會建立新的發票。
networkstringnull區塊鏈網路程式碼
url_returnstringmin: 6max: 255urlnull在付款之前，用戶可以點擊付款表單上的按鈕並返回此 URL 的商店頁面。
url_successstringmin: 6max: 255urlnull付款成功後，使用者可以點擊付款表單上的按鈕並返回此URL。
url_callbackstringmin: 6max: 255urlnull發送付款狀態 webhook 的 URL
is_payment_multiplebooleantrue是否允許用戶支付剩餘金額。當用戶未支付單筆交易的全部發票金額，而您希望允許其支付全額時，此功能非常有用。如果您停用此功能，發票將在收到首筆付款後完成，您的餘額中將收到款項。
lifetimeintegermin: 300max: 432003600開立發票的有效期限（以秒為單位）
to_currencystring此參數用於指定發票金額換算的目標貨幣。建立發票時，您需要提供金額和貨幣，API 會將該金額轉換為 to_currency 中的等值金額。例如，要建立一張 20 美元的比特幣發票：
amount: 20
currency: USD
to_currency: BTCAPI 將根據當前匯率將 20 美元轉換為等值的 BTC，用戶將以 BTC 支付to_currency 應該始終是加密貨幣代碼，而不是法定貨幣代碼。
subtractintegermin: 0max: 1000向客戶收取的付款佣金百分比如果您的費率為 1%，那麼如果您建立 100 USDT 的發票，減去 = 100（客戶支付 100% 的佣金），則客戶必須支付 101 USDT。
accuracy_payment_percentnumericmin: 0max: 50可以接受的付款不準確性。例如，如果您傳遞價值 5，即使客戶只支付了 95% 的金額，發票也會被標記為已付款。實際付款金額將記入餘額
additional_datastringmax: 255null您的附加資訊（不向客戶顯示）
currenciesarray使用商家設定中可用的貨幣數組（如果未設定該參數，則預設使用所有支援的加密貨幣）。可用的貨幣在商家設定部分設定。允許付款的貨幣清單。如果您想限制客戶可用於支付發票的貨幣列表，這將非常有用。 結構
except_currenciesarraynull不予支付的貨幣列表 結構
course_sourcestringmin: 4max: 20可用值• Binance• BinanceP2P• Exmo• Kucoin如果未通過，則使用 Cryptomus 匯率。發票中採用其匯率轉換的服務。
from_referral_codestringnull提出請求的商家透過代碼連接到推薦人。例如，您是一個透過 Cryptomus API 產生發票的應用程序，您的客戶是其他商店。
他們在您的應用程式中輸入他們的 API 金鑰和商家 ID，然後您使用他們的憑證發送請求並傳遞您的推薦代碼。因此，您的客戶將成為您的 Cryptomus 帳戶的推薦人，並且您將從他們的營業額中獲得收入。
discount_percentintegermin: -99max: 100null正數：
允許您設定折扣。
要為付款設定 5% 的折扣，您應該傳遞一個值：5負數：
允許您設定自訂的額外佣金。要為付款設定 10% 的額外佣金，您應該傳遞一個值：-10只有當發票具有特定的加密貨幣時，才會考慮建立發票時的折扣百分比。
is_refreshbooleanfalse使用此參數，您可以更新有效期，如果有效期已過期，則可以獲得發票的新地址。為此，您需要傳遞所有必要的參數，並且傳遞的 order_id 的發票將被刷新。僅 address、payment_status 和 expired_at 欄位會改變。其他欄位無論傳遞什麼參數，都不會改變。

參數類型

string

定義

待付金額。如果金額中有便士，則使用分隔符號“.”發送。
例如：10.28

參數類型

string

定義

貨幣代碼

參數類型

stringmin: 1max: 128alpha_dash

定義

您系統中的訂單 ID參數應為由字母、數字、底線和短劃線組成的字串，不能包含空格和特殊字元。 order_id 在商家發票/靜態錢包/定期付款中必須是唯一的當我們找到帶有 order_id 的現有發票時，我們會返回其詳細信息，不會建立新的發票。

參數類型

string

定義

區塊鏈網路程式碼

參數類型

stringmin: 6max: 255url

定義

在付款之前，用戶可以點擊付款表單上的按鈕並返回此 URL 的商店頁面。

參數類型

stringmin: 6max: 255url

定義

付款成功後，使用者可以點擊付款表單上的按鈕並返回此URL。

參數類型

stringmin: 6max: 255url

定義

發送付款狀態 webhook 的 URL

參數類型

boolean

定義

是否允許用戶支付剩餘金額。當用戶未支付單筆交易的全部發票金額，而您希望允許其支付全額時，此功能非常有用。如果您停用此功能，發票將在收到首筆付款後完成，您的餘額中將收到款項。

參數類型

integermin: 300max: 43200

定義

開立發票的有效期限（以秒為單位）

參數類型

string

定義

此參數用於指定發票金額換算的目標貨幣。建立發票時，您需要提供金額和貨幣，API 會將該金額轉換為 to_currency 中的等值金額。例如，要建立一張 20 美元的比特幣發票：
amount: 20
currency: USD
to_currency: BTCAPI 將根據當前匯率將 20 美元轉換為等值的 BTC，用戶將以 BTC 支付to_currency 應該始終是加密貨幣代碼，而不是法定貨幣代碼。

參數類型

integermin: 0max: 100

定義

向客戶收取的付款佣金百分比如果您的費率為 1%，那麼如果您建立 100 USDT 的發票，減去 = 100（客戶支付 100% 的佣金），則客戶必須支付 101 USDT。

參數類型

numericmin: 0max: 5

定義

可以接受的付款不準確性。例如，如果您傳遞價值 5，即使客戶只支付了 95% 的金額，發票也會被標記為已付款。實際付款金額將記入餘額

參數類型

stringmax: 255

定義

您的附加資訊（不向客戶顯示）

參數類型

array

定義

允許付款的貨幣清單。如果您想限制客戶可用於支付發票的貨幣列表，這將非常有用。 結構

參數類型

array

定義

不予支付的貨幣列表 結構

參數類型

stringmin: 4max: 20
可用值- Binance- BinanceP2P- Exmo- Kucoin

定義

發票中採用其匯率轉換的服務。

參數類型

string

定義

提出請求的商家透過代碼連接到推薦人。例如，您是一個透過 Cryptomus API 產生發票的應用程序，您的客戶是其他商店。
他們在您的應用程式中輸入他們的 API 金鑰和商家 ID，然後您使用他們的憑證發送請求並傳遞您的推薦代碼。因此，您的客戶將成為您的 Cryptomus 帳戶的推薦人，並且您將從他們的營業額中獲得收入。

參數類型

integermin: -99max: 100

定義

正數：
允許您設定折扣。
要為付款設定 5% 的折扣，您應該傳遞一個值：5負數：
允許您設定自訂的額外佣金。要為付款設定 10% 的額外佣金，您應該傳遞一個值：-10只有當發票具有特定的加密貨幣時，才會考慮建立發票時的折扣百分比。

參數類型

boolean

定義

使用此參數，您可以更新有效期，如果有效期已過期，則可以獲得發票的新地址。為此，您需要傳遞所有必要的參數，並且傳遞的 order_id 的發票將被刷新。僅 address、payment_status 和 expired_at 欄位會改變。其他欄位無論傳遞什麼參數，都不會改變。

* - 必需參數

結構 貨幣

姓名定義
currency*貨幣代碼
network區塊鏈網路程式碼

定義

貨幣代碼

定義

區塊鏈網路程式碼

* - 必需參數

結構 except_currencies

姓名定義
currency*貨幣代碼
network區塊鏈網路程式碼

定義

貨幣代碼

定義

區塊鏈網路程式碼

* - 必需參數

只有當貨幣或 to_currency 參數是加密貨幣並且傳遞了網絡參數（或加密貨幣只有一個網絡，例如 BTC）時，發票才會在創建時具有特定的加密貨幣和地址。

請求範例

以下是一個包含最低要求參數數量的範例。在本例中，將使用法定貨幣美元建立發票。在付款頁面上，用戶可以選擇加密貨幣和支付網路來支付此帳單。


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"
}'
複製

回覆

響應參數

姓名定義
uuid發票 UUID
order_id您系統中的訂單 ID
amount發票金額
payment_amount客戶支付的金額
payer_amount客戶必須支付的payer_currency金額，包括折扣或額外佣金。
discount_percent在請求參數中傳遞的折扣或額外佣金的百分比
discount以加密貨幣計算的實際折扣或額外佣金金額。例如，如果發票金額為 15 USDT，折扣百分比為 -5，則折扣值為 -0.75即 金額 + 折扣 = 付款人金額
payer_currency客戶必須用來付款的貨幣。
currency發票貨幣代碼
merchant_amount將記入您餘額的加密貨幣金額。如果未指定發票付款人貨幣 (payer_currency)，則該值為空。
network區塊鏈網路程式碼
address支付錢包地址
from付款錢包的地址
txid交易哈希
payment_status付款狀態 所有付款狀態
url支付頁面URL
expired_at發票到期時間戳
is_final發票是否已最終確定。當發票最終確定後，無法支付發票（已付款或已過期）
additional_data附加資訊
created_at發票建立日期。時區為 UTC+3
updated_at上次發票更新日期。時區為 UTC+3

定義

發票 UUID

定義

您系統中的訂單 ID

定義

發票金額

定義

客戶支付的金額

定義

客戶必須支付的payer_currency金額，包括折扣或額外佣金。

定義

在請求參數中傳遞的折扣或額外佣金的百分比

定義

以加密貨幣計算的實際折扣或額外佣金金額。例如，如果發票金額為 15 USDT，折扣百分比為 -5，則折扣值為 -0.75即 金額 + 折扣 = 付款人金額

定義

客戶必須用來付款的貨幣。

定義

發票貨幣代碼

定義

將記入您餘額的加密貨幣金額。如果未指定發票付款人貨幣 (payer_currency)，則該值為空。

定義

區塊鏈網路程式碼

定義

支付錢包地址

定義

付款錢包的地址

定義

交易哈希

定義

付款狀態 所有付款狀態

定義

支付頁面URL

定義

發票到期時間戳

定義

發票是否已最終確定。當發票最終確定後，無法支付發票（已付款或已過期）

定義

附加資訊

定義

發票建立日期。時區為 UTC+3

定義

上次發票更新日期。時區為 UTC+3

回應範例


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}
複製

更多範例

請求資料以在波場網路中建立一張價值 20 USDT 的發票。發票在建立時會包含一個地址。


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5	"network": "tron"
6}
複製

請求資料來建立 25 美元的發票，並允許客戶在任何網路中僅使用 USDT 付款。


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT"
6}
複製

請求資料以建立 25 美元的發票，並允許客戶在波場網路中僅使用 USDT 付款。發票在建立時將包含一個地址。


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT",
6	"network": "tron"
7}
複製

請求資料以建立 20 USDT 的發票並允許客戶在所有可用網路中付款


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1"
5}
複製

請求資料以建立一張 20 美元的發票，並允許客戶僅使用比特幣支付。發票在建立時會包含一個地址。


1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}
複製

請求資料以建立 0.5 BTC 的發票，並允許客戶僅使用比特幣付款。發票在建立時會包含一個地址。


1{
2	"amount": "0.5",
3	"currency": "BTC",
4	"order_id": "1"
5}
複製

可能的錯誤

驗證錯誤

程式碼 : 422

範例回覆：

如果需要某些參數但未傳遞：


1{
2	"state": 1,
3	"errors": {
4		"amount": ["validation.required"]
5	}
6}
複製

如果您提供的網路程式碼不受支援


1{
2    "state": 1,
3    "message": "The network was not found"
4}
複製

如果我們不支援您在 currency 參數中提供的貨幣代碼：


1{
2    "state": 1,
3    "message": "The currency was not found"
4}
複製

如果您的付款被凍結，您需要聯絡客服。


1{
2    "state": 1,
3    "message": "You are forbidden"
4}
複製

如果我們沒有找到在 to_currency 參數中傳遞的貨幣的支付服務：


1{
2    "state": 1,
3    "message": "Not found service to_currency"
4}
複製

如果在轉換為 to_currency 時意外發生某些事情：


1{
2    "state": 1,
3    "message": "Error convert to_currency"
4}
複製

如果付款金額低於加密貨幣支援的最低金額，您將收到此錯誤訊息：


1{
2    "state": 1,
3    "message": "Minimum amount 0.5 USDT"
4}
複製

如果付款金額大於加密貨幣支援的最大金額，您將收到此錯誤訊息：


1{
2    "state": 1,
3    "message": "Maximum amount 10000000 USDT"
4}
複製

如果您沒有包含用於付款的加密貨幣的有效商家錢包，您將收到此錯誤：


1{
2    "state": 1,
3    "message": "Wallet not found"
4}
複製

如果發生技術問題且付款暫時無法使用，您可能會收到以下錯誤訊息：


1{
2    "state": 1,
3    "message": "Gateway error"
4}
複製


1{
2    "state": 1,
3    "message": "The terminal was not found"
4}
複製


1{
2    "state": 1,
3    "message": "Server error"
4}
複製

內部伺服器錯誤

程式碼 : 500

範例回覆：


1{
2	"message": "Server error, #1",
3	"code": 500,
4	"error": null
5}
複製