6 Fee Maintenance (SOAP Web Services)

This section describes the options for viewing and maintaining fees for your program if you are using the Thredd SOAP Web Services. For more information on the Thredd API described in this section, see the Web Services Guide (SOAP).

If you are using the Thredd REST-based Cards API, please read the section Fee Maintenance (Cards API).

6.1 Managing Fee Groups

You can use the Thredd API to query and update the fee groups linked to a card and to apply additional fees to a card.

6.1.1 Listing Fee Groups

You can use the List Groups web service (Ws_list_group) to list the codes and descriptions of all groups of a certain type (e.g. Fee Groups). You can specify one the following <GroupType> values related to fees:

2 = Authorisation Fee Groups

3 = Recurring/Scheduled Fee Groups

4 = API Usage (Web Service) Fee Groups

See the example below: (only relevant fields are shown)

Request

Copy
XML
<soapenv:Body>
      <hyp:Ws_List_Group>
         <hyp:WSID>1234</hyp:WSID>
         <hyp:IssCode>ABCD</hyp:IssCode>
         <hyp:GroupType>2</hyp:GroupType>
      </hyp:Ws_List_Group>
   </soapenv:Body>

Notes

Authorisation Fee Group = 2:

Copy
         <hyp:GroupType>2</hyp:GroupType>

Response

Copy
XML
          <Ws_List_GroupResult>
            <WSID>1234</WSID>
            <IssCode>ABCD</IssCode>
            <GroupType>1</GroupType>
                        <ActionCode>000</ActionCode>
            <GroupInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH1</GroupCode>
                  <GroupDesc>GROUP Auth 1</GroupDesc>
               </GroupListInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH2</GroupCode>
                  <GroupDesc> GROUP Auth 2</GroupDesc>
               </GroupListInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH3</GroupCode>
                  <GroupDesc>GROUP Auth 3</GroupDesc>
               </GroupListInfo>
            </GroupInfo>
         </Ws_List_GroupResult>

Notes

Authorisation Fee Groups set up on Thredd:

Copy
            <GroupInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH1</GroupCode>
                  <GroupDesc>GROUP Auth 1</GroupDesc>
               </GroupListInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH2</GroupCode>
                  <GroupDesc> GROUP Auth 2</GroupDesc>
               </GroupListInfo>
               <GroupListInfo>
                  <GroupCode>GRPAUTH3</GroupCode>
                  <GroupDesc>GROUP Auth 3</GroupDesc>
               </GroupListInfo>

If you do not specify a <GroupType> value in the request or request a type that does not exist, this will return an error.

6.1.2 Linking Cards to Fee Groups

When creating a card using the Create Card web service (Ws_CreateCard), if you do not specify fee groups then the default groups for the card product associated with the card are used. Alternatively, you can link the card to specific fee groups at the time when the card is created.

If the card is being loaded for the first time and you do not want to apply your normal card load fee, you can use the <FeeWaiver> parameter to exempt the card from the web services load fee.

See the example below: (only relevant fields are shown)

Request

Copy
XML
<hyp:Ws_CreateCard>
      <hyp:WSID>1234</hyp:WSID>
      <hyp:IssCode>ABCD</hyp:IssCode>
       ……
<hyp:LimitsGroup>DF - 01</hyp:LimitsGroup>
      <hyp:MCCGroup></hyp:MCCGroup>
      <hyp:PERMSGroup></hyp:PERMSGroup>
        ………
<hyp: FeeGroup>GROUP1</hyp: FeeGroup>
<hyp:SchedFeeGroup>GROUP1</hyp:SchedFeeGroup>
<hyp:WSFeeGroup>GROUP2</hyp:WSFeeGroup>
<hyp:FxGroup>GROUP4</hyp:FxGroup>
    ….
<hyp:FeeWaiver></hyp:FeeWaiver>

Notes

Specify the fee groups to link to this new card:

Copy
<hyp: FeeGroup>GROUP1</hyp: FeeGroup>
<hyp:SchedFeeGroup>GROUP1</hyp:SchedFeeGroup>
<hyp:WSFeeGroup>GROUP2</hyp:WSFeeGroup>
Copy
<hyp:FeeWaiver></hyp:FeeWaiver>

Response

Copy
XML
<Ws_CreateCardResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
         <Ws_CreateCardResult>
            <WSID>1234</WSID>
            <IssCode>ABCD</IssCode>
            <TxnCode>10</TxnCode>
            <PublicToken>123456789</PublicToken>
            …
            <LocDate>2021-01-01</LocDate>
            <LocTime>120000</LocTime>
            <ItemID>1234</ItemID>
            <ClientCode>0</ClientCode>
            <SysDate>2021-01-01</SysDate>
            <ActionCode>000</ActionCode>
            <LoadValue>10</LoadValue>
            <IsLive>false</IsLive>
            <ExpDate>03/22</ExpDate>
            <CVV>123</CVV>
            <MaskedPAN>987654******0123</MaskedPAN>
         </Ws_CreateCardResult>
      </Ws_CreateCardResponse>

6.1.3 Changing the Fees Groups Linked to a Card

You can use the Change Card Groups web service (Ws_Card_Change_Groups) to change one or more of the usage or fee groups for a specific card.

You must enter the Thredd code of an existing a Fee group, as defined in your Product Setup Form (PSF).

See the example below: (only relevant fields are shown)

Request

Copy
XML
<soapenv:Body>
      <hyp:Ws_Card_Change_Groups>
         <hyp:WSID>1234</hyp:WSID>
         <hyp:IssCode>ABCD</hyp:IssCode>
         <hyp:PAN></hyp:PAN>
         <hyp:PublicToken>123456789</hyp:PublicToken>
          ….
         <hyp:LimitsGroup> </hyp:LimitsGroup>
         <hyp:MCCGroup></hyp:MCCGroup>
         <hyp:PERMSGroup></hyp:PERMSGroup>
         <hyp:FeeGroup>GRPAUTH2</hyp:FeeGroup>
         <hyp:SchedFeeGroup></hyp:SchedFeeGroup>
         <hyp:LinkageGroup></hyp:LinkageGroup>
         <hyp:AuthCalendarGroup></hyp:AuthCalendarGroup>
         <hyp:FXGroup></hyp:FXGroup>         
    <hyp:PaymentTokenUsageGroup></hyp:PaymentTokenUsageGroup>
      </hyp:Ws_Card_Change_Groups>
   </soapenv:Body>

Response

Copy
XML
 <soap:Body>
      <Ws_Card_Change_GroupsResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
         <Ws_Card_Change_GroupsResult>
            <WSID>1234</WSID>
            <IssCode>ABCD</IssCode>
            <ActionCode>000</ActionCode>
        ….
            <LocDate>2021-01-01</LocDate>
            <LocTime>120000</LocTime>
            <SysDate>2021-01-01</SysDate>
            <PublicToken>123456789</PublicToken>
         </Ws_Card_Change_GroupsResult>
      </Ws_Card_Change_GroupsResponse>
   </soap:Body>

6.2 Viewing and Applying Card Fees

A number of web services are available for querying and applying fees to a specific card.

6.2.1 Querying Pending Fees

You can use Card List Pending Fees (Ws_List_Pending_Fees) to return details of pending fees that relate to a specific card. Pending fees are any charges that could not be taken from the card due to an insufficient available balance.

For example, if you charge a card activation fee and the card is activated before funds have been loaded, this will generate a pending fee. The pending fee is taken when the card is loaded (i.e., when sufficient funds are available).

See the example below: (only relevant fields are shown)

Request

Copy
XML
      <hyp:Ws_List_Pending_Fees>
         <hyp:WSID>123456789</hyp:WSID>
         <hyp:IssCode>ABCD</hyp:IssCode>
         <hyp:PAN></hyp:PAN>
         <hyp:PublicToken>123456789</hyp:PublicToken>
         <hyp:FeeProcessingCode></hyp:FeeProcessingCode>
      </hyp:Ws_List_Pending_Fees>

Notes

Specifies the card you are querying:

Copy
         <hyp:PublicToken>123456789</hyp:PublicToken>

Response

Copy
XML
      <Ws_List_Pending_FeesResponse 
         <Ws_List_Pending_FeesResult>
            <WSID>123456789</WSID>
            <ActionCode>000</ActionCode>
         <Fees>
               <Fee>
                  <PublicToken>123456789</PublicToken>
                  <PostDate>2021-03-14</PostDate>
                  <TransDate>2021-03-14</TransDate>
                  <ProcCode>84</ProcCode>
                  <ActualAmt>4.99</ActualAmt>
                  <AmtTaken>4</AmtTaken>
                  <RemainingAmt>.99</RemainingAmt>
                  <Description>Load fee</Description>
                  <PartialAllowed>true</PartialAllowed>
                  <Collected>true</Collected>
                  <PendingFeesEnabled>true</PendingFeesEnabled>
               </Fee>
               <Fee>
                  <PublicToken>123456789</PublicToken>
                  <PostDate>2021-03-14</PostDate>
                  <TransDate>2021-03-14</TransDate>
                  <ProcCode>82</ProcCode>
                  <ActualAmt>2</ActualAmt>
                  <AmtTaken>0</AmtTaken>
                  <RemainingAmt>2</RemainingAmt>
                  <Description>Card Issue Fee</Description>
                  <PartialAllowed>false</PartialAllowed>
                  <Collected>true</Collected>
                  <PendingFeesEnabled>true</PendingFeesEnabled>
               </Fee>
            </Fees>

6.2.2 Querying Card Transaction Fees

You can use the Card Statement web service <Ws_Card_Statement> to query details of card transaction fees over a defined period.

We recommend you use the EHI data feed for viewing details of your fees. Using web services to query card fees may incur additional charges. Please ensure you abide by the Thredd Fair Usage Policy for web services (refer to your Letter of Intent or Contract).

See the example below: (only relevant fields are shown)

Request

Copy
XML
      <hyp:Ws_Card_Statement>
         <hyp:WSID>1234</hyp:WSID>
         <hyp:IssCode>ABCD</hyp:IssCode>
         <hyp:TxnCode>5</hyp:TxnCode>
         ….
         <hyp:PublicToken>123456789</hyp:PublicToken>
         ….
         <hyp:TxnFilter>5</hyp:TxnFilter>
         <hyp:StartDate> 2020-01-15</hyp:StartDate>
         <hyp:EndDate>2021-01-15</hyp:EndDate>
         <hyp:NumTxn></hyp:NumTxn>
         <hyp:DataSrc>0</hyp:DataSrc>
      </hyp:Ws_Card_Statement>

Response

Copy
XML
<Ws_Card_StatementResult>
            <WSID>1234</WSID>
            <IssCode>ABCD</IssCode>
            <TxnCode>5</TxnCode>
            …
            <PublicToken>123456</PublicToken>
            ..
            <StartBal>10</StartBal>
            <EndBal>0</EndBal>
            <TxnFilter>5</TxnFilter>
            <StartDate>2020-01-15</StartDate>
            <EndDate>2021-01-15</EndDate>
            <NumTxn>2</NumTxn>
            <ItemSrc>2</ItemSrc>
            <CurBill>GBP</CurBill>
            <AvlBal>0</AvlBal>
            <BlkAmt>0</BlkAmt>
            ….
            <Transactions>
               <Transaction1>
                  <TxnDate>2021-02-01</TxnDate>
                  <PostDate>2021-02-01</PostDate>
                  <AmtBill>10</AmtBill>
                  <AmtTxn>10</AmtTxn>
             …
                  <Description> Unload: UnLoad</Description>
                  ..
                  <TransactionType>U</TransactionType>
                  <StatusCode>S</StatusCode>
                  <StatusDesc> Settled: -</StatusDesc>                  
                  …
          <FeeId>0</FeeId>
                  <FixedFee>0.05</FixedFee>
                  <RateFee>0</RateFee>
                  <FxPdg>0</FxPdg>
                  …
                  <ProcCode>230000</ProcCode>
               </Transaction1>
               <Transaction2>
                  <TxnDate>2021-01-15</TxnDate>
                  <PostDate>2021-01-15</PostDate>
                  <AmtBill>10</AmtBill>
                  <AmtTxn>10</AmtTxn>
                  <BillConvRate>1</BillConvRate>
                  <DebOrCred>1</DebOrCred>
                  <TerminalId/>
                  <Description> Load: Web services load </Description>
                  <RRN/>
                  <CurTxn>GBP</CurTxn>
                  <ItemId>1233</ItemId>
                  <AvlBal>10</AvlBal>
                  <BlkAmt>0</BlkAmt>
                  <TransactionType>L</TransactionType>
                  <StatusCode>S</StatusCode>
                  <StatusDesc>Settled :  -</StatusDesc>
                  ..
                  <FeeId>0</FeeId>
                  <WSID>1234</WSID>
                  <FixedFee>0.05</FixedFee>
                  <RateFee>0</RateFee>
                  <FxPdg>0</FxPdg>
                  ..
                  <ProcCode>220000</ProcCode>
               </Transaction2>
            </Transactions>

Notes

The Fee amount =

Copy
                  <FixedFee>0.05</FixedFee>
                  <RateFee>0</RateFee>

You can use the description and processing code (DE003) to determine the source of the fee:

Copy
                  <Description> Load: Web services load </Description>
Copy
                  <ProcCode>220000</ProcCode>

For details of the processing codes, see Appendix 1: Processing Codes (DE003).

6.2.3 Applying Fees to a Card

You can use the Generic Fees web service <Ws_Generic_Fees> to apply a one-off fee charge with a comment to a particular card.

You need an associated processing code (<ProcCode>) for applying the fee. You can use the default amount configured for the web service fee group or specify an amount using the <Fee> parameter and add a comment to clarify the purpose of the fee (e.g., Administration Fee or Chargeback fee).

We recommend you use processing code 83 (administration fee) when applying ad-hoc fees to a card.

You will first need to configure the details of your Web Service Group in the PSF, and this must then be set up by your implementation manager. See Web Service Fees

Request

Copy
XML
      <hyp:Ws_Generic_Fees>
         <hyp:WSID>1234</hyp:WSID>
         <hyp:IssCode>ABCD</hyp:IssCode>
         <hyp:PAN></hyp:PAN>
         <hyp:PublicToken>123456789</hyp:PublicToken>
         <hyp:ProcCode>83</hyp:ProcCode>
         <hyp:Comment>Admin fee</hyp:Comment>
         <hyp:LocDate>2013-01-01</hyp:LocDate>
         <hyp:LocTime>120000</hyp:LocTime>
         <hyp:Fee>0.0</hyp:Fee>
      </hyp:Ws_Generic_Fees>

Notes

Enter the two-digit Thredd processing code and add a description to the fee:

Copy
         <hyp:ProcCode>83</hyp:ProcCode>
         <hyp:Comment>Admin fee</hyp:Comment>
Copy
         <hyp:Fee>0.0</hyp:Fee>

For details of the processing codes, see Appendix 2: Fee Processing Codes.