وظائف واجهة برمجة تطبيقات استرداد الأموال

إنشاء استرداد

ينشئ عملية استرداد رسوم تم إنشاؤها بالفعل ولكن لم يتم استردادها بعد. يمكن تحديد المبلغ الذي سيتم استرداده، أو يمكن استرداد مبلغ الرسوم بالكامل من خلال عدم تحديد مبلغ. سيتم إنشاء عملية استرداد الأموال بنفس عملة الرسوم وبنفس طريقة الدفع التي تم بها استرداد الرسوم.

** لا يمكن استرداد رسوم أكثر من مرة واحدة.** إذا حاولت استرداد رسوم تم استردادها بالفعل، فسيتم إرجاع خطأ. سيحدث هذا أيضًا إذا حاولت استرداد أكثر من مبلغ الشحن الأصلي.

نقطة النهاية: https://api.stripe.com/v1/refunds

العملية: POST

أمثلة

cURL Example:

curl -X POST https://api.stripe.com/v1/refunds \
  -u <YOUR_SECRET_KEY>: \
  -d "charge=ch_1NirD82eZvKYlo2CIvbtLWuY"

الردود

ستُرجع الردود رموزًا قياسية.

200: موافق

{
  "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
  "object": "refund",
  "amount": 212,
  "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx",
  "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY",
  "created": 1692942318,
  "currency": "usd",
  "destination_details": {
    "card": {
      "reference": "123456789012",
      "reference_status": "available",
      "reference_type": "acquirer_reference_number",
      "type": "refund"
    },
    "type": "card"
  },
  "metadata": {},
  "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null
}

400: طلب سيء

{
  "error": {
    "code": "parameter_invalid_integer",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-integer",
    "message": "عدد صحيح غير صالح: <عدد صحيح>",
    "param": "amount",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_UQf6XBwBl9yk66?t=1734829676",
    "type": "invalid_request_error"
  }
}

401: غير مصرح به

{
  "error": {
    "type": "invalid_request_error",
    "message": "مفتاح API غير صالح المقدم: sk_test_********************1234"
  }
}

المعلمات

معلمات الجسم

المعلمة	النوع	الوصف
amount	integer	المبلغ المطلوب رده، بالسنت. إذا لم يتم تحديده، سيتم رد مبلغ الرسوم بالكامل.
charge	string	(مطلوب) معرف الرسوم المطلوب ردها.
currency	string	رمز عملة ISO المكون من ثلاثة أحرف، بأحرف صغيرة. يجب أن تكون عملة مدعومة. إذا لم يتم تحديدها، سيتم استخدام عملة الرسوم.
expand[]	array of strings	يحدد الحقول التي يجب توسيعها في الاستجابة.
customer	string	معرف العميل الذي تنتمي إليه الرسوم.
reason	string	سبب الاسترداد. إذا تم تعيينها، فإن القيم المحتملة هي duplicate، fraudulent، أو requested_by_customer. إذا تم تعيينها على أنها fraudulent، فستتم إضافة البطاقة والبريد الإلكتروني المرتبطين بالرسوم إلى قوائم الحظر الخاصة بك، وسيساعد ذلك في تحسين اكتشاف الاحتيال في Stripe.
payment_intent	string	معرف PaymentIntent لاستردادها.
refund_application_fee	boolean	يشير إلى ما إذا كان ينبغي استرداد رسوم التطبيق. إذا تم استرداد المبلغ بالكامل، فسيتم استرداد رسوم التطبيق أيضًا. خلاف ذلك، سيتم رد رسوم التطبيق بالتناسب مع المبلغ المسترد. يمكن أن يكون رسم التطبيق هو فقط التطبيق الذي أنشأ الرسوم.
origin	string	أصل المبلغ المسترد.
reverse_transfer	boolean	يشير إلى ما إذا كان ينبغي عكس التحويل. يتم عكس التحويل بشكل متناسب مع المبلغ المسترد (استرداد كامل أو جزئي).
instructions_email	string	يستخدم عنوان البريد الإلكتروني للعميل لتعليمات استرداد الأموال عندما يتم استخدام طريقة الدفع بدون دعم استرداد الأموال.

تحديث استرداد الأموال

تحديث المبلغ المسترد المحدد عن طريق تعيين قيم المعلمات التي تم تمريرها. سيتم ترك أي معلمات لم يتم توفيرها دون تغيير. هذا مفيد لتخزين معلومات إضافية حول المبلغ المسترد.

نقطة النهاية: https://api.stripe.com/v1/refunds/{id}

العملية: POST

أمثلة

cURL Example:

curl -X POST `https://api.stripe.com/v1/refunds/{id}` \
  -u <YOUR_SECRET_KEY>: \
  -d "metadata[order_id]=6735"

الردود

ستُرجع الردود رموزًا قياسية.

200: موافق

{
  "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
  "object": "refund",
  "amount": 1000,
  "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx",
  "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY",
  "created": 1692942318,
  "currency": "usd",
  "destination_details": {
    "card": {
      "reference": "123456789012",
      "reference_status": "available",
      "reference_type": "acquirer_reference_number",
      "type": "refund"
    },
    "type": "card"
  },
  "metadata": {
    "order_id": "6735"
  },
  "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null
}

400: طلب سيء

{
  "error": {
    "code": "parameter_invalid_integer",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-integer",
    "message": "عدد صحيح غير صالح: <عدد صحيح>",
    "param": "amount",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_UQf6XBwBl9yk66?t=1734829676",
    "type": "invalid_request_error"
  }
}

401: غير مصرح به

{
  "error": {
    "type": "invalid_request_error",
    "message": "مفتاح API غير صالح المقدم: sk_test_********************1234"
  }
}

المعلمات

معلمات الجسم

المعلمة	النوع	الوصف
metadata	object	مجموعة من أزواج المفاتيح-القيم التي يمكنك إرفاقها بكائن. يمكن أن يكون هذا مفيدًا لتخزين معلومات إضافية حول الكائن بتنسيق منظم.
expand[]	array of strings	يحدد الحقول التي يجب توسيعها في الاستجابة.

متغيرات المسار

الاسم	النوع	مطلوب	الوصف
id	string	مطلوب	معرف المسترد المطلوب تحديثه.

استرداد مبلغ مسترد

استرداد تفاصيل عملية استرداد أموال محددة.

نقطة النهاية: https://api.stripe.com/v1/refunds/{id}

العملية: GET

أمثلة

cURL Example:

curl -X GET https://api.stripe.com/v1/refunds/re_1Nispe2eZvKYlo2Cd31jOCgZ \
  -u <YOUR_SECRET_KEY>:

الردود

ستعيد الردود رموزًا قياسية.

200: موافق

{
  "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
  "object": "refund",
  "amount": 212,
  "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx",
  "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY",
  "created": 1692942318,
  "currency": "usd",
  "destination_details": {
    "card": {
      "reference": "123456789012",
      "reference_status": "available",
      "reference_type": "acquirer_reference_number",
      "type": "refund"
    },
    "type": "card"
  },
  "metadata": {},
  "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null
}

400: طلب سيء

{
  "error": {
    "code": "parameter_invalid_integer",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-integer",
    "message": "عدد صحيح غير صالح: <عدد صحيح>",
    "param": "amount",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_UQf6XBwBl9yk66?t=1734829676",
    "type": "invalid_request_error"
  }
}

401: غير مصرح به

{
  "error": {
    "type": "invalid_request_error",
    "message": "مفتاح API غير صالح المقدم: sk_test_********************1234"
  }
}

المعلمات

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

المعلمة	النوع	الوصف
expand[]	array of strings	يحدد الحقول التي يجب توسيعها في الاستجابة.

متغيرات المسار

الاسم	النوع	مطلوب	الوصف
id	string	مطلوب	معرف المسترد المطلوب استرداده.

سرد جميع المبالغ المستردة

إرجاع قائمة بالمبالغ المستردة الحالية. يتم إرجاع المبالغ المستردة بترتيب مرتب، مع ظهور أحدث المبالغ المستردة أولاً. يتم إرجاع أحدث 10 مبالغ مستردة بشكل افتراضي.

نقطة النهاية: https://api.stripe.com/v1/refunds

العملية: GET

أمثلة

cURL Example:

curl -X GET https://api.stripe.com/v1/refunds \
  -u <YOUR_SECRET_KEY>:

الردود

ستعيد الردود رموزًا قياسية.

200: موافق

{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
      "object": "refund",
      "amount": 212,
      "balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx",
      "charge": "ch_1NirD82eZvKYlo2CIvbtLWuY",
      "created": 1692942318,
      "currency": "usd",
      "destination_details": {
        "card": {
          "reference": "123456789012",
          "reference_status": "available",
          "reference_type": "acquirer_reference_number",
          "type": "refund"
        },
        "type": "card"
      },
      "metadata": {},
      "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
      "reason": null,
      "receipt_number": null,
      "source_transfer_reversal": null,
      "status": "succeeded",
      "transfer_reversal": null
    }
  ]
}

400: طلب سيء

{
    "error": {
        "code": "resource_missing",
        "doc_url": "https://stripe.com/docs/error-codes/resource-missing",
        "message": "لا يوجد مثل هذه الشحنة: 'ch_1NirD82eZvKYlo2CIvbtLWuY'",
        "param": "charge",
        "request_log_url": "https://dashboard.stripe.com/test/logs/req_HIH2jWkJGecwCk?t=1754504399",
        "type": "invalid_request_error"
    }
}

401: غير مصرح به

{
  "error": {
    "type": "invalid_request_error",
    "message": "تم توفير مفتاح API غير صالح: sk_test_********************1234"
  }
}

المعلمات

المعلمة	النوع	الوصف
charge	string	معرف التكلفة لاسترداد المبالغ المستردة. إذا لم يتم تحديده، سيتم إرجاع جميع المبالغ المستردة.
created	dictionary	إرجاع المبالغ المستردة التي تم إنشاؤها فقط خلال فترات التاريخ المحددة. يمكن أن يكون هذا قاموسًا بالمفاتيح التالية: gt، gte، lt، lte.
ending_before	string	مؤشر للاستخدام في ترقيم الصفحات. استخدم معرف الكائن ending_before لتحديد مكانك في القائمة. إذا قمت بإجراء طلب قائمة وتلقيت 100 نتيجة، تبدأ بـ obj_bar، يمكن أن يتضمن استدعاؤك اللاحق ending_before=obj_bar لجلب الصفحة السابقة من القائمة.
limit	integer	حد لعدد الكائنات التي سيتم إرجاعها. يمكن أن يتراوح الحد بين 1 و100. الافتراضي هو 10.
payment_intent	string	معرف PaymentIntent لاسترداد المبالغ المستردة. إذا لم يتم تحديده، سيتم إرجاع جميع المبالغ المستردة.
starting_after	string	مؤشر للاستخدام في ترقيم الصفحات. استخدم معرف الكائن starting_after لتحديد مكانك في القائمة. إذا قمت بإجراء طلب قائمة وتلقيت 100 نتيجة، تنتهي بـ obj_foo، يمكن أن يتضمن استدعاؤك اللاحق starting_after=obj_foo لجلب الصفحة التالية من القائمة.
expand[]	array of strings	يحدد الحقول التي يجب توسيعها في الاستجابة.