Transfer Event

The transfer event type is used for money transfers between accounts, wallets, or users.

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": "transfer",
  "timestamp": "2025-03-15T09:15:00Z",
  "trx_id": "trx_d4e5f6a7b8c9",
  "attempt_id": "att_001",
  "order_id": "order_88901",
  "external_id": "txn_transfer_88901",
  "device_id": "fp_def456789abc0123",
  "user_id": "usr_345678",
  "beneficiary_id": "usr_889900",
  "user_email": "[email protected]",
  "full_name": "Mohammed Al-Saud",
  "phone_number": "+966534567890",
  "ip_address": "178.150.22.91",
  "ip_country": "SA",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0",
  "payment_method": "Mada",
  "card_bin": "98765432",
  "card_last4": "1234",
  "card_expiry_month": 3,
  "card_expiry_year": 2026,
  "card_fingerprint": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
  "card_brand": "mada",
  "card_issuing_bank": "Riyad Bank",
  "card_issuer_country": "SA",
  "transaction_amount": 500.00,
  "currency": "USD",
  "account_created_at": "2022-03-10T00:00:00Z",
  "channel": "app",
  "platform": "android"
}

Response Example

{
  "request_id": "d4e5f6a7-b8c9-0123-def0-345678901bcd",
  "decision": "challenge",
  "risk_score": 45,
  "risk_level": "medium"
}

Feedback Examples

Successful Transfer

{
  "request_id": "d4e5f6a7-b8c9-0123-def0-345678901bcd",
  "outcome": "success",
  "external_id": "txn_transfer_88901"
}

Disputed Transfer

{
  "request_id": "d4e5f6a7-b8c9-0123-def0-345678901bcd",
  "outcome": "dispute",
  "outcome_details": {
    "dispute_reason": "unauthorized_transfer",
    "dispute_date": "2025-03-20"
  },
  "external_id": "txn_transfer_88901"
}

Key Fields for Transfer Events

Field	Importance	Notes
transaction_amount	Required	Transfer 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
user_id	Required	Identifies the sender
beneficiary_id	Recommended	Identifies the recipient. Stored as a typed field, so velocity rules can count transfers to the same beneficiary
payment_method	Recommended	Source of funds