Guides
Guides
  1. Surcharge

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

Type

Name

Req.

Description

SecurityToken

securityToken

R

A unique token that is used to identify a merchant and authenticate the API request.

dateTime

fromDateTime

R

Only includes payments after this date.

dateTime

toDateTime

R

Only includes payments before this date.

SearchFilter[]

filters

O

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

See Supported Search Parameters below.

boolean

countOnly

R

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

int

start

O

Index of the first object to return in the array.

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

int

limit

R

Maximum number of objects to return.

Note: Must be > 0.

string

sort

O

Not currently used.

Return Value

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

Supported Search Parameters
ParameterDescriptionExample of Use
SurchargeInternalIdThe internal identifier for the surcharge record.
<ebiz:SearchFilter>
 <ebiz:FieldName>SurchargeInternalId</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>*************-1234-1234-************</ebiz:FieldValue>
</ebiz:SearchFilter>
AuthCodeThe authorization code associated with the payment.
<ebiz:SearchFilter>
 <ebiz:FieldName>AuthCode</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>284124</ebiz:FieldValue>
</ebiz:SearchFilter>
RefNumThe reference number for the transaction.
<ebiz:SearchFilter>
 <ebiz:FieldName>RefNum</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>3189853127</ebiz:FieldValue>
</ebiz:SearchFilter>
PaymentMethodTypeThe type of payment method used (e.g., Visa, MasterCard).
<ebiz:SearchFilter>
 <ebiz:FieldName>PaymentMethodType</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>Visa</ebiz:FieldValue>
</ebiz:SearchFilter>
DatePaidFilters payments made before or after a specific date.
<ebiz:SearchFilter>
 <ebiz:FieldName>DatePaid</ebiz:FieldName>
 <ebiz:ComparisonOperator>lt</ebiz:ComparisonOperator>
 <ebiz:FieldValue>2020-02-05</ebiz:FieldValue>
</ebiz:SearchFilter>
SurchargePercentageThe percentage value of the applied surcharge.
<ebiz:SearchFilter>
 <ebiz:FieldName>SurchargePercentage</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>1</ebiz:FieldValue>
</ebiz:SearchFilter>
IsAppliedIndicates whether the surcharge was applied (true/false).
<ebiz:SearchFilter>
 <ebiz:FieldName>IsApplied</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>false</ebiz:FieldValue>
</ebiz:SearchFilter>
SurchargeCountryIdThe country where the surcharge was applied.
<ebiz:SearchFilter>
 <ebiz:FieldName>SurchargeCountryId</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>USA</ebiz:FieldValue>
</ebiz:SearchFilter>
SurchargeTypeIdThe type/category of the surcharge applied.
<ebiz:SearchFilter>
 <ebiz:FieldName>SurchargeTypeId</ebiz:FieldName>
 <ebiz:ComparisonOperator>eq</ebiz:ComparisonOperator>
 <ebiz:FieldValue>DailyDiscount</ebiz:FieldValue>
</ebiz:SearchFilter>

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>

Updated 5 months ago