This API is used to get the balance of the respective card. This API is applicable for prepaid, debit, and credit products issued on Pine Labs platform. NOTE: This API is not applicable for corporate devicesfor the debit and credit product. It is applicable only for prepaid corporate devices. When a Balance Inquiry API issent from an IVR, the system will validate, process and return the following balance details to the IVR: • Current Outstanding Amount (with or without loan) • Last Payment Received Details (Amount /Date) – Available Credit Limit – Available Cash Limit – Total Amount Due – Minimum Amount Due – Payment Due Date – Reward Points Available Depending on the request, the system validates the following details: • The system verifies if they Allow Balance Inquiry API flag isselected for the currentstatus of the device used, on the Card Management> Institution Parameter Setup> Device Status screen. • Ifthe flag is enabled and the request is a financial request, the request is processed according to the response code of the device status. • If the response code is in approved stage, the request is processed further. • If the value of DEVICE_STATUS_CODE = UPGRADE (9) AND UPGRADE_STATUS = 1 for a financial transaction, the request is approved irrespective of the response code for program change status. • If the value of DEVICE_STATUS_CODE = UPGRADE (9) AND UPGRADE_STATUS = 2 for a financial transaction, the request is processed according to the response code of the device status. • If the account is in Freeze status and fee is not applicable, and the Allow Balance Inquiry API flag is selected in the Device Status screen, the API request is processed successfully. • Ifthe account isin Freeze status and fee is applicable, the API request is not processed. An error message 'Transaction not permitted' is displayed.
Card Number Alias (CNA) processing logic- Institution level uniqueness
- If the system locates a device with status code as Normal (0) or Upgrade (9 with upgrade status as 1), then that device is used for processing the request.
- If the system locates two devices; one with status code as Normal (0) and another with status code as Upgrade (9 with upgrade status as 1), and both have the same client ID, then the device with status code as Upgrade is selected and the request is processed on that device.
- If the CNA is linked to multiple devices with status code as Normal (0) or Upgrade (9 with upgrade status as 1), the request is rejected.
- If the system does not find any device with status code as per step 1 and 2, then the system tries to find the CNA linked to only one device in Cancelled status. If found, the device is used for further processing the request.
- If the system does not find any device with status code as perstep 4, then system tries to find the CNA linked to the latest device. The device is used for further processing the request. This does not include CNA that is linked to a device with status as Cancelled.
Card Number Alias (CNA) processing logic- Device level uniqueness
- If the system locates a device with status code as Normal (0) or Upgrade (9 with upgrade status as 1), then that device is used for processing the request.
- If the system locates two devices; one with status code as Normal (0) and another with status code as Upgrade (9 with upgrade status as 1), and both have the same client ID, then the device with status code as Upgrade isselected and the request is processed on that device.
- If the CNA is linked to multiple devices with status code as Normal (0) or Upgrade (9 with upgrade status as 1), the request is rejected.
- If the system does not find any device with status code as per step 1 and 2, then the system tries to find the CNA linked to only one device in Cancelled status. If found, the device is used for further processing the request.
- If the system does not find any device with status code as per step 4, then the system checksifthe Device Plan Code and Program Code are present in API request. If found, the system tries to locate the CNA linked to the latest device. The device is used for further processing the request. This does not include CNA that islinked to a device with status as Cancelled. Once the Balance Inquiry API validation issuccessful, the balance details are sent as a response message. If the API is unsuccessful, the relevant response code for failure issent as a response message. It is also applicable for Static Virtual Active primary devices.
PIN Validation Logic
The system validations are executed in the following order:
- The system checks if PIN Retry counter has exceeded or not.
- If it has not exceeded, the system checks if the provided PIN is the old PIN or the new one.
- PIN Required flag enabled at the device plan level on the If the card in question has been renewed with the Card Management > Program Setup > Device Configuration > Device Plan screen, the system maintainstwo PINs. In such cases, it validatesthe PIN asfollows: a. If the formFactorExpiryDate that comes in the request matches with the former expiry date of the old card, the old PIN is verified. b. If it matches with the expiry date of renewed card, the new PIN is verified. c. In case the expiry date is not received in request, the new PIN is verified.
- In the case of non-renewed cards, where the system does not store two PINS, the new PIN is verified.
- Ifthe PIN validation issuccessful, the system further processesthe API request and resets the PIN Retry Counter.
NOTE: The system accepts the old PIN only when the formFactor is a card number. The request fails if the formfactor is Card Pack ID or Card Number Alias.
Why would I need to use this resource?
Third party enables the balance inquiry service for cardholder using this API resource. If the card has more than one wallet, then balance inquiry returns a balance in each wallet balance. Otherwise, only a single wallet balance returns in response.
HTTP Status and Response Status Matrix
- HTTP Code: This is the response status code issued by a server in response to a client's request made to the server.
- Error Code: This is the error code returned by Credit+ Issuing application in the ‘code’ field of the response message indicating if the request was processed successfully or failed.
- Reason: This is the description of the error code returned by Credit+ Issuing application.
| HTTP Code | Error Code | Reason |
|---|---|---|
| 201 | 000 | Request processed successfully. |
| 400 | HDS000 | Month’s data is invalid. |
| 400 | 102 | Suspected fraud. |
| 400 | 119 | Transaction not permitted. |
| 403 | 900 | Invalid User. |
| 404 | 900 | Device(s) does not exist. |
| 500 | 999 | Statement not available for last 3. |
| 400 | 905 | Pin Retries Limit Violated |
| 400 | 997 | Cardholder authentication failed |
| 400 | 997 | Form Factor field is mandatory. |
| 400 | 997 | Form Factor Type field is invalid. |
| 400 | 997 | Form Factor Type field is mandatory. |
| 400 | 997 | Form Factor field value must have minimum length 10. |
| 400 | 997 | Form Factor field value must have maximum length 24. |
| 400 | 997 | RRN field should be numeric. |
| 400 | 997 | RRN field is mandatory. |
| 400 | 997 | RRN field value must have size 12. |
| 400 | 997 | Trace Audit Number field is mandatory. |
| 400 | 997 | Trace Audit Number field should be numeric. |
| 400 | 997 | Trace Audit Number field value must have size 6. |
| 400 | 997 | Form Factor Expiry Date field is mandatory. |
| 400 | 997 | Form Factor Expiry Date field must be in yyMM format. |
| 400 | 997 | Form Factor Expiry Date is not allowed for FormFactorType 'CPI'. |
| 400 | 997 | Note field value must have maximum length 100. |
| 400 | 997 | Product type is currently not supported. |
| 400 | 997 | Only alphanumeric characters and underscore are allowed. |
| 400 | 997 | Product Type field is invalid. |
| 400 | 997 | Program Code field value must have max length 6. |
| 400 | 997 | Program Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character. |
| 400 | 997 | Device Plan Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character. |
| 400 | 997 | Device Plan Code field value must have max length 10. |
| 400 | CNA005 | Multiple device numbers are active for given details. |
| 400 | CNA003 | Record does not exist for the given details. |
| 400 | CNA001 | Bank Does Not Exists |
| 400 | CNA002 | Card Number Alias Functionality is not applicable for this Institution |
| 400 | CNA006 | Error while fetching device details. |
| 400 | 997 | Card Number Alias field value must have max length 24. |
| 400 | 997 | Form Factor Expiry Date is not allowed for FormFactorType 'CNA’. |
| 400 | 994 | Invalid Request - Unrecognized field. |
| 400 | 988 | Encryption type Not Supported. |
| 400 | API_TXN_NOT_PERMITTED | Transaction not permitted to card holder. |
| 400 | 913 | Forward offset time limit violated. |
| 400 | CPI_MULTIPLE_DEVICE_FOUND | Multiple device numbers are active for given details. |
| 400 | CPI_NO_DEVICE_FOUND | Record does not exist for the given details. |
| 400 | 997 | Device Plan Code and Program Code are mandatory in request. |
| 404 | 998 | Device Number does not exist. |
| 500 | 913 | Backward offset time limit violated. |
| 400 | 994 | Invalid Encryption-Algorithm header value |
| 400 | 994 | Invalid Encryption Request Parameters |
| 400 | 994 | Cryptography error |
| 400 | 916 | Record not found |
| 400 | 997 | Invalid Account Number |
| 400 | 997 | Invalid combination of Account number and Account type |
| 400 | 997 | Acceptor Terminal Id field is mandatory. |