Payment Status API

Check payment status by PaymentId — verify and confirm transactions

Overview

The Payment Status endpoint lets you check the current status of a payment using the PaymentId returned after a customer completes (or abandons) a payment. Use it to verify whether a payment succeeded, is still pending, or was canceled — so you can update your orders, show the right message to the customer, or trigger fulfillment.

👍 When to use this API
  • After the customer is redirected to your CallBackUrl or ErrorUrl — use the PaymentId from the callback to confirm the final status.
  • When using embedded payment (e.g. in iframe) — after the payment flow completes, call this endpoint with the returned PaymentId to get the definitive status.
  • For manual or automated reconciliation — poll or check status for specific payments when needed.
📘 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/status GET Get payment status by PaymentId (query parameter)

Request

Send a GET request with the payment identifier as a query parameter.

Query Parameter

Parameter Type Required Description
PaymentId string Yes The payment ID you received from the Royat Pay checkout flow (e.g. from callback URL or ExecutePayment flow)

Example request URL

GET https://panel.royat.sa/api/payment/status?PaymentId=100000001

Replace 100000001 with the actual PaymentId from your callback or payment response.

Response

The response uses the standard API format: IsSuccess, Message, ValidationErrors, and Data. On success, Data contains the invoice and transaction details.

Top-level response fields

Field Type Description
IsSuccess boolean Whether the request was successful
Message string Human-readable message
ValidationErrors object|null Field-level errors (e.g. missing PaymentId)
Data object Invoice and transaction details (see below)

Data object (invoice & status)

Field Type Description
InvoiceId number Invoice ID used for this payment
InvoiceStatus string Paid, Pending, or Canceled — use this to decide if the payment succeeded
InvoiceReference string Invoice reference from Royat Pay
CustomerReference string Your reference (e.g. order ID) sent when creating the invoice
InvoiceValue number Invoice total value
CustomerName string Customer name on the invoice
CustomerEmail string Customer email
CustomerMobile string Customer mobile number
CreatedDate string Invoice creation date
ExpiryDate string Invoice expiry date
InvoiceTransactions array List of payment attempts with status, PaymentId, payment method, etc.
❗ Always use InvoiceStatus: To confirm that the customer has paid, check Data.InvoiceStatus === "Paid". Do not rely only on the customer being redirected to the success URL — always verify with this API when handling orders or delivering services.

Sample response (success — paid)

{
  "IsSuccess": true,
  "Message": null,
  "ValidationErrors": null,
  "Data": {
    "InvoiceId": 927972,
    "InvoiceStatus": "Paid",
    "InvoiceReference": "0106292797237",
    "CustomerReference": "ORDER-12345",
    "InvoiceValue": 10.000,
    "CustomerName": "John Doe",
    "CustomerEmail": "[email protected]",
    "CustomerMobile": "1234567890",
    "CreatedDate": "2024-01-15T10:30:00",
    "ExpiryDate": "2024-01-16T10:30:00",
    "InvoiceTransactions": [
      {
        "TransactionDate": "2024-01-15T10:35:00",
        "PaymentMethod": "Visa/Master",
        "ReferenceId": "REF123",
        "TrackId": "TRACK456",
        "TransactionId": "TXN789",
        "PaymentId": "100000001",
        "TransactionStatus": "Succeded",
        "PaymentMethodId": 20
      }
    ]
  }
}

Sample response (validation error)

When PaymentId is missing:

{
  "IsSuccess": false,
  "Message": "Validation failed",
  "ValidationErrors": {
    "PaymentId": ["PaymentId is required"]
  },
  "Data": null
}

Typical integration flow

  1. Customer completes payment and is redirected to your CallBackUrl (or stays in your app with embedded flow).
  2. Your callback/page receives a PaymentId (e.g. from query string: ?PaymentId=100000001).
  3. Your server calls GET https://panel.royat.sa/api/payment/status?PaymentId=100000001 with the Bearer token.
  4. If Data.InvoiceStatus === "Paid", mark the order as paid and show success; otherwise show appropriate message (e.g. pending or failed).
👍 Best practice: Use this endpoint after every payment callback or embedded payment completion so your system always reflects the true Royat Pay payment status, and you avoid fulfilling orders based on unverified redirects.

Support

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