إنشاء فاتورة
طلب
معلمات الاستعلام
اسم | نوع المعلمة | القيمة الافتراضية | تعريف |
---|---|---|---|
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تعريف
رمز شبكة blockchainنوع المعلمة
stringmin: 6max: 255urlتعريف
قبل الدفع ، يمكن للمستخدم النقر فوق الزر الموجود في نموذج الدفع والعودة إلى صفحة المتجر في عنوان URL هذا.نوع المعلمة
stringmin: 6max: 255urlتعريف
بعد الدفع الناجح ، يمكن للمستخدم النقر على الزر الموجود في نموذج الدفع والعودة إلى عنوان URL هذا.نوع المعلمة
stringmin: 6max: 255urlتعريف
عنوان URL الذي سيتم إرسال Webhooks مع حالة الدفع إليهنوع المعلمة
booleanتعريف
ما إذا كان المستخدم مسموحًا بدفع المبلغ المتبقي. يكون هذا مفيدًا عندما لا يدفع المستخدم كامل المبلغ من الفاتورة لمعاملة واحدة ، وتريد أن تسمح له بدفع المبلغ بالكامل. إذا قمت بتعطيل هذه الميزة ، فستنتهي الفاتورة بعد تلقي الدفعة الأولى وستتلقى أموالًا لتحقيق رصيدك.نوع المعلمة
integermin: 300max: 43200تعريف
عمر الفاتورة الصادرة (بالثواني)نوع المعلمة
stringتعريف
يتم استخدام المعلمة لتحديد العملة المستهدفة لتحويل مبلغ الفاتورة. عند إنشاء فاتورة ، يمكنك تقديم مبلغ وعملة ، وسيقوم واجهة برمجة التطبيقات بتحويل هذا المبلغ إلى القيمة المكافئة في to_currency.على سبيل المثال ، لإنشاء فاتورة مقابل 20 دولارًا في Bitcoin:
amount : 20
currency : USD
to_currency : BTCسيقوم API بتحويل مبلغ 20 دولارًا أمريكيًا إلى ما يعادلها في BTC بناءً على سعر الصرف الحالي وسيدفع المستخدم في BTCيجب أن يكون to_currency دائمًا رمز العملة المشفرة ، وليس رمز العملة Fiat.نوع المعلمة
integermin: 0max: 100تعريف
النسبة المئوية لجنة الدفع التي يتم فرضها على العميلإذا كان لديك معدل 1 ٪ ، فعندئذٍ ، إذا قمت بإنشاء فاتورة مقابل 100 دولار أمريكي مع طرح = 100 (يدفع العميل عمولة بنسبة 100 ٪) ، فسيتعين على العميل دفع 101 USDT.نوع المعلمة
numericmin: 0max: 5تعريف
عدم دقة مقبولة في الدفع.على سبيل المثال ، إذا قمت بتمرير القيمة 5 ، فسيتم تمييز الفاتورة على أنها مدفوعة حتى لو دفع العميل 95 ٪ فقط من المبلغ.سيتم إضافة مبلغ الدفع الفعلي إلى الرصيدنوع المعلمة
stringmax: 255تعريف
معلومات إضافية لك (لا تظهر للعميل)نوع المعلمة
arrayتعريف
قائمة العملات المسموح بها للدفع. هذا مفيد إذا كنت ترغب في الحد من قائمة العملات المعدنية التي يمكن لعملائك استخدامها لدفع الفواتير. بناءنوع المعلمة
arrayتعريف
قائمة العملات المستبعدة للدفع بناءنوع المعلمة
stringmin: 4max: 20
القيم المتاحة- Binance- BinanceP2P- Exmo- Kucoinتعريف
الخدمة التي يتم من خلالها أخذ أسعار الصرف للتحويل في الفاتورة.نوع المعلمة
stringتعريف
التاجر الذي يقوم بتوصيل الطلب يتصل إلى إحالة حسب الرمز.على سبيل المثال ، أنت تطبيق يقوم بإنشاء فواتير عبر واجهة برمجة تطبيقات Cryptomus وعملائك متاجر أخرى. كود الإحالة.وبالتالي ، يصبح عملاؤك إحالات على حساب Cryptomus الخاص بك وسوف تتلقى دخلًا من معدل دورانهم.نوع المعلمة
integermin: -99max: 100تعريف
الأرقام الإيجابية:
يتيح لك تعيين خصم.
لتعيين خصم 5 ٪ للدفع ، يجب أن تمرير قيمة: 5الأرقام السلبية:
يتيح لك تعيين عمولة إضافية مخصصة.لتحديد عمولة إضافية بنسبة 10 ٪ للدفع ، يجب أن تمرير قيمة: -10يتم أخذ نسبة الخصم عند إنشاء فاتورة في الاعتبار فقط إذا كانت الفاتورة تحتوي على عملة مشفرة محددة.نوع المعلمة
booleanتعريف
باستخدام هذه المعلمة ، يمكنك تحديث مدى الحياة والحصول على عنوان جديد للفاتورة إذا انتهت صلاحية العمر.للقيام بذلك ، تحتاج إلى تمرير جميع المعلمات المطلوبة ، وسيتم تحديث الفاتورة مع 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}
ينسخ