Card Balance Enquiry

API: Ws_Balance_Enquiry and Ws_Balance_Enquiry_V2

This web service returns the current available balance on the card.

There are two versions of this web service. Ws_Balance_Enquiry_V2 omits a few request parameters and includes a new LimitInfo response structure, as described below.

Thredd recommends that clients implement EHIClosed External Host Interface (EHI) is a Thredd facility that enables exchange of data between the Thredd processing centre and external systems using online web services. All transaction data processed by Thredd is transferred to the External Host side via EHI in real time. For certain types of transactions such as Authorisations, the External Host can participate in payment transaction authorisation. (External Host Interface) to receive up-to-date customer balances after every transaction to comply with a Mastercard mandate which states that issuers must offer a mobile-based transaction alerts service to cardholders. For details, contact your Implementation Manager.

Record Description

Tag

Type

Minimum Length

Maximum Length

Description

Request

Response

<WSID>

N

1

19

Web service ID. Must be unique for every request. For details, see the FAQs.

Mandatory

Mandatory

<IssCode>

AN

1

4

Thredd Issuer (Program Manager) Code. Assigned by Thredd.

Mandatory

Mandatory

<TxnCode>

AN

1

2

The Transaction Code. See Transaction Codes. Default value ‘3’.

Mandatory

Mandatory

<ClientCode>

AN

1

64

User ID of the customer using the service. Only applicable to systems using member logins. Returned in the response if present in the request. Note: Legacy field. Not used.

Conditional

Conditional

<itemSrc>

N

1

5

Source field which defines the item source type. See Item Source Types. If used, overrides any existing fees for using this web service.

Mandatory

Omit

<AuthType>

AN

1

1

Parameter to specify how the card is authenticated. See Authentication Methods.

Mandatory

Omit

<PAN>

AN

14

19

Card Number. Unique card identifier. Mandatory in request if <track2> and <PublicToken> are not present.

Conditional

Omit

<Track2>

AN

1

40

The card’s Track 2. Mandatory in request and response if <PAN> and <PublicToken> are not present or when <AuthType> is ‘4’.

Conditional

Omit

<PublicToken>

AN

1

9

The card’s public token, Mandatory in request if <PAN> and <Track2> are not present. Mandatory in the response.

Conditional

Mandatory

<DOB>

YYYY-MM-DD

10

10

Date of Birth. Mandatory if value of <AuthType> is ‘2’ or ‘6’.

Conditional

Omit

<CVV>

AN

3

3

Card Verification ValueClosed The Card Verification Value (CVV) on a credit card or debit card is a 3 digit number on VISA, MasterCard and Discover branded credit and debit cards. Cardholder's are typically required to enter the CVV during any online or cardholder not present transactions. CVV numbers are also known as CSC numbers (Card Security Code), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process that makes them harder to guess., the 3-digit code printed on the back of the card. Mandatory if the value of <AuthType> is ‘3’.

Conditional

Omit

<AccCode>

AN

0

6

Access code or passcode. If provided, must be 6 digits, leading zeroes are acceptable. Leave empty if not required. Mandatory if the value of <AuthType> is ‘4’.

Conditional

Omit

<LastName>

AN

1

20

Cardholder's last name for authenticating the cardholder if the value of <AuthType> is ‘6’.

Conditional

Omit

<LocDate>

YYYY-MM-DD

10

10

The local current date in year-month-date format.

Mandatory

Mandatory

<LocTime>

HHMMSS

6

6

The local current time, in hour-minute-second format.

Mandatory

Mandatory

<TerminalID>

AN

1

15

Point of Sale (POS) or other terminal identifier, such as a hostname.

Optional

Omit

<GetLimits>

AN

1

1

Optional request parameter to return limit information. Possible values are: 0 = Do not return limits information; 1 = Return limits information. If GetLimits is empty or not supplied, the default is 0. If GetLimits is 1, an extra XML element is returned in the reponse. See LimitInfo Details below.

Optional

Omit

<AvlBal>

D

1

20

The current balance on the card account. This includes all financial transactions and outstanding authorisations. The balance amount can include up to four decimal places, depending on the currency exponent (e.g., 10.99 for EUR which has a currency exponent of 2). See Currency Codes.

Omit

Mandatory

<BlkAmt>

D

1

20

Amount of funds blocked on the card account as a result of all outstanding authorisations. The balance amount can include up to four decimal places, depending on the currency exponent (e.g., 10.99 for EUR which has a currency exponent of 2). See Currency Codes.

Omit

Mandatory

<CurCode>

AN

3

3

3-letter ISO currency code for the currency (e.g. EUR).

Omit

Mandatory

<SysDate>

YYYY-MM-DD

10

10

The system processing date.

Omit

Mandatory

<PINStatus>

N

1

1

Indicates whether the allowed number of card PIN tries has been exceeded. 0 = No; 1 = Yes.

Omit

Mandatory

<LimitInfo>

 

 

 

See LimitInfo Details below. Occurs 0 or 1 times in the response.

Omit

Optional

<ActionCode>

AN

3

3

The action code for the response. See Action Codes.

Omit

Mandatory

LimitInfo Details (V1)

Tag

Type

Minimum Length

Maximum Length

Description

Request

Response

<MaxAllowableBalance>

D

1

20

Maximum allowed balance of the card.

Omit

Mandatory

<DailyLoadLimit>

D

1

20

Daily load limit.

Omit

Mandatory

<DailyLoadFrequencyLimit>

D

1

20

Daily load frequency.

Omit

Mandatory

<AmountLoaded>

D

1

20

Amount loaded today.

Omit

Mandatory

<NoOfLoads>

D

1

20

Number of loads today.

Omit

Mandatory

<AmountLeftToLoad>

D

1

20

Available amount left to load today.

Omit

Mandatory

<NoOfLoadLeft>

D

1

20

Available number of loads left today.

Omit

Mandatory

<DailyPosLimit>

D

1

20

Daily POS terminal spend limit.

Omit

Mandatory

<DailyPosFrequencyLimit>

D

1

20

Daily POS spend frequency limit (how many times the cardholder is allowed to spend at a POS terminal.)

Omit

Mandatory

<POSUsage>

D

1

20

POS terminal spend value so far today.

Omit

Mandatory

<NoOfPOSUsage>

D

1

20

POS terminal spend frequency today.

Omit

Mandatory

<ValueOfPOSLeft>

D

1

20

POS terminal spend value left today.

Omit

Mandatory

<NoOfPOSTransactionsLeft>

D

1

20

POS terminal spend frequency left today.

Omit

Mandatory

<DailyCashLimit>

D

1

20

Cash withdrawal daily value limit.

Omit

Mandatory

<DailyCashFrequencyLimit>

D

1

20

Cash withdrawal daily frequency limit.

Omit

Mandatory

<CashWithdrawal>

D

1

20

Cash withdrawals so far today.

Omit

Mandatory

<NoOfCashWithdrawal>

D

1

20

Cash withdrawal frequency today.

Omit

Mandatory

<ValueOfCashLeft>

D

1

20

Cash withdrawal value left today.

Omit

Mandatory

<NoOfCashTransactionLeft>

D

1

20

Cash withdrawal frequency left today.

Omit

Mandatory

<DailyUnLoadLimit>

D

1

20

Unload daily limit.

Omit

Mandatory

<DailyUnLoadFrequencyLimit>

D

1

20

Unload daily frequency limit.

Omit

Mandatory

<AmountUnLoaded>

D

1

20

Amount unloaded so far today.

Omit

Mandatory

<NoOfUnLoads>

D

1

20

Frequency of unloads today.

Omit

Mandatory

<AmountLeftToUnLoad>

D

1

20

Amount available to unload today.

Omit

Mandatory

<NoOfUnLoadLeft>

D

1

20

Frequency of unloads available today.

Omit

Mandatory

LimitInfo Details (V2)

Tag

Type

Minimum Length

Maximum Length

Description

Request

Response

<MaxAllowableBalance>

D

1

20

Maximum allowed balance of the card.

Omit

Mandatory

<SubLimit>

 

 

 

Containing element (repeats).

Omit

Mandatory

<Process>

AN

1

10

Name of the process that the sub-limit affects. Valid values are: POS,

CASH and LOAD.

Omit

Mandatory

Source (attribute)

N

1

3

The numeric Load Source (LoadSrc). Only applies to LOAD sub limits and is optional.

Omit

Conditional

<MaxPerTransaction>

D

1

20

Maximum amount of a single transaction.

Omit

Mandatory

<MinPerTransaction>

D

1

20

Minimum amount of a single transaction.

Omit

Mandatory

<SubLimitPeriod>

 

 

 

Containing element  (repeats)

Omit

Mandatory

<Period>

N

1

10

Number of units of the period.

Omit

Mandatory

<Unit>

AN

1

10

Type of period unit. Valid values are: Hour, Day, Month and Year.

Omit

Mandatory

<Limit>

D

1

20

Total financial amount of limit per period.

Omit

Mandatory

<Frequency>

N

1

10

Number of transactions allowed within the period.

Omit

Mandatory

<Usage>

D

1

20

Current usage of total financial amount of limit.

Omit

Mandatory

<No>

N

1

10

Current usage of number of transactions within the period.

Omit

Mandatory

<SubLimitPeriod>

 

 

 

Containing element (repeats).

Omit

Mandatory

<SubLimit>

 

 

 

Containing element (repeats).

Omit

Mandatory

Request

Copy 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hyp="http://www.globalprocessing.ae/HyperionWeb">
   <soapenv:Header>
      <hyp:AuthSoapHeader>
         <hyp:strUserName>******</hyp:strUserName>
         <hyp:strPassword>******</hyp:strPassword>
      </hyp:AuthSoapHeader>
   </soapenv:Header>
   <soapenv:Body>
      <hyp:Ws_Balance_Enquiry>
         <hyp:WSID>2021123456789</hyp:WSID>
         <hyp:IssCode>PMT</hyp:IssCode>
         <hyp:TxnCode>3</hyp:TxnCode>
         <hyp:ClientCode></hyp:ClientCode>
         <hyp:ItemSrc>2</hyp:ItemSrc>
         <hyp:AuthType>1</hyp:AuthType>
         <hyp:PAN></hyp:PAN>
         <hyp:Track2></hyp:Track2>
         <hyp:PublicToken>123456789</hyp:PublicToken>
         <hyp:DOB></hyp:DOB>
         <hyp:CVV></hyp:CVV>
         <hyp:AccCode></hyp:AccCode>
         <hyp:LastName></hyp:LastName>
         <hyp:LocDate>2021-01-01</hyp:LocDate>
         <hyp:LocTime>120000</hyp:LocTime>
         <hyp:TerminalID></hyp:TerminalID>
         <hyp:GetLimits>1</hyp:GetLimits>
      </hyp:Ws_Balance_Enquiry>
   </soapenv:Body>
</soapenv:Envelope>

Response

Copy 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <Ws_Balance_EnquiryResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
         <Ws_Balance_EnquiryResult>
            <WSID>2021123456789</WSID>
            <IssCode>PMT</IssCode>
            <TxnCode>3</TxnCode>
            <PublicToken>123456789</PublicToken>
            <LocDate>2021-01-01</LocDate>
            <LocTime>120000</LocTime>
            <AvlBal>10</AvlBal>
            <BlkAmt>0</BlkAmt>
            <CurCode>GBP</CurCode>
            <ClientCode/>
            <SysDate>2021-01-01</SysDate>
            <ActionCode>000</ActionCode>
            <PINStatus>0</PINStatus>
            <LimitInfo>
               <LimitInformation>
                  <MaxAllowableBalance>375000</MaxAllowableBalance>
                  <DailyLoadLimit>375000</DailyLoadLimit>
                  <DailyLoadFrequencyLimit>50</DailyLoadFrequencyLimit>
                  <AmountLoaded>0</AmountLoaded>
                  <NoOfLoads>0</NoOfLoads>
                  <AmountLeftToLoad>374305.93</AmountLeftToLoad>
                  <NoOfLoadLeft>50</NoOfLoadLeft>
                  <DailyPosLimit>375000</DailyPosLimit>
                  <DailyPosFrequencyLimit>9999</DailyPosFrequencyLimit>
                  <POSUsage>0</POSUsage>
                  <NoOfPOSUsage>0</NoOfPOSUsage>
                  <ValueOfPOSLeft>694.07</ValueOfPOSLeft>
                  <NoOfPOSTransactionsLeft>9999</NoOfPOSTransactionsLeft>
                  <DailyCashLimit>0</DailyCashLimit>
                  <DailyCashFrequencyLimit>0</DailyCashFrequencyLimit>
                  <CashWithdrawal>0</CashWithdrawal>
                  <NoOfCashWithdrawal>0</NoOfCashWithdrawal>
                  <ValueOfCashLeft>694.07</ValueOfCashLeft>
                  <NoOfCashTransactionLeft>0</NoOfCashTransactionLeft>
                  <DailyUnLoadLimit>40000</DailyUnLoadLimit>
                  <DailyUnLoadFrequencyLimit>50</DailyUnLoadFrequencyLimit>
                  <AmountUnLoaded>0</AmountUnLoaded>
                  <NoOfUnLoads>0</NoOfUnLoads>
                  <AmountLeftToUnLoad>694.07</AmountLeftToUnLoad>
                  <NoOfUnLoadLeft>50</NoOfUnLoadLeft>
               </LimitInformation>
            </LimitInfo>
         </Ws_Balance_EnquiryResult>
      </Ws_Balance_EnquiryResponse>
   </soap:Body>
</soap:Envelope>