5. Get Invoice
Paylink Get Orders API enables the merchant's application to get specific invoices.
Overview
The merchant's application is responsible for calling this endpoint to check the payment status of the invoice using "TransactionNo." Then from the response, the merchant's application checks the invoice payment status from the field "orderStatus."
Important Note
Important Note for using
getInvoiceMerchant's application must call the
getInvoiceendpoint immediately after the payment on the server side. First, check the integrity of the price by getting the amount paid "amount." and comparing it with the invoice amount, then check the payment status "orderStatus" to be "paid.".
Endpoint
GET /api/getInvoice/{transactionNo}
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token. |
| Content-Type | Yes | It must be set to 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. See details below. |
| amount | Float | The total amount of the invoice. |
| transactionNo | String | The gateway assigns the transaction number. |
| orderStatus | String | The status of the invoice. |
| paymentErrors | String | Any payment errors that occurred. |
| 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. |
Order Status Possible Values
orderStatus field can contain the following 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. |
If the payment is declined, orderStatus is still pending payment until the Paylink system cancels it, but the paymentErrors field will contain the reason for the decline.
Payment error codes
The payment error code returned in the "paymentErrors" array of the following example object:
{
"errorCode":"05", //The code of the error.
"errorTitle":"Do Not Honor", //The title of the error
"errorMessage":"Do Not Honor", //The detail description message of the error
"errorTime":"2020/10/25" //The time of the decline
}
The full possible values are as follows:
| Code | Title | Description |
|---|---|---|
| 01 | Refer To Card Issuer | The issuer refuses the transaction |
| 03 | Invalid Merchant Number | This error indicates that the entered details are incorrect or your merchant facility is non-functional |
| 04 | Pick Up Card | The transaction is declined by the issuing bank that requested to retain the card as it could be reported as lost or stolen |
| 05 | Do not honour | The issuing bank is unwilling to accept the transaction |
| 06 | Error | Error |
| 12 | Invalid Transaction | An error occurred while processing the card |
| 13 | Invalid Amount | Invalid amount |
| 14 | Invalid Card Number | The card issuing bank has declined the transaction because of an incorrectly entered credit card number or a number that doesn't exist |
| 15 | No Issuer | The customer's card issuer doesn't exist |
| 22 | Suspected Malfunction | The issuing bank is not responding during the transaction |
| 30 | Format Error | Format error |
| 31 | Bank Not Supported By Switch | The customer's bank has declined the transaction because it doesn't allow using the card for mail/telephone, fax, email, or internet orders |
| 34 | Suspected Fraud, Retain Card | The transaction is declined by the issuing bank as there is suspected fraud on this credit card number |
| 37 | Contact Acquirer Security Department | The customer's card issuer has declined the transaction and requested to retain your customer's card |
| 41 | Lost Card | The issuing bank has declined the transaction as the owner of the card reported it as lost or stolen |
| 42 | No Universal Account | The issuing bank declines the transaction as the account type is not valid for this card number |
| 43 | Stolen Card | The issuing bank has declined the transaction as the credit card owner has reported this card as stolen |
| 49 | The Card Was Declined | The customer's card issuer has declined the transaction as the credit card is not enabled for online transactions |
| 51 | Insufficient Funds | The transaction is denied by the issuing bank as there are not enough funds in the associated bank account to complete this payment, or the transaction will put the customer's credit card over the limit |
| 54 | Expired Card | The card is expired and no longer valid to use |
| 56 | No Card Record | The issuer declines the transaction, as the credit card number does not exist |
| 57 | Function Not Permitted To Cardholder | The issuing bank has declined the transaction as this card cannot be used for this type of transaction |
| 58 | Function Not Permitted To Terminal | The code appears when the card cannot be used for this type of transaction or when the merchant processing account is not correctly configured |
| 59 | Suspected Fraud | The issuer declined the transaction because it appeared fraudulent |
| 61 | Withdrawal Limit Exceeded | The issuer has declined the transaction because it will exceed the customer's card limit |
| 62 | Restricted Card | The card is invalid in a specific region or country, or the customer tried to pay online with a card that does not support your online payments |
| 67 | Capture Card | The issuing bank declined the transaction because the card is suspected to be counterfeit |
| 91 | Card Issuer Unavailable | There was a problem contacting the issuing bank to authorize the transaction |
| 92 | Unable To Route Transaction | The customer's card can't be found for routing, and the code is mainly used for a test credit card number. |
Try the endpoint
For more detail about the endpoint and to try it out, please click here.
Updated 2 months ago