4. Get Invoice

This endpoint is used to get invoice details identified by the transaction number. It can also be used to check the order status and the paid amount.

Endpoint

GET /api/getInvoice/{transactionNo}

Request Headers

HeaderRequiredDescription
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"
}

Response Body

The response to the request is as follows:

ParameterTypeDescription
gatewayOrderRequestObjectThe invoice details were sent to the gateway.
amountFloatThe total amount of the invoice.
transactionNoStringThe gateway assigns the transaction number.
orderStatusStringThe status of the invoice.
urlStringThe URL to the payment page.
qrUrlStringThe URL to the QR code image for the payment
checkUrlStringThe URL of the API can be used to check the status of the price. NOTE: Calling this URL must have a token in the header.
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.
paymentReceiptObjectAn object is displayed when the order is paid. It contains the following information:

- receiptUrl: The URL of the receipt.
- passcode: The passcode required to open the receipt.
- paymentMethod: The payment type, such as MADA, VISA, etc.
- paymentDate: The payment date.
- bankCardNumber: The last four digits of the card, if any.
paymentErrorsArrayAny payment errors that occurred.

Order Status Possible Values

ValueDescription
PendingThe invoice is still pending payment.
PaidThe customer successfully paid the invoice.
CanceledPaylink or the merchant compensated the invoice.

πŸ“˜

Declined Payments

In the event of a payment decline, the orderStatus remains pending payment until canceled by the Paylink system. However, the paymentErrors field will indicate the reason for the decline.

Payment error codes

The payment error codes are returned within the "paymentErrors" array, consisting of objects like the example below:

[
  {
    "errorCode": "05", // Error code.
    "errorTitle": "Do Not Honor", // Title of the error.
    "errorMessage": "Do Not Honor", // Detailed description of the error.
    "errorTime": "2020/10/25" // Time of the decline.
  },
  {
    // Another error object...
  }
]

For a complete list of possible error codes and their meanings, refer to our Payment Errors Codes documentation.

Understanding these error codes is crucial for diagnosing payment failures, enabling prompt resolution and smoother transaction processes.