Payment Event

The payment event type is used for payment transactions. This is the most common monetary event type.

Category: Monetary Relevant feedback outcomes: success, fail, fraud, dispute, chargeback, rejected, refund

Request Example

POST /api/v1/generic/validate HTTP/1.1
Host: api.sa.mubeen.ai
X-API-Key: <your_key>
Content-Type: application/json

{
  "event_type": "payment",
  "timestamp": "2025-03-15T10:30:00Z",
  "trx_id": "trx_019a54474a4e",
  "attempt_id": "att_001",
  "order_id": "order_98765",
  "external_id": "order_98765",
  "device_id": "fp_1234567890abcdef",
  "user_id": "usr_123456",
  "user_email": "[email protected]",
  "full_name": "Ahmed Al-Rashid",
  "phone_number": "+966512345678",
  "ip_address": "185.23.45.67",
  "ip_country": "SA",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
  "payment_method": "Visa",
  "card_bin": "42424242",
  "card_last4": "4242",
  "card_expiry_month": 6,
  "card_expiry_year": 2028,
  "card_fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "card_brand": "visa",
  "card_issuing_bank": "Al Rajhi Banking & Inv. Corp.",
  "card_issuer_country": "SA",
  "transaction_amount": 249.99,
  "currency": "USD",
  "account_created_at": "2023-06-15T00:00:00Z",
  "product_ids_list": ["PUBGs", "Fortnite"],
  "channel": "app",
  "platform": "ios"
}

Response Example

{
  "request_id": "019a5447-4a4e-7b3f-9562-54ce36825c2e",
  "decision": "allow",
  "risk_score": 12,
  "risk_level": "low"
}

Feedback Examples

Successful Payment

{
  "request_id": "019a5447-4a4e-7b3f-9562-54ce36825c2e",
  "outcome": "success",
  "external_id": "order_98765"
}

Failed Payment (Card Declined)

{
  "request_id": "019a5447-4a4e-7b3f-9562-54ce36825c2e",
  "outcome": "fail",
  "outcome_details": {
    "error_code": "card_declined",
    "processor_response": "do_not_honor"
  },
  "external_id": "order_98765"
}

Fraudulent Payment

{
  "request_id": "019a5447-4a4e-7b3f-9562-54ce36825c2e",
  "outcome": "fraud",
  "outcome_details": {
    "fraud_type": "stolen_card",
    "detection_method": "manual_review",
    "confidence": "high"
  },
  "external_id": "order_98765"
}

Chargeback

{
  "request_id": "019a5447-4a4e-7b3f-9562-54ce36825c2e",
  "outcome": "chargeback",
  "outcome_details": {
    "chargeback_reason": "unauthorized_transaction",
    "chargeback_date": "2025-04-01"
  },
  "external_id": "order_98765"
}

Key Fields for Payment Events

Field	Importance	Notes
transaction_amount	Required	Transaction value
currency	Recommended	Currency code (ISO 4217, e.g., USD). Not enforced by the API. If omitted, the amount is treated as USD, so a non-USD amount is converted wrongly and USD-based rules and reporting will be off
payment_method	Recommended	Visa, Mastercard, Mada, ApplePay, GooglePay
card_bin / card_last4	Recommended	Card identification for fraud detection
card_fingerprint	Recommended	Same-card detection across transactions
product_ids_list	Optional	Items being purchased