SearchSurchargePayments

Description

The SearchSurchargePayments method retrieves all completed surcharge payments within a specified time range. Additional search filters may be applied to narrow the results.

AuthOnly (pre-authorization) transactions are not returned in the results as they are not considered completed payments until captured.

Syntax

SurchargeSearchResult SearchSurchargePayments(SecurityToken securityToken, dateTime fromDateTime, dateTime toDateTime, SearchFilter[] filters, boolean countOnly, int start, int limit, string sort)

Arguments

TypeNameReq.Description
SecurityToken securityTokenRA unique token that is used to identify a merchant and authenticate the API request.
dateTimefromDateTimeROnly includes payments after this date.
dateTimetoDateTimeROnly includes payments before this date.
SearchFilter[]filtersO

Filters Surcharge objects based on one or more field names, comparison operators, and field values.

See Supported Search Parameters below.

booleancountOnlyRWhether the response should include only the total count of matching objects, excluding the objects themselves.
intstartO

Index of the first object to return in the array.

Note: If the field is omitted, defaults to 0. If included, must be ≥ 0.

intlimitR

Maximum number of objects to return.

Note: Must be > 0.

stringsortONot currently used.

Return Value

TypeDescription
SurchargeSearchResult[]On success, returns a list of matching Surcharge objects. Otherwise, a fault is returned.

Supported Search Parameters
SurchargeInternalId The internal identifier for the surcharge record.
  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>SurchargeInternalId\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>\*\*\*\*\*\*\*\*\*\*\*\*\*-1234-1234-\*\*\*\*\*\*\*\*\*\*\*\*\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>AuthCode</td>
  <td>The authorization code associated with the payment.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>AuthCode\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>284124\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>RefNum</td>
  <td>The reference number for the transaction.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>RefNum\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>3189853127\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>PaymentMethodType</td>
  <td>The type of payment method used (e.g., Visa, MasterCard).</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>PaymentMethodType\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>Visa\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>DatePaid</td>
  <td>Filters payments made before or after a specific date.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>DatePaid\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>lt\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>2020-02-05\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>SurchargePercentage</td>
  <td>The percentage value of the applied surcharge.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>SurchargePercentage\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>1\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>IsApplied</td>
  <td>Indicates whether the surcharge was applied (true/false).</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>IsApplied\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>false\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>SurchargeCountryId</td>
  <td>The country where the surcharge was applied.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>SurchargeCountryId\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>USA\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

<tr>
  <td>SurchargeTypeId</td>
  <td>The type/category of the surcharge applied.</td>

  <td>
    <pre><code>\<ebiz:SearchFilter>
     \<ebiz:FieldName>SurchargeTypeId\</ebiz:FieldName>
     \<ebiz:ComparisonOperator>eq\</ebiz:ComparisonOperator>
     \<ebiz:FieldValue>DailyDiscount\</ebiz:FieldValue>
    \</ebiz:SearchFilter></code></pre>
  </td>
</tr>

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ebiz="http://eBizCharge.ServiceModel.SOAP">
   <soapenv:Header/>
   <soapenv:Body>
      <ebiz:SearchSurchargePayments>
         <ebiz:securityToken>
            <ebiz:SecurityId>******-****-****-****-*********</ebiz:SecurityId>
            <ebiz:UserId>********</ebiz:UserId>
            <ebiz:Password>********</ebiz:Password>
         </ebiz:securityToken>
         <ebiz:fromDateTime>2020-09-04</ebiz:fromDateTime>
         <ebiz:toDateTime>2029-09-04</ebiz:toDateTime>
         <ebiz:filters>
            <ebiz:SearchFilter>
               <ebiz:FieldName>DatePaid</ebiz:FieldName>
               <ebiz:ComparisonOperator>gt</ebiz:ComparisonOperator>
               <ebiz:FieldValue>2025-02-05</ebiz:FieldValue>
            </ebiz:SearchFilter>
         </ebiz:filters>
         <ebiz:countOnly>false</ebiz:countOnly>
         <ebiz:start>0</ebiz:start>
         <ebiz:limit>1000</ebiz:limit>
         <ebiz:sort></ebiz:sort>
      </ebiz:SearchSurchargePayments>
   </soapenv:Body>
</soapenv:Envelope>
// Create the service client
var client = new IeBizServiceClient();

// Create and populate the security token
SecurityToken securityToken = new SecurityToken();
securityToken.UserId = "******";
securityToken.SecurityId = "********-****-****-****-***********";
securityToken.Password = "*******";

// Set up date range
DateTime fromDate = new DateTime(2020, 1, 1);
DateTime toDate = new DateTime(2029, 1, 1);

// Create a search filter object to filter the results
SearchFilter[] filters = new SearchFilter[1];
SearchFilter dateFilter = new SearchFilter();
dateFilter.FieldName = "DatePaid";
dateFilter.ComparisonOperator = "gt";
dateFilter.FieldValue = "2025-02-05";
filters[0] = dateFilter;

// Call the SearchSurchargePayments method
var result = client.SearchSurchargePayments(
  securityToken,
  fromDate,
  toDate,
  filters,       // filters applied
  false,      // countOnly = false
  0,          // start index
  1000,       // limit
  null         // sort order
);
$client = new SoapClient();

// SecurityToken object
$securityToken = [
  "SecurityId" => "**************970-ba92****************",
  "UserId"     => "",
  "Password"   => "",
];

$fromDateTime = "2017-01-01T00:00:00";
$toDateTime   = "2024-12-31T23:59:59";

// Match C# SearchFilter[] filters = new SearchFilter[1];
$filters = [
  "SearchFilter" => [
    [
      "FieldName"           => "SurchargeDate",
      "ComparisonOperator"  => "eq",
      "FieldValue"          => "2017-12-01",
    ]
  ]
];

$params = [
  "securityToken" => $securityToken,
  "fromDateTime"  => $fromDateTime,
  "toDateTime"    => $toDateTime,
  "filters"       => $filters,
  "countOnly"     => false,
  "start"         => 0,
  "limit"         => 10,
  "sort"          => "closed",
];

try {
  $response = $client->SearchSurchargePayments($params);

  $result =
    $response->SearchSurchargePaymentsResult
    ?? $response->SurchargeSearchResult
    ?? null;
  // Extract the Surcharge array from the Surcharges object
  $surchargesObj = $result->Surcharges ?? null;
  $surcharges = $surchargesObj->Surcharge ?? [];

  // Normalize to array if single item
  if (!is_array($surcharges)) {
    $surcharges = [$surcharges];
  }

  foreach ($surcharges as $r) {
    echo "===== Surcharge =====\n";
    echo "SurchargeInternalId: " . ($r->SurchargeInternalId ?? "") . "\n";
    echo "AuthCode: " . ($r->AuthCode ?? "") . "\n";
    echo "RefNum: " . ($r->RefNum ?? "") . "\n";
    echo "Last4: " . ($r->Last4 ?? "") . "\n";
    echo "DateApplied: " . ($r->DateApplied ?? "") . "\n";
    echo "PaymentMethodType: " . ($r->PaymentMethodType ?? "") . "\n";
    echo "TotalSurchargeAmount: " . ($r->TotalSurchargeAmount ?? "") . "\n";
    echo "DatePaid: " . ($r->DatePaid ?? "") . "\n";
    echo "SurchargePercentage: " . ($r->SurchargePercentage ?? "") . "\n";
    echo "TotalPaidAmount: " . ($r->TotalPaidAmount ?? "") . "\n";
    echo "IsApplied: " . ($r->IsApplied ? "true" : "false") . "\n";
    echo "Currency: " . ($r->Currency ?? "") . "\n";
    echo "PaymentSourceId: " . ($r->PaymentSourceId ?? "") . "\n";

    // Parse PaidDocuments
    if (!empty($r->PaidDocuments)) {
      $paidDocs = $r->PaidDocuments->PaidDocument ?? [];

      // Normalize to array if single document
      if (!is_array($paidDocs)) {
          $paidDocs = [$paidDocs];
        }

      echo "PaidDocuments:\n";
      foreach ($paidDocs as $doc) {
          echo "  - CustomerId: " . ($doc->CustomerId ?? "") . "\n";
          echo "    DocumentNumber: " . ($doc->DocumentNumber ?? "") . "\n";
          echo "    DocumentTypeId: " . ($doc->DocumentTypeId ?? "") . "\n";
          echo "    PaidAmount: " . ($doc->PaidAmount ?? "") . "\n";
          echo "    DivisionId: " . ($doc->DivisionId ?? "") . "\n";
        }
    }
    echo "=====================\n\n";
  }

} catch (SoapFault $e) {
  echo "SOAP Error: " . $e->getMessage() . "\n\n";
  echo "Last SOAP Request:\n" . $client->__getLastRequest() . "\n\n";
  echo "Last SOAP Response:\n" . $client->__getLastResponse() . "\n";
}

Example Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <SearchSurchargePaymentsResponse xmlns="http://eBizCharge.ServiceModel.SOAP">
         <SearchSurchargePaymentsResult>
            <Surcharges>
               <Surcharge>
                  <SurchargeInternalId>********-df48-4fb9-8c7e-********</SurchargeInternalId>
                  <AuthCode>065***</AuthCode>
                  <RefNum>*****46641</RefNum>
                  <Last4>**39</Last4>
                  <PaymentMethodType>Visa</PaymentMethodType>
                  <DatePaid>3/30/2023 3:55:40 PM</DatePaid>
                  <TotalSurchargeAmount>0.1500</TotalSurchargeAmount>
                  <PaymentMethodId/>
                  <PaymentSourceId>EBizCharge *******</PaymentSourceId>
                  <SurchargePercentage>2.5000</SurchargePercentage>
                  <TotalPaidAmount>6.1500</TotalPaidAmount>
                  <Currency>USD</Currency>
                  <PaidDocuments>
                     <PaidDocument>
                        <CustomerId>ID0001</CustomerId>
                        <DivisionId/>
                        <DocumentNumber>DOC-321</DocumentNumber>
                        <DocumentInternalId/>
                        <DocumentTypeId>Invoice</DocumentTypeId>
                        <PaidAmount>6.0000</PaidAmount>
                     </PaidDocument>
                  </PaidDocuments>
                  <IsApplied>false</IsApplied>
                  <DateApplied/>
               </Surcharge>
            </Surcharges>
            <Start>0</Start>
            <Limit>1</Limit>
            <Count>1</Count>
         </SearchSurchargePaymentsResult>
      </SearchSurchargePaymentsResponse>
   </s:Body>
</s:Envelope>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <s:Fault>
         <faultcode>s:Client</faultcode>
         <faultstring xml:lang="en-US">Error: Not Found</faultstring>
      </s:Fault>
   </s:Body>
</s:Envelope>