إنشاء فاتورة

post
https://api.cryptomus.com/v1/payment
ينسخ

طلب

معلمات الاستعلام

اسمنوع المعلمةالقيمة الافتراضيةتعريف
amount*stringالمبلغ المستحق للدفع.إذا كانت هناك بنسات في المبلغ ، فأرسلها مع فاصل
".مثال: 10.28
currency*stringرمز العملة
order_id*stringmin: 1max: 128alpha_dashطلب معرف في نظامكيجب أن تكون المعلمة عبارة عن سلسلة تتكون من الأحرف الأبجدية والأرقام والرسومات الساحرة والشرطات. لا ينبغي أن تحتوي على أي مسافات أو أحرف خاصة.يجب أن يكون order_id فريدًا داخل فواتير التاجر/محافظ ثابتة/مدفوعات تكرارعندما نجد فاتورة موجودة مع order_id ، نعيد تفاصيلها ، ولن يتم إنشاء فاتورة جديدة.
networkstringnullرمز شبكة blockchain
url_returnstringmin: 6max: 255urlnullقبل الدفع ، يمكن للمستخدم النقر فوق الزر الموجود في نموذج الدفع والعودة إلى صفحة المتجر في عنوان URL هذا.
url_successstringmin: 6max: 255urlnullبعد الدفع الناجح ، يمكن للمستخدم النقر على الزر الموجود في نموذج الدفع والعودة إلى عنوان URL هذا.
url_callbackstringmin: 6max: 255urlnullعنوان URL الذي سيتم إرسال Webhooks مع حالة الدفع إليه
is_payment_multiplebooleantrueما إذا كان المستخدم مسموحًا بدفع المبلغ المتبقي. يكون هذا مفيدًا عندما لا يدفع المستخدم كامل المبلغ من الفاتورة لمعاملة واحدة ، وتريد أن تسمح له بدفع المبلغ بالكامل. إذا قمت بتعطيل هذه الميزة ، فستنتهي الفاتورة بعد تلقي الدفعة الأولى وستتلقى أموالًا لتحقيق رصيدك.
lifetimeintegermin: 300max: 432003600عمر الفاتورة الصادرة (بالثواني)
to_currencystringيتم استخدام المعلمة لتحديد العملة المستهدفة لتحويل مبلغ الفاتورة. عند إنشاء فاتورة ، يمكنك تقديم مبلغ وعملة ، وسيقوم واجهة برمجة التطبيقات بتحويل هذا المبلغ إلى القيمة المكافئة في to_currency.على سبيل المثال ، لإنشاء فاتورة مقابل 20 دولارًا في Bitcoin:
amount : 20
currency : USD
to_currency : BTC
سيقوم API بتحويل مبلغ 20 دولارًا أمريكيًا إلى ما يعادلها في BTC بناءً على سعر الصرف الحالي وسيدفع المستخدم في BTCيجب أن يكون to_currency دائمًا رمز العملة المشفرة ، وليس رمز العملة Fiat.
subtractintegermin: 0max: 1000النسبة المئوية لجنة الدفع التي يتم فرضها على العميلإذا كان لديك معدل 1 ٪ ، فعندئذٍ ، إذا قمت بإنشاء فاتورة مقابل 100 دولار أمريكي مع طرح = 100 (يدفع العميل عمولة بنسبة 100 ٪) ، فسيتعين على العميل دفع 101 USDT.
accuracy_payment_percentnumericmin: 0max: 50عدم دقة مقبولة في الدفع.على سبيل المثال ، إذا قمت بتمرير القيمة 5 ، فسيتم تمييز الفاتورة على أنها مدفوعة حتى لو دفع العميل 95 ٪ فقط من المبلغ.سيتم إضافة مبلغ الدفع الفعلي إلى الرصيد
additional_datastringmax: 255nullمعلومات إضافية لك (لا تظهر للعميل)
currenciesarrayيتم استخدام مجموعة من العملات المتاحة من إعدادات التاجر (إذا لم يتم تعيين المعلمة ، يتم استخدام جميع العملات المشفرة المدعومة افتراضيًا).يتم تعيين العملات المتاحة في قسم إعدادات التاجر.قائمة العملات المسموح بها للدفع. هذا مفيد إذا كنت ترغب في الحد من قائمة العملات المعدنية التي يمكن لعملائك استخدامها لدفع الفواتير. بناء
except_currenciesarraynullقائمة العملات المستبعدة للدفع بناء
course_sourcestringmin: 4max: 20القيم المتاحةBinanceBinanceP2PExmoKucoinإذا لم يتم تمريرها ، يتم استخدام أسعار صرف Cryptomus.الخدمة التي يتم من خلالها أخذ أسعار الصرف للتحويل في الفاتورة.
from_referral_codestringnullالتاجر الذي يقوم بتوصيل الطلب يتصل إلى إحالة حسب الرمز.على سبيل المثال ، أنت تطبيق يقوم بإنشاء فواتير عبر واجهة برمجة تطبيقات Cryptomus وعملائك متاجر أخرى. كود الإحالة.وبالتالي ، يصبح عملاؤك إحالات على حساب 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

تعريف

طلب معرف في نظامكيجب أن تكون المعلمة عبارة عن سلسلة تتكون من الأحرف الأبجدية والأرقام والرسومات الساحرة والشرطات. لا ينبغي أن تحتوي على أي مسافات أو أحرف خاصة.يجب أن يكون 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

* - المعلمة الإلزامية

سيكون للفاتورة عملة مشفرة وعنوان معين في وقت الإنشاء فقط إذا كانت المعلمة العملة أو to_currency عملة مشفرة وتم تمرير معلمة الشبكة (أو أن العملة المشفرة تحتوي فقط على شبكة واحدة ، على سبيل المثال BTC).

طلب مثال

أدناه مثال عينة مع الحد الأدنى لعدد المعلمات. في هذه الحالة ، سيتم إنشاء فاتورة مع عملة 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}
ينسخ