التوثيق / مرجع الواجهة

الإبلاغ عن نتيجة الدفع

يُبلغ عمّا حدث فعلاً لعملية دفع قيّمتها، لتتعلّم منه نماذج الدفع وأوزان القواعد وذاكرة السمعة في حسابك.

نظرة عامة#

feedback/payment طريقة POST بمحتوى JSON. أرسل transaction_id الذي استخدمته مع كشف احتيال الدفع وoutcome: approved أو declined أو chargeback أو refunded أو fraud_confirmed أو legit_confirmed. أضف reason (رمز الرفض أو سبب الاعتراض) وoccurred_at إن توفّرا. راجع الملاحظات والتعلّم لمعرفة كيف تُستخدم النتائج.

متى تستدعيها#

عند تسليم الطلب (approved) أو رفضه أو استرداده أو الاعتراض عليه.
عندما يؤكد فريق المخاطر احتيالاً في طلب، أو يجيز طلباً كان معلّقاً (fraud_confirmed / legit_confirmed).

كيف تعمل#

تُكتب النتيجة على كل تقييم لذلك الـtransaction_id في حسابك وتكون data.status بقيمة applied.
إن لم يقيّم Gurdx تلك المعاملة بعد، تُحفظ النتيجة وتكون data.status بقيمة pending، ثم تُطبَّق تلقائياً عند تقييم المعاملة. وللطلبات التي لم يقيّمها Gurdx إطلاقاً (تاريخ ما قبل التكامل) أضف customer_id أو customer_email أو customer_phone أو customer_ip أو customer_device_id لتغذّي النتيجة السمعة رغم ذلك.
إرسال النتيجة نفسها مرة أخرى يُرجع label: "unchanged"، فإعادة المحاولة آمنة. ولا يُستبدل chargeback أو fraud_confirmed بـapproved أو declined أو refunded لاحق؛ وحده legit_confirmed يتجاوزه.

ملاحظات#

مجانية: لا تُحتسب من حصتك ومتاحة في كل الباقات.
وضع الاختبار يتحقق ويرد بنتيجة نموذجية دون حفظ شيء.
الحقول الناقصة أو غير الصالحة تُرجع الخطأ 131 (invalid_feedback) مع HTTP 200.

الطلب#

POST https://gurdx.cretip.com/api/feedback/payment

صادِق بمعامل key أو بترويسة Authorization: Bearer.
مجانية — لا تُحتسب من حصتك.
متاحة في: تجربة مجانية القياسية المميّزة الدفع حسب الاستخدام

المعاملات#

الاسم	النوع	الوصف
`transaction_id` مطلوب جسم	`string`	The `transaction_id` you sent to Payment Fraud Detection (your order or payment id).
`outcome` مطلوب جسم	`string`	What really happened: `approved`, `declined`, `chargeback`, `refunded`, `fraud_confirmed` or `legit_confirmed`.
`reason` اختياري جسم	`string`	Free text, e.g. the gateway decline code or the chargeback reason. A `declined` outcome whose reason mentions fraud (for example `fraud`, `stolen_card`, `suspected_fraud`) counts as fraud for learning.
`occurred_at` اختياري جسم	`string\|integer`	When the outcome happened: ISO-8601 date or UNIX timestamp. Defaults to now.
`customer_id` اختياري جسم	`string`	Optional. The customer of this payment, for transactions that were never scored by Gurdx (historical backfill).
`customer_email` اختياري جسم	`string`	Optional, as above.
`customer_phone` اختياري جسم	`string`	Optional, as above.
`customer_ip` اختياري جسم	`string`	Optional, as above.
`customer_device_id` اختياري جسم	`string`	Optional, as above.

تقبل كل خدمة أيضاً format, lang, mode, userID. راجع الخيارات.

أمثلة برمجية#

curl -X POST "https://gurdx.cretip.com/api/feedback/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "ORD-10492",
    "outcome": "chargeback",
    "reason": "fraudulent",
    "occurred_at": "2026-10-20T14:05:00Z"
}'

<?php

$payload = [
    'transaction_id' => 'ORD-10492',
    'outcome' => 'chargeback',
    'reason' => 'fraudulent',
    'occurred_at' => '2026-10-20T14:05:00Z',
];

$ch = curl_init('https://gurdx.cretip.com/api/feedback/payment');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);

if ($result['status'] !== 'success') {
    error_log($result['code'].': '.$result['description']);
}

const res = await fetch('https://gurdx.cretip.com/api/feedback/payment', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transaction_id": "ORD-10492",
    "outcome": "chargeback",
    "reason": "fraudulent",
    "occurred_at": "2026-10-20T14:05:00Z"
}),
});
const result = await res.json();

if (result.status !== 'success') {
  console.error(result.code, result.description);
}

import requests

res = requests.post(
    "https://gurdx.cretip.com/api/feedback/payment",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "transaction_id": "ORD-10492",
        "outcome": "chargeback",
        "reason": "fraudulent",
        "occurred_at": "2026-10-20T14:05:00Z",
    },
)
result = res.json()

if result["status"] != "success":
    print(result["code"], result["description"])

الاستجابة#

نجاح#

{
    "data": {
        "transaction_id": "ORD-10492",
        "outcome": "chargeback",
        "status": "applied",
        "matched": 1,
        "label": "created"
    },
    "status": "success",
    "executionTime": 4
}

خطأ#

تُسلَّم الأخطاء بحالة HTTP 200 — افحص دائماً حقل status.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

حقول الاستجابة#

الاسم	النوع	الوصف
`data.transaction_id`	`string`	The transaction id, as received.
`data.outcome`	`string`	The outcome, as recorded.
`data.status`	`string`	`applied` when the transaction was found and updated, `pending` when no scored transaction has this id yet: the outcome is kept and applied automatically when it is scored.
`data.matched`	`integer`	How many scorings of this transaction were updated.
`data.label`	`string`	`created`, `updated` or `unchanged` (sending the same feedback again is a no-op).

وجدت خطأ؟ أخبرنا عبر صفحة التواصل. تواصل معنا