API Reference

Balance Inquiry

post
https://uatmea-iss-apigw.creditpluspinelabs.com/deviceapi/apis/v1/services/cardholder/balanceInquiry

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

  1. The system checks if PIN Retry counter has exceeded or not.
  2. If it has not exceeded, the system checks if the provided PIN is the old PIN or the new one.
  3. 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.
  4. In the case of non-renewed cards, where the system does not store two PINS, the new PIN is verified.
  5. 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 CodeError CodeReason
201000Request processed successfully.
400HDS000Month’s data is invalid.
400102Suspected fraud.
400119Transaction not permitted.
403900Invalid User.
404900Device(s) does not exist.
500999Statement not available for last 3.
400905Pin Retries Limit Violated
400997Cardholder authentication failed
400997Form Factor field is mandatory.
400997Form Factor Type field is invalid.
400997Form Factor Type field is mandatory.
400997Form Factor field value must have minimum length 10.
400997Form Factor field value must have maximum length 24.
400997RRN field should be numeric.
400997RRN field is mandatory.
400997RRN field value must have size 12.
400997Trace Audit Number field is mandatory.
400997Trace Audit Number field should be numeric.
400997Trace Audit Number field value must have size 6.
400997Form Factor Expiry Date field is mandatory.
400997Form Factor Expiry Date field must be in yyMM format.
400997Form Factor Expiry Date is not allowed for FormFactorType 'CPI'.
400997Note field value must have maximum length 100.
400997Product type is currently not supported.
400997Only alphanumeric characters and underscore are allowed.
400997Product Type field is invalid.
400997Program Code field value must have max length 6.
400997Program Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character.
400997Device Plan Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character.
400997Device Plan Code field value must have max length 10.
400CNA005Multiple device numbers are active for given details.
400CNA003Record does not exist for the given details.
400CNA001Bank Does Not Exists
400CNA002Card Number Alias Functionality is not applicable for this Institution
400CNA006Error while fetching device details.
400997Card Number Alias field value must have max length 24.
400997Form Factor Expiry Date is not allowed for FormFactorType 'CNA’.
400994Invalid Request - Unrecognized field.
400988Encryption type Not Supported.
400API_TXN_NOT_PERMITTEDTransaction not permitted to card holder.
400913Forward offset time limit violated.
400CPI_MULTIPLE_DEVICE_FOUNDMultiple device numbers are active for given details.
400CPI_NO_DEVICE_FOUNDRecord does not exist for the given details.
400997Device Plan Code and Program Code are mandatory in request.
404998Device Number does not exist.
500913Backward offset time limit violated.
400994Invalid Encryption-Algorithm header value
400994Invalid Encryption Request Parameters
400994Cryptography error
400916Record not found
400997Invalid Account Number
400997Invalid combination of Account number and Account type
400997Acceptor Terminal Id field is mandatory.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum

Accessing channel. Recommended values are 31 or API. No validation on channel for this API.

Allowed:
string
enum
required

It is used to identify whether Card Number (CRD) or Card Number Alias (CNA) or Card Pack ID (CPI) is received in request. Length: 3. Not Null. Either CRD or CNA or CPI.

Allowed:
string
required
length between 10 and 24

It will contain either Card Number or Card Number Alias or Card Pack ID based on the formFactorType value. Not Null. Maximum length: 24. Minimum length: 10 (minimum length is not applicable for CNA).

string
required
length between 12 and 12
^[0-9]{12}$

Retrieval Reference Number. It can be used to retrieve the original transaction data. It is Mandatory and a Unique Authorization Reference Number (Reference Retrieval Number). Fix length 12. Not NULL. Must be number.

string
required
length between 6 and 6
^[0-9]{6}$

A number assigned by the originator of a transaction to uniquely identify a transaction throughout its life. Fix length is 6. Not NULL. Must be number.

string
^[0-9]{4}$

It is the date on which the card number will expire. Format: YYMM. Mandatory if formFactorType is CRD.

string
length ≤ 100

Free text description about the request. Maximum length 100.

string
^[0-9]+$

MCC is used to classify the business by the type of goods or services it provides. Numeric.

string

Identification code of acceptor terminal. This field is mandatory for closed loop programs or for debit products.

string

Identification of acquiring entity. This is mandatory for Closed Loop Programs.

string
enum

Product type of Device. Valid values: P (Pre-paid), C (Credit), D (Debit). This field is required only when formFactorType is CNA and multiple devices are linked with same CNA.

Allowed:
string
length ≤ 6
^[A-Z0-9_]+$

Program attached to the device. Maximum Length: 6. This field is required only when formFactorType is CNA and multiple devices are linked with same CNA.

string
length ≤ 10
^[A-Z0-9_]+$

Device Plan Code attached with the device. Maximum Length: 10. This field is required only when formFactorType is CNA and multiple devices are linked with same CNA.

string
enum

Indicates the type of CBS account. Must contain any of the valid values: SAVING, CURRENT, CREDIT. This field is applicable only for debit products.

Allowed:
string
length ≤ 24
^[0-9]+$

Primary account number in CBS. Maximum length: 24. Numeric [0-9]. This field is applicable only for debit products.

string
required
^[0-9]+$

Current UTC timestamp in milliseconds. Numeric. DES key expiration criteria depends on input UTC timestamp. Applicable only for encrypted requests. Not null.

Headers
string
^[a-zA-Z0-9-]{1,50}$

API Consumer must share Correlation-ID in HTTP header for API requests. The Correlation-ID must be unique for each request. It is recommended to generate a universally unique identifier (UUID) of length 32 or 36 that is compliant with RFC 4122. The maximum supported length is 50 alphanumeric characters. For example, ac97d177-9345-4934-8343-0f91a7a02836. If the Correlation-ID is not received in the incoming request, the system generates the UUID dynamically and assigns it to the request.

string
enum
required

API Consumer must share Encryption-Algorithm as a key (value: DES168) in HTTP header in order to encrypt the API requests.

Allowed:
string

API Consumer can share Source in HTTP header for API requests. For the list of Source values, see the Pre-conditions for HTTP Header of REST API topic in the Pre-requisite for Rest API section.

Response

Updated about 1 year ago

Did this page help you?
Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 1 year ago

Did this page help you?