Direct Payment


The provided API documentation details the payInvoice endpoint within the Paylink API framework. This specific endpoint is designed for merchants, enabling them to create invoices and accept online payments through the Paylink gateway. The integration process facilitates the collection of card information directly from customers. This information is then utilized for processing payments on your webpage. Notably, this method provides immediate results regarding the payment status, eliminating the need for webpage redirections.

Important Note

To request activation of the direct payment feature, adherence to Payment Card Industry Data Security Standards (PCI DSS) is mandatory, and obtaining PCI DSS certification is essential. Compliance with these standards is a legal requirement. Non-compliance not only endangers customer data but also exposes you to the possibility of substantial penalties.

Once you have ensured compliance and obtained the necessary certification, please reach out to your account manager or sales representative to enable the Direct Payment feature.


Available Payment Methods for Direct Integration

It's essential to be aware that not all Payment Methods support the Direct Payment feature. For detailed information, please consult with your account manager.


Paylink has two environments which are testing and production environments. The base server link of both environments are:



The testing server base is



The production server base is


This endpoint requires authentication using a bearer token provided by RestPilot Paylink. The token should be included in the Authorization header of the request.


POST /api/payInvoice

Request Headers

AuthorizationYesBearer token provided by Authentication Endpoint
AcceptYesIt must be set to application/JSON.
Content-TypeYesIt must be set to application/JSON.
  "Authorization": "Bearer [id_token]",
  "Accept": "application/json",
  "Content-Type": "application/json"

Request Body Parameters

Creating an invoice requires information on the new invoice, such as the amount, callback URL, and client email. The following table describes the body parameters.

amountfloatYesThe total amount of the invoice. NOTE: Buyer will pay this amount regardless of the total amounts of the products' prices.
callBackUrlstringNoThe URL will be called when the payment is complete or canceled.
clientEmailstringNoThe email address of the client.
clientMobilestringYesThe mobile number of the client.
currencystringNoThe currency code of the invoice. The default value is SAR. (e.g., USD, EUR, GBP).
clientNamestringYesThe name of the client.
notestringNoA note for the invoice.
orderNumberstringYesA unique identifier for the invoice.
productsarrayYesAn array of product objects will be included in the invoice. See product object details below.
smsMessagestringNoThis option will enable the invoice to be sent to the client's mobile specified in clientMobile. The message of this SMS can have placeholder for dynamic content. The placeholders are:

- [CLIENT_NAME]: Name of the client.
- [TRANSACTION_NO]: Transaction number from Paylink of the invoice.
- [ORDER_NUMBER]: The order number of the invoice.
- [QR_URL]: The URL that display QR code of the invoice.
- [MOB_URL]: The URL of the simple invoice format for mobile devices.
- [SHORT_URL]: The short URL of the invoice.
- [AMOUNT]: The amount of the invoice.
- [WEB_URL]: The full URL of the invoice.NOTE: The service requires additional aggrement with Paylink sales.
supportedCardBrandsArrayNoList of supported card brands. This list is optional. values are: [mada, visaMastercard, amex, tabby, tamara, stcpay, urpay]
displayPendingBooleanNoThis option will make this invoice displayed in
cardObjectYesThe card object within the provided JSON structure represents the credit or debit card information required for processing a payment. It contains three fields:

Expiry: This is an object itself, housing the card's expiration date. It's split into two parts: month and year. In the given example, the month is "04", indicating April, and the year is "28", presumably representing 2028.

Number: This is the card number, a sequence of digits unique to each card. In this case, the number provided is "4111111111111111", which is a commonly used placeholder in payment processing examples.

Security code: Also known as the CVV (Card Verification Value), this is a security feature for card-not-present transactions. Here, it is given as "446".

Product Object Details

titlestringYesThe title of the product.
pricefloatYesThe price of the product.
qtyintYesThe quantity of the product.
descriptionstringNoA description of the product.
isDigitalboolNoSet to true if the product is digital.
imageSrcstringNoA URL to an image of the product.
specificVatfloatNoThe VAT rate for the product. This will override the default VAT rate for the invoice if set.
productCostfloatNoThe cost of the product. This will be used to calculate the profit margin for the merchant.

An example of the request is as follows:

  "amount": 5,
  "callBackUrl": "",
  "clientEmail": "[email protected]",
  "clientMobile": "0509200900",
  "clientName": "Zaid Matooq",
  "note": "This invoice is for VIP client.",
  "orderNumber": "MERCHANT-ANY-UNIQUE-ORDER-NUMBER-123123123",
    "expiry": {
      "month": "04",
      "year": "28"
    "number": "4111111111111111",
  "products": [
      "description": "Brown Hand bag leather for ladies",
      "imageSrc": "",
      "isDigital": true,
      "price": 150,
      "qty": 1,
      "title": "Hand bag"

Success Response

If the add invoice request success. The response details are as follows:

gatewayOrderRequestObjectThe invoice details were sent to the gateway. See details below.
amountFloatThe total amount of the invoice.
transactionNoStringThe gateway assigns the transaction number.
orderStatusStringThe status of the invoice.
paymentErrorsStringAny payment errors that occurred.
urlStringThe URL to the 3DS page.
successBooleanThis field indicates whether this endpoint operation is successful or not. NOTE: This is not the payment or order status. It is the endpoint for getting invoice details.
digitalOrderBooleanThis field indicates whether the order contains digital products or not.
foreignCurrencyRateFloatThis is about the foreign currency rate used in the transaction, if applicable. In addition, it includes the exchange rate related to the SAR currency.

Failure Response:

If any failure occurred, the response details are as follows

detailstringA detailed error message explaining the reason for the failure.
titlestringA short title for the error that summarizes the reason for the failure.
typestringA URL that identifies the type of error.
statusstringThe HTTP status code for the response.

Important Note


Invoice minimum amount

The minimum invoice amount in the Paylink system is SAR 5.00.


Important use of GetInvoice in server side

Merchant's application must perform this endpoint on the server-side. Then send the resulting response to the client-side. If this endpoint is used in the client-side, then its result must be verified and confirmed using GetInvoice endpoint from the server-side to check the orderStatus equal to piad and the amount paid.

Try the endpoint

For more detail about the endpoint and to try it out, please click here.