Session Details API

Verify an embedded (v3 session) payment when the callback lacks a PaymentId

Overview

Modern embedded checkout (PaymentMode: COMPLETE_PAYMENT) authenticates and completes the payment inside the widget using a SessionId — some completions don't surface a PaymentId in the callback the way the classic redirect flow does. The Session Details endpoint lets you look the session back up by its SessionId and read the invoice/transaction status directly.

👍 When to use this API
  • Your embedded checkout completes, but the page you receive after it doesn't include a usable PaymentId.
  • You want to double-check a session before relying on client-side success events.
📘 Request Header: Add "Authorization": "Bearer {Token}" to the request header. Your client token can be found in your portal account settings.

API Endpoint

Endpoint Method Description
/api/payment/session-details GET Get a v3 embedded session's status by SessionId

Request

Query Parameter

Parameter Type Required Description
SessionId string Yes The SessionId you obtained from InitiateSession or the v3 create-session response

Example request URL

GET https://panel.royat.sa/api/payment/session-details?SessionId=dfc6a3c3-df09-44cb-9c6a-0a6375752da6

Response

Standard API response format. Data mirrors MyFatoorah's session object — the invoice's status, value and id live under Data.TransactionResult.Invoice, and the reference you sent at create-session is echoed back under Data.Customer.Reference.

{
  "IsSuccess": true,
  "Message": null,
  "ValidationErrors": null,
  "Data": {
    "SessionId": "dfc6a3c3-df09-44cb-9c6a-0a6375752da6",
    "Customer": {
      "Reference": "ORD-2026-00073"
    },
    "Order": {
      "Amount": 35
    },
    "TransactionResult": {
      "Invoice": {
        "Id": 88839341,
        "Status": "Paid",
        "Value": 35
      }
    }
  }
}
❗ Verify fail-closed before fulfilling: Only treat the payment as confirmed when all three hold: IsSuccess is true, Data.TransactionResult.Invoice.Status is exactly "Paid", and — when your integration cares about binding to a specific order — Data.Customer.Reference and Data.TransactionResult.Invoice.Value match the order you expect. A missing or mismatched reference/amount should be treated as unverified, not as paid.

Support

For more information and support, please contact the Royat Pay team.