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
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token provided by Authentication Endpoint |
| Accept | Yes | It must be set to application/JSON. |
| Content-Type | Yes | It 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:
| Parameter | Type | Description |
|---|---|---|
| gatewayOrderRequest | Object | The invoice details were sent to the gateway. |
| amount | Float | The total amount of the invoice. |
| transactionNo | String | The gateway assigns the transaction number. |
| orderStatus | String | The status of the invoice. |
| url | String | The URL to the payment page. |
| qrUrl | String | The URL to the QR code image for the payment |
| checkUrl | String | The 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. |
| success | Boolean | This 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. |
| digitalOrder | Boolean | This field indicates whether the order contains digital products or not. |
| foreignCurrencyRate | Float | This is about the foreign currency rate used in the transaction, if applicable. In addition, it includes the exchange rate related to the SAR currency. |
| paymentReceipt | Object | An 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. |
| paymentErrors | Array | Any payment errors that occurred. |
Order Status Possible Values
| Value | Description |
|---|---|
| Pending | The invoice is still pending payment. |
| Paid | The customer successfully paid the invoice. |
| Canceled | Paylink 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
paymentErrorsfield 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.
Updated 9 months ago