InitiatePayment API

Retrieve available payment methods with service charges

Overview

The "InitiatePayment" endpoint is a POST request. It is used to retrieve all available and enabled Payment Methods of your portal account with any service charge that may apply to the checkout. Detailed functionality of how to use this endpoint is explained in the checkout integration section.

The endpoint on Swagger is: Payment_InitiatePayment.

Now, we are going to declare the endpoint and its models along with each accepted parameter and possible value.

📘 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:

Input Parameter	Type	Description
InvoiceAmount	number	The transaction amount you need to charge your customer after applying coupon codes, taxes, fare updates, and so on.
CurrencyIso	string	The currency code that you need to charge your customer through. For full list please check ISO Lookups.

📘 Note: We calculate the total amount of the invoice for a certain currency after applying the exchange rate.

Response Model

After viewing the Response Model that you will get as a result of your request, here, you will find full details about the Data Model of this API endpoint. Let's check it and its contents.

Response Field	Type	Description
PaymentMethodId	integer	The payment method ID that is used in Royat Pay system to identify the method of payment
PaymentMethodAr	string	Payment method Arabic name
PaymentMethodEn	string	Payment method English name
PaymentMethodCode	string	Code that refers to the payment method
IsDirectPayment	boolean	"true" or "false" to indicate if this payment method supports Direct Payment
ServiceCharge	double	The transaction service charges based on the settings in the portal profile
TotalAmount	double	The total amount that you should send before calling Execute Payment including the service charges after calculating it.
CurrencyIso	string	The currency code that you have sent in CurrencyIso
ImageUrl	string	Payment icon URL that you can use to display it in your page for the customers
IsEmbeddedSupported	boolean	"true" or "false" to indicate if this payment method supports Embedded Payment
PaymentCurrencyIso	string	The currency in which the payment will be made

👍 Hint: Initiate Payment is an optional step that return a list of Payment Methods that you need in Execute Payment. It does not execute or store any information about the payment. It just gets the proper information based on your Royat Pay profile and calculates the service charges based on the settings there.

Sample Messages

Initiate Payment Request

{
  "InvoiceAmount": 100,
  "CurrencyIso": "SAR"
}

Initiate Payment Response

{
  "IsSuccess": true,
  "Message": "Initiated Successfully!",
  "ValidationErrors": null,
  "Data": {
    "PaymentMethods": [
      {
        "PaymentMethodId": 2,
        "PaymentMethodAr": "فيزا / ماستر",
        "PaymentMethodEn": "VISA/MASTER",
        "PaymentMethodCode": "vm",
        "IsDirectPayment": false,
        "ServiceCharge": 0.2,
        "TotalAmount": 100,
        "CurrencyIso": "SAR",
        "ImageUrl": "https://royatpay.example.com/imgs/payment-methods/vm.png",
        "IsEmbeddedSupported": true,
        "PaymentCurrencyIso": "SAR"
      },
      {
        "PaymentMethodId": 11,
        "PaymentMethodAr": "أبل الدفع",
        "PaymentMethodEn": "Apple Pay",
        "PaymentMethodCode": "ap",
        "IsDirectPayment": false,
        "ServiceCharge": 2,
        "TotalAmount": 100,
        "CurrencyIso": "SAR",
        "ImageUrl": "https://royatpay.example.com/imgs/payment-methods/ap.png",
        "IsEmbeddedSupported": true,
        "PaymentCurrencyIso": "SAR"
      },
      {
        "PaymentMethodId": 32,
        "PaymentMethodAr": "جوجل للدفع",
        "PaymentMethodEn": "GooglePay",
        "PaymentMethodCode": "gp",
        "IsDirectPayment": false,
        "ServiceCharge": 2,
        "TotalAmount": 100,
        "CurrencyIso": "SAR",
        "ImageUrl": "https://royatpay.example.com/imgs/payment-methods/gp.png",
        "IsEmbeddedSupported": true,
        "PaymentCurrencyIso": "SAR"
      }
    ]
  }
}

API Endpoint

Endpoint	Method	Description
`/api/payment/initiate`	POST	Retrieve all available and enabled Payment Methods with commission charges

Support

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