إنشاء فاتورة
طلب
معلمات الاستعلام
| اسم | نوع المعلمة | القيمة الافتراضية | تعريف | 
|---|---|---|---|
| amount* | string | - | المبلغ المستحق للدفع.إذا كانت هناك بنسات في المبلغ ، فأرسلها مع فاصل ".مثال: 10.28 | 
| currency* | string | - | رمز العملة | 
| order_id* | stringmin: 1max: 128alpha_dash | - | طلب معرف في نظامكيجب أن تكون المعلمة عبارة عن سلسلة تتكون من الأحرف الأبجدية والأرقام والرسومات الساحرة والشرطات. لا ينبغي أن تحتوي على أي مسافات أو أحرف خاصة.يجب أن يكون order_id فريدًا داخل فواتير التاجر/محافظ ثابتة/مدفوعات تكرارعندما نجد فاتورة موجودة مع order_id ، نعيد تفاصيلها ، ولن يتم إنشاء فاتورة جديدة. | 
| network | string | null | رمز شبكة blockchain | 
| url_return | stringmin: 6max: 255url | null | قبل الدفع ، يمكن للمستخدم النقر فوق الزر الموجود في نموذج الدفع والعودة إلى صفحة المتجر في عنوان URL هذا. | 
| url_success | stringmin: 6max: 255url | null | بعد الدفع الناجح ، يمكن للمستخدم النقر على الزر الموجود في نموذج الدفع والعودة إلى عنوان URL هذا. | 
| url_callback | stringmin: 6max: 255url | null | عنوان URL الذي سيتم إرسال webhooks مع حالة الدفع إليه | 
| is_payment_multiple | boolean | true | ما إذا كان المستخدم مسموحًا بدفع المبلغ المتبقي. يكون هذا مفيدًا عندما لا يدفع المستخدم كامل المبلغ من الفاتورة لمعاملة واحدة ، وتريد أن تسمح له بدفع المبلغ بالكامل. إذا قمت بتعطيل هذه الميزة ، فستنتهي الفاتورة بعد تلقي الدفعة الأولى وستتلقى أموالًا لتحقيق رصيدك. | 
| lifetime | integermin: 300max: 43200 | 3600 | عمر الفاتورة الصادرة (بالثواني) | 
| to_currency | string | - | يتم استخدام المعلمة لتحديد العملة المستهدفة لتحويل مبلغ الفاتورة. عند إنشاء فاتورة ، يمكنك تقديم مبلغ وعملة ، وسيقوم واجهة برمجة التطبيقات بتحويل هذا المبلغ إلى القيمة المكافئة في to_currency.على سبيل المثال ، لإنشاء فاتورة مقابل 20 دولارًا في Bitcoin: amount : 20 currency : USD to_currency : BTCسيقوم API بتحويل مبلغ 20 دولارًا أمريكيًا إلى ما يعادلها في BTC بناءً على سعر الصرف الحالي وسيدفع المستخدم في BTCيجب أن يكون to_currency دائمًا رمز العملة المشفرة ، وليس رمز العملة Fiat. | 
| subtract | integermin: 0max: 100 | 0 | النسبة المئوية لجنة الدفع التي يتم فرضها على العميلإذا كان لديك معدل 1 ٪ ، فعندئذٍ ، إذا قمت بإنشاء فاتورة مقابل 100 دولار أمريكي مع طرح = 100 (يدفع العميل عمولة بنسبة 100 ٪) ، فسيتعين على العميل دفع 101 USDT. | 
| accuracy_payment_percent | numericmin: 0max: 5 | 0 | عدم دقة مقبولة في الدفع.على سبيل المثال ، إذا قمت بتمرير القيمة 5 ، فسيتم تمييز الفاتورة على أنها مدفوعة حتى لو دفع العميل 95 ٪ فقط من المبلغ.سيتم إضافة مبلغ الدفع الفعلي إلى الرصيد | 
| additional_data | stringmax: 255 | null | معلومات إضافية لك (لا تظهر للعميل) | 
| currencies | array | يتم استخدام مجموعة من العملات المتاحة من إعدادات التاجر (إذا لم يتم تعيين المعلمة ، يتم استخدام جميع العملات المشفرة المدعومة افتراضيًا).يتم تعيين العملات المتاحة في قسم إعدادات التاجر. | قائمة العملات المسموح بها للدفع. هذا مفيد إذا كنت ترغب في الحد من قائمة العملات المعدنية التي يمكن لعملائك استخدامها لدفع الفواتير. بناء | 
| except_currencies | array | null | قائمة العملات المستبعدة للدفع بناء | 
| course_source | stringmin: 4max: 20القيم المتاحة• Binance• BinanceP2P• Exmo• Kucoin | إذا لم يتم تمريرها ، يتم استخدام أسعار صرف Cryptomus. | الخدمة التي يتم من خلالها أخذ أسعار الصرف للتحويل في الفاتورة. | 
| from_referral_code | string | null | التاجر الذي يقوم بتوصيل الطلب يتصل إلى إحالة حسب الرمز.على سبيل المثال ، أنت تطبيق يقوم بإنشاء فواتير عبر واجهة برمجة تطبيقات Cryptomus وعملائك متاجر أخرى. كود الإحالة.وبالتالي ، يصبح عملاؤك إحالات على حساب Cryptomus الخاص بك وسوف تتلقى دخلًا من معدل دورانهم. | 
| discount_percent | integermin: -99max: 100 | null | الأرقام الإيجابية: يتيح لك تعيين خصم. لتعيين خصم 5 ٪ للدفع ، يجب أن تمرير قيمة: 5الأرقام السلبية: يتيح لك تعيين عمولة إضافية مخصصة.لتحديد عمولة إضافية بنسبة 10 ٪ للدفع ، يجب أن تمرير قيمة: -10يتم أخذ نسبة الخصم عند إنشاء فاتورة في الاعتبار فقط إذا كانت الفاتورة تحتوي على عملة مشفرة محددة. | 
| is_refresh | boolean | false | باستخدام هذه المعلمة ، يمكنك تحديث مدى الحياة والحصول على عنوان جديد للفاتورة إذا انتهت صلاحية العمر.للقيام بذلك ، تحتاج إلى تمرير جميع المعلمات المطلوبة ، وسيتم تحديث الفاتورة مع Order_id.فقط address و payment_status و expired_at يتم تغييره. لا يتم تغيير الحقول الأخرى ، بغض النظر عن المعلمات التي تم تمريرها. | 
- نوع المعلمة string- تعريف المبلغ المستحق للدفع.إذا كانت هناك بنسات في المبلغ ، فأرسلها مع فاصل
 ".مثال: 10.28
- نوع المعلمة string- تعريف رمز العملة
- نوع المعلمة stringmin: 1max: 128alpha_dash- تعريف طلب معرف في نظامكيجب أن تكون المعلمة عبارة عن سلسلة تتكون من الأحرف الأبجدية والأرقام والرسومات الساحرة والشرطات. لا ينبغي أن تحتوي على أي مسافات أو أحرف خاصة.يجب أن يكون order_id فريدًا داخل فواتير التاجر/محافظ ثابتة/مدفوعات تكرارعندما نجد فاتورة موجودة مع order_id ، نعيد تفاصيلها ، ولن يتم إنشاء فاتورة جديدة.
- نوع المعلمة string- القيمة الافتراضية null- تعريف رمز شبكة blockchain
- نوع المعلمة stringmin: 6max: 255url- القيمة الافتراضية null- تعريف قبل الدفع ، يمكن للمستخدم النقر فوق الزر الموجود في نموذج الدفع والعودة إلى صفحة المتجر في عنوان URL هذا.
- نوع المعلمة stringmin: 6max: 255url- القيمة الافتراضية null- تعريف بعد الدفع الناجح ، يمكن للمستخدم النقر على الزر الموجود في نموذج الدفع والعودة إلى عنوان URL هذا.
- نوع المعلمة stringmin: 6max: 255url- القيمة الافتراضية null- تعريف عنوان URL الذي سيتم إرسال webhooks مع حالة الدفع إليه
- نوع المعلمة boolean- القيمة الافتراضية true- تعريف ما إذا كان المستخدم مسموحًا بدفع المبلغ المتبقي. يكون هذا مفيدًا عندما لا يدفع المستخدم كامل المبلغ من الفاتورة لمعاملة واحدة ، وتريد أن تسمح له بدفع المبلغ بالكامل. إذا قمت بتعطيل هذه الميزة ، فستنتهي الفاتورة بعد تلقي الدفعة الأولى وستتلقى أموالًا لتحقيق رصيدك.
- نوع المعلمة integermin: 300max: 43200- القيمة الافتراضية 3600- تعريف عمر الفاتورة الصادرة (بالثواني)
- نوع المعلمة string- تعريف يتم استخدام المعلمة لتحديد العملة المستهدفة لتحويل مبلغ الفاتورة. عند إنشاء فاتورة ، يمكنك تقديم مبلغ وعملة ، وسيقوم واجهة برمجة التطبيقات بتحويل هذا المبلغ إلى القيمة المكافئة في to_currency.على سبيل المثال ، لإنشاء فاتورة مقابل 20 دولارًا في Bitcoin:
 amount : 20
 currency : USD
 to_currency : BTCسيقوم API بتحويل مبلغ 20 دولارًا أمريكيًا إلى ما يعادلها في BTC بناءً على سعر الصرف الحالي وسيدفع المستخدم في BTCيجب أن يكون to_currency دائمًا رمز العملة المشفرة ، وليس رمز العملة Fiat.
- نوع المعلمة integermin: 0max: 100- القيمة الافتراضية 0- تعريف النسبة المئوية لجنة الدفع التي يتم فرضها على العميلإذا كان لديك معدل 1 ٪ ، فعندئذٍ ، إذا قمت بإنشاء فاتورة مقابل 100 دولار أمريكي مع طرح = 100 (يدفع العميل عمولة بنسبة 100 ٪) ، فسيتعين على العميل دفع 101 USDT.
- نوع المعلمة numericmin: 0max: 5- القيمة الافتراضية 0- تعريف عدم دقة مقبولة في الدفع.على سبيل المثال ، إذا قمت بتمرير القيمة 5 ، فسيتم تمييز الفاتورة على أنها مدفوعة حتى لو دفع العميل 95 ٪ فقط من المبلغ.سيتم إضافة مبلغ الدفع الفعلي إلى الرصيد
- نوع المعلمة stringmax: 255- القيمة الافتراضية null- تعريف معلومات إضافية لك (لا تظهر للعميل)
- نوع المعلمة array- القيمة الافتراضية يتم استخدام مجموعة من العملات المتاحة من إعدادات التاجر (إذا لم يتم تعيين المعلمة ، يتم استخدام جميع العملات المشفرة المدعومة افتراضيًا).يتم تعيين العملات المتاحة في قسم إعدادات التاجر.- تعريف قائمة العملات المسموح بها للدفع. هذا مفيد إذا كنت ترغب في الحد من قائمة العملات المعدنية التي يمكن لعملائك استخدامها لدفع الفواتير. بناء
- نوع المعلمة stringmin: 4max: 20
 القيم المتاحة- Binance- BinanceP2P- Exmo- Kucoin- القيمة الافتراضية إذا لم يتم تمريرها ، يتم استخدام أسعار صرف Cryptomus.
 القيم المتاحة- Binance- BinanceP2P- Exmo- Kucoin- تعريف الخدمة التي يتم من خلالها أخذ أسعار الصرف للتحويل في الفاتورة.
- نوع المعلمة string- القيمة الافتراضية null- تعريف التاجر الذي يقوم بتوصيل الطلب يتصل إلى إحالة حسب الرمز.على سبيل المثال ، أنت تطبيق يقوم بإنشاء فواتير عبر واجهة برمجة تطبيقات Cryptomus وعملائك متاجر أخرى. كود الإحالة.وبالتالي ، يصبح عملاؤك إحالات على حساب Cryptomus الخاص بك وسوف تتلقى دخلًا من معدل دورانهم.
- نوع المعلمة integermin: -99max: 100- القيمة الافتراضية null- تعريف الأرقام الإيجابية:
 يتيح لك تعيين خصم.
 لتعيين خصم 5 ٪ للدفع ، يجب أن تمرير قيمة: 5الأرقام السلبية:
 يتيح لك تعيين عمولة إضافية مخصصة.لتحديد عمولة إضافية بنسبة 10 ٪ للدفع ، يجب أن تمرير قيمة: -10يتم أخذ نسبة الخصم عند إنشاء فاتورة في الاعتبار فقط إذا كانت الفاتورة تحتوي على عملة مشفرة محددة.
- نوع المعلمة boolean- القيمة الافتراضية false- تعريف باستخدام هذه المعلمة ، يمكنك تحديث مدى الحياة والحصول على عنوان جديد للفاتورة إذا انتهت صلاحية العمر.للقيام بذلك ، تحتاج إلى تمرير جميع المعلمات المطلوبة ، وسيتم تحديث الفاتورة مع Order_id.فقط address و payment_status و expired_at يتم تغييره. لا يتم تغيير الحقول الأخرى ، بغض النظر عن المعلمات التي تم تمريرها.
* - المعلمة الإلزامية
هيكل العملات
| اسم | تعريف | 
|---|---|
| currency* | رمز العملة | 
| network | رمز شبكة blockchain | 
- تعريف رمز العملة
- تعريف رمز شبكة blockchain
* - المعلمة الإلزامية
هيكل except_currencies
| اسم | تعريف | 
|---|---|
| currency* | رمز العملة | 
| network | رمز شبكة blockchain | 
- تعريف رمز العملة
- تعريف رمز شبكة blockchain
* - المعلمة الإلزامية
طلب مثال
أدناه مثال عينة مع الحد الأدنى لعدد المعلمات. في هذه الحالة ، سيتم إنشاء فاتورة مع عملة FIAT USD. في صفحة الدفع ، سيتمكن المستخدم من تحديد العملة المشفرة والشبكة لدفع هذه الفاتورة.
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 | طلب معرف في نظامك | 
| amount | مقدار الفاتورة | 
| payment_amount | المبلغ الذي يدفعه العميل | 
| payer_amount | المبلغ في payer_currency الذي يجب على العميل دفعه ، بما في ذلك الخصم أو العمولة الإضافية. | 
| discount_percent | النسبة المئوية للخصم أو العمولة الإضافية ، تم إقرارها في معلمات الطلب | 
| discount | المبلغ الفعلي من الخصم أو العمولة الإضافية في العملة المشفرة.على سبيل المثال ، إذا كان مبلغ الفاتورة 15 USDT و DEFICE_PERCENT هو -5 ، فستكون قيمة الخصم -0.75أي amount + discount = payer_amount | 
| payer_currency | العملة التي يجب على العميل القيام بها. | 
| currency | رمز العملة الفاتورة | 
| merchant_amount | المبلغ في التشفير الذي سيتم الفضل في رصيدك. إذا لم يتم تحديد الفاتورة payer_currency ، فستكون القيمة لاغية. | 
| network | رمز شبكة blockchain | 
| address | عنوان محفظة للدفع | 
| from | عنوان المحفظة التي تم إجراء الدفع منها | 
| txid | تجزئة المعاملة | 
| payment_status | حالة السداد جميع حالات الدفع | 
| url | صفحة دفع عنوان URL | 
| expired_at | الطابع الزمني لانتهاء الفاتورة | 
| is_final | ما إذا تم الانتهاء من الفاتورة.عندما يتم الانتهاء من الفاتورة ، يكون من المستحيل دفع فاتورة (إما مدفوعة أو انتهت صلاحيتها) | 
| additional_data | معلومات إضافية | 
| created_at | تاريخ إنشاء الفاتورة. المنطقة الزمنية هي UTC+3 | 
| updated_at | آخر تاريخ تحديث الفاتورة. المنطقة الزمنية هي UTC+3 | 
- تعريف فاتورة uuid
- تعريف طلب معرف في نظامك
- تعريف مقدار الفاتورة
- تعريف المبلغ الذي يدفعه العميل
- تعريف المبلغ في payer_currency الذي يجب على العميل دفعه ، بما في ذلك الخصم أو العمولة الإضافية.
- تعريف النسبة المئوية للخصم أو العمولة الإضافية ، تم إقرارها في معلمات الطلب
- تعريف المبلغ الفعلي من الخصم أو العمولة الإضافية في العملة المشفرة.على سبيل المثال ، إذا كان مبلغ الفاتورة 15 USDT و DEFICE_PERCENT هو -5 ، فستكون قيمة الخصم -0.75أي amount + discount = payer_amount
- تعريف العملة التي يجب على العميل القيام بها.
- تعريف رمز العملة الفاتورة
- تعريف المبلغ في التشفير الذي سيتم الفضل في رصيدك. إذا لم يتم تحديد الفاتورة payer_currency ، فستكون القيمة لاغية.
- تعريف رمز شبكة blockchain
- تعريف عنوان محفظة للدفع
- تعريف عنوان المحفظة التي تم إجراء الدفع منها
- تعريف تجزئة المعاملة
- تعريف صفحة دفع عنوان 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 في شبكة Tron. سيكون للفاتورة عنوان في وقت الخلق.
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 في شبكة Tron. سيكون للفاتورة عنوان في وقت الخلق.
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 دولارًا أمريكيًا والسماح للعملاء بالدفع في Bitcoin فقط. سيكون للفاتورة عنوان في وقت الخلق.
1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}طلب البيانات لإنشاء فاتورة لـ 0.5 BTC والسماح للعملاء بالدفع في Bitcoin فقط. سيكون للفاتورة عنوان في وقت الخلق.
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}