ExecutePayment API

Create invoice and execute payment transaction

Overview

The "ExecutePayment" endpoint is a POST request. It is used to create an invoice and execute the payment transaction. This endpoint processes the actual payment after you have initiated a payment session or selected a payment method.

The endpoint on Swagger is: Payment_ExecutePayment.

📘 Request Header: Add "Authorization": "Bearer {Token}" to request header. Token of demo configuration can be found in your portal account settings.

Request Model

The request is a POST request with the following parameters:

Required Fields

Input Parameter Type Description
InvoiceValue number The total amount of the invoice including service charges
CurrencyIso string The currency code. For Saudi Arabia, use SAR.

Optional Fields

Input Parameter Type Description
SessionId string The session ID received from InitiateSession endpoint (for Embedded Payment)
PaymentMethodId integer The payment method ID from InitiatePayment response (Note: Do not use with SessionId)
CustomerName string Customer's full name
CustomerEmail string Customer's email address
CustomerMobile string Customer's mobile number
CallBackUrl string URL to redirect customer after successful payment
ErrorUrl string URL to redirect customer after failed payment
Language string Language code ("en" or "ar")
CustomerReference string Your internal reference for this transaction
InvoiceItems array Array of invoice items (optional)
❗ Important: When using Embedded Payment, use SessionId parameter and do NOT pass PaymentMethodId as it will overwrite the SessionId.

Response Model

The response contains the following fields:

Response Field Type Description
IsSuccess boolean Indicates if the request was successful
Message string Response message
ValidationErrors array Array of validation errors (if any)
Data.InvoiceId integer The unique invoice ID
Data.IsDirectPayment boolean Indicates if this is a direct payment
Data.PaymentURL string The payment URL to redirect the customer (3D Secure page for cards)
Data.CustomerReference string Your customer reference
Data.UserDefinedField string Any user-defined field you passed
Data.RecurringId string Recurring payment ID (if applicable)

Sample Messages

ExecutePayment Request (With SessionId - Embedded Payment)

🚧 Deprecated for new integrations. This SessionId flow (paired with /api/payment/initiate-session and the older embedded widget) does not reliably attribute completed payments to your settlement account. For new embedded checkout integrations, use create-session instead. Kept here only for existing integrations that already depend on it. 
{
   "SessionId":"36c1bab2-1e21-ec11-bae9-000d3aaca798",
   "InvoiceValue":10,
   "CurrencyIso":"SAR",
   "CallBackUrl":"https://yoursite.com/success",
   "ErrorUrl":"https://yoursite.com/error"
}

ExecutePayment Request (With PaymentMethodId - Redirect Checkout)

{
   "InvoiceValue":100,
   "CurrencyIso":"SAR",
   "PaymentMethodId":2,
   "CustomerName":"John Doe",
   "CustomerEmail":"[email protected]",
   "CustomerMobile":"1234567890",
   "CallBackUrl":"https://yoursite.com/success",
   "ErrorUrl":"https://yoursite.com/error",
   "Language":"en",
   "CustomerReference":"ORDER-12345",
   "InvoiceItems":[
      {
         "ItemName":"Product Name",
         "Quantity":1,
         "UnitPrice":100
      }
   ]
}

ExecutePayment Response

{
   "IsSuccess":true,
   "Message":"Invoice Created Successfully!",
   "ValidationErrors":null,
   "Data":{
      "InvoiceId":927972,
      "IsDirectPayment":false,
      "PaymentURL":"https://checkout.royatpay.example/pay?invoiceKey=0106292797237&methodId=20",
      "CustomerReference":"ORDER-12345",
      "UserDefinedField":null,
      "RecurringId":""
   }
}

Payment URL Handling

After receiving the PaymentURL in the response, you have different options based on the payment method:

For Card and Google Pay:

  • Redirect the customer to the PaymentURL (3D Secure page)
  • Open the PaymentURL in an iframe

For Apple Pay:

  • Invoke the PaymentURL in the backend and get status via webhook or GetPaymentStatus
  • Open the PaymentURL and redirect to CallBackUrl/ErrorUrl

For STC Pay:

  • Open the PaymentURL to redirect customer to CallBackUrl or ErrorUrl based on transaction status
👍 Best Practice: Use webhooks and GetPaymentStatus together to automatically update your system instead of manually following up with customers. We recommend using both as a best practice.

Checkout Page Branding

Customer-facing checkout pages are presented under Royat Pay branding. Your integration only needs to send the payment request and redirect the customer to the returned PaymentURL when required.

API Endpoint

Endpoint Method Description
/api/payment/execute POST Create invoice and execute payment transaction

Support

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