Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Information Lookup Service Transactions

The Information Lookup Service (ILS) operation allows you to run a report through the API over a date range you specify to return data on Authorizations, Settlements, Credits, and Chargebacks processed through a merchant account. You can use the type element to combine one or more transaction types in a single request. 

This chapter describes how to process the ILS operation via the Paysafe Web Service.

•    The ILS operation accepts an ilsLookupRequestV1 document object.

•    The ILS operation returns an ilsLookupResponseV1 response.

.NET example

To build the .NET example:

  1. Create a new project.

  2. Add a Web Reference.

  3. Enter the WSDL URL and click the Add Reference button.

  4. The Web client is now built.

  5. Build the request and process response.

Building ILS requests

ILS requests require the ilsLookupRequestV1 document object. This section describes the structure of an ilsLookupRequestV1 and how to construct one. 

ILS – C#

The following is an ILS example in C#:

//Prepare the call to the Credit Card Web Service



ILSLookupRequestV1 ilsLookupRequest = new ILSLookupRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";







DateV1 startDate = new DateV1();



startDate.year = 2008;



startDate.month = 11;



startDate.day = 3;



startDate.hour = 0;



startDate.minute = 0;



startDate.second = 0;







DateV1 endDate = new DateV1();



endDate.year = 2008;



endDate.month = 11;



endDate.day = 3;



endDate.hour = 14;



endDate.minute = 40;



endDate.second = 59;







RequestTypeV1[] txnTypes = new RequestTypeV1[1];



txnTypes[0] = RequestTypeV1.settlements;







IlsLookupRequestV1 req = new IlsLookupRequestV1();



req.merchantAccount = merchantAccount;



req.startDate = startDate;



req.endDate = endDate;



req.type = txnTypes;







System.Console.WriteLine("Sending request...");







IlsServiceV1 ilsService = new IlsServiceV1();



IlsLookupResponseV1 response = null;







response = ilsService.ilsLookup( req );







System.Console.WriteLine("Response received: ");



String responseTxt = "";







if( response != null )



{



   responseTxt += "Decision: " + response.decision + Environment.NewLine;



   responseTxt += "Description: " + response.description + Environment.NewLine;



   



   if( response.decision == DecisionV1.ACCEPTED )



   {



      responseTxt += "Authorizations: " + response.transactions.authorizations + Environment.NewLine;



      responseTxt += "Settlements: " + response.transactions.settlements + Environment.NewLine;



      responseTxt += "Chargebacks: " + response.transactions.chargebacks + Environment.NewLine;



      responseTxt += "Credits: " + response.transactions.credits + Environment.NewLine;



   }



}







System.Console.WriteLine( responseTxt );

ilsLookupRequestV1 schema

An ilsLookupRequestV1 has the following structure:

ilsLookupRequestV1 elements

The ilsLookupRequestV1 document object contains the following elements:

Element Child Element Required Type Description

merchantAccount

accountNum

Yes

String

Max = 10

This is the merchant account number.
 

storeID

Yes

String

Max = 80

This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
 

storePwd

Yes

String

Max = 20

This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.

startDate

year

Yes

Int

Max = 9999

This is the year set for the search start.
 

month

Yes

Int

Min = 1

Max = 12

This is the month set for the search start.
 

day

Yes

Int

Min = 1

Max = 31

This is the day set for the search start.
 

hour

Yes

Int

Min = 0

Max = 23

This is the hour set for the search start.
 

minute

Yes

Int

Min = 0

Max = 59

This is the minute set for the search start.
 

second

Yes

Int

Min = 0

Max = 59

This is the second set for the search start.

endDate

year

Yes

Int

Max = 9999

This is the year set for the search end.
 

month

Yes

Int

Min = 1

Max = 12

This is the month set for the search end.
 

day

Yes

Int

Min = 1

Max = 31

This is the day set for the search end.
 

hour

Yes

Int

Min = 0

Max = 23

This is the hour set for the search end.
 

minute

Yes

Int

Min = 0

Max = 59

This is the minute set for the search end.
 

second

Yes

Int

Min = 0

Max = 59

This is the second set for the search end.

type

  

Yes

Enumeration

This is the type of transaction for which you are looking for data. Possible values are:

•    authorizations

•    settlements

•    credits

•    chargebacks

•    dd-charge

•    dd-credit

•    dd-charge-bacs (returns mandateReference element)

•    dd-credit-bacs (returns mandateReference element)

•    dd-mandate-bacs (returns mandateReference and effectiveDate elements)

ccOptions

  

Optional

Enumeration

For internal use only.

ddOptions

  

Optional

    
 

dateType

Optional

Enumeration

This specifies the nature of the transaction status that will searched for.

•    initiation – The search will be conducted on all checks that were presented during the time period specified. If the dateType is not specified, this is the default setting.

•    status_change – The search will be conducted on all checks whose status changed during the time period specified.
 

status

Optional

Enumeration

The lookup request will return only those transactions with the status specified here.

When combined with a status_change element, only those records that had the specified status during that date range are returned.

If this element is not specified then transactions of all statuses are returned.

Possible values are:

•    Presented

•    Represented

•    Returned

•    Pending Customer Approval

•    Pending

•    Active

•    Declined

•    Cancelled

•    Failed

•    Cleared

The maximum range for an ILS request is 24 hours.

Processing the response

The following is an example of a typical ilsLookupResponseV1 for a successful transaction.

<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1">



   <decision>ACCEPTED</decision>



   <description/>



   <merchantAccount>10000400036</merchantAccount>



   <currency>USD</currency>



   <startDate>



      <year>2011</year>



      <month>2</month>



      <day>5</day>



      <hour>0</hour>



      <minute>0</minute>



      <second>0</second>



   </startDate>



   <endDate>



      <year>2011</year>



      <month>3</month>



      <day>5</day>



      <hour>23</hour>



      <minute>59</minute>



      <second>59</second>



   </endDate>



   <txnType>



      <code>authorizations</code>



      <count>2</count>



   </txnType>



   <txnType>



   <code>settlements</code>



      <count>2</count>



   </txnType>



   <txnType>



      <code>credits</code>



      <count>1</count>



   </txnType>



   <txnType>



      <code>chargebacks</code>



      <count>1</count>



   </txnType>



   <transactions childFma='1000201930'>



      <authorizations>100052493|FS|2011-02-05 09:57:54|test 123|111.65



      </authorizations>



      <settlements>100052493|C|2011-02-05 09:57:55|test 123|111.65



      </settlements>



      <credits>116883988|C|2011-03-02 15:17:09|test 123|5.0|102318569|USD

      </credits>



      <chargebacks>368237|100052493|test 123|test 123|1111|2011-02

      -05|111.65|USD|111.65|30|40003610000160100052493|100000|1||2008-02-05



      </chargebacks>



   </transactions>



<transactions childFma='1000201931'>



      <authorizations>100052493|FS|2011-02-05 09:57:54|test 123|88.00



      </authorizations>



      <settlements>100052493|C|2011-02-05 09:57:55|test 123|88.00



      </settlements>



   </transactions>



</ilsLookupResponseV1>

The following is an example of a typical ilsLookupResponseV1 for a rejected transaction. In this example, an invalid merchant ID or password was submitted.

<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1">



<decision>REJECTED</decision>



<description>Invalid Credentials</description>



</ilsLookupResponseV1>

ilsLookupResponseV1 schema

An ilsLookupResponseV1 has the following structure:

The following elements are relevant for an ilsLookupResponseV1:

Element Child Element Required Type Description

decision

  

Yes

Enumeration

This is the status of the transaction. One of the following is returned:

•    Accepted – the transaction was processed.

•    Error – the transaction was attempted, but failed for some reason.

•    Rejected – the request was rejected, e.g., due to invalid merchant credentials.

description

  

Yes

String

Max = 1024

If the decision returned is Error or Rejected, this is a description of the error.

merchantAccount

  

Yes

String

Max = 10

This is the merchant account number.

currency

  

Yes

String

Length = 3

This is the currency of the merchant account.

startDate

year

Yes

Int

Max = 9999

This is the year set for the search start date.
 

month

Yes

Int

Min = 1

Max = 12

This is the month set for the search start date.
 

day

Yes

Int

Min = 1

Max = 31

This is the day set for the search start date.
 

hour

Yes

Int

Min = 0

Max = 23

This is the hour set for the search start date.
 

minute

Yes

Int

Min = 0

Max = 59

This is the minute set for the search start date.
 

second

Yes

Int

Min = 0

Max = 59

This is the second set for the search start date.

endDate

year

Yes

Int

Max = 9999

This is the year set for the search end date.
 

month

Yes

Int

Min = 1

Max = 12

This is the month set for the search end date.
 

day

Yes

Int

Min = 1

Max = 31

This is the day set for the search end date.
 

hour

Yes

Int

Min = 0

Max = 23

This is the hour set for the search end date.
 

minute

Yes

Int

Min = 0

Max = 59

This is the minute set for the search end date.
 

second

Yes

Int

Min = 0

Max = 59

This is the second set for the search end date.

txnType

code

Yes

String

This is the type of transaction for which you searched for data. Possible values are:

•    authorizations

•    settlements

•    credits

•    chargebacks

•    dd-charge

•    dd-credit

•    dd-charge-bacs (includes mandateReference element)

•    dd-credit-bacs (includes mandateReference element)

•    dd-mandate-bacs (includes mandateReference and effectiveDate elements)
 

count

Yes

Int

This is the number of the transaction type returned in the code element above. Each code element returned has its own count.

transactions

  

Optional
 

Attribute of transactions
 

childFma

Conditional

String

Max = 10

This is the child merchant account number, and provided only if the account provided for the merchantAccount element is a master account.
   
 

authorizations

Optional

String

Each instance of authorizations contains further details. 
 

settlements

Optional

String

Each instance of settlements contains further details.
 

credits

Optional

String

Each instance of credits contains further details. 
 

chargebacks

Optional

String

Each instance of chargebacks contains further details. 
 

dd-charge

Optional

String

Each instance of dd-charge, dd-credit, dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs contains further details. 
 

dd-credit

Optional

String
 

dd-charge-bacs

Optional

String
 

dd-credit-bacs

Optional

String
 

dd-mandate-bacs

Optional

String

Response element contents

Paysafe may without warning, when necessary, add additional detail elements to each of the transaction response types documented below (authorizations, settlements, credits, and chargebacks).

These additional detail elements will be added at the end of the current pipe-separated element list, as in the example below.

<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1">



…



   <transactions childFma='1000201930'>



      <authorizations>100052493|FS|2011-02-05 09:57:54|test 123|

      111.65|added element|added element



      </authorizations>



      <settlements>100052493|C|2011-02-05 09:57:55|test 123



      |111.65|added element|added element



      </settlements>



      <credits>116883988|C|2011-03-02 15:17:09|test 123|5.0|102318569|

      USD|added element|added element

      </credits>



      <chargebacks>368237|100052493|test 123|test 123|1111|2011-02-05

      |111.65|USD|111.65|30|40003610000160100052493|100000|1||

      2008-02-05|added element



      </chargebacks>



…



</ilsLookupResponseV1>

It is the merchant’s responsibility to ensure that their integration for the ilsLookupRequestV1 is not adversely affected by the addition of extra detail elements by Paysafe

Authorizations response details

The following details may returned for authorizations:

Parameter Description

Record Sequence

This is the confirmation number assigned by Paysafe to the transaction.

Authorization Status

This is the status of the Authorization. Possible values are:

•    A – Authorized

•    FS – Fully Settled

•    AS – Partially Settled

Transaction Date/Time

This is the date and time the Authorization was processed.

Merchant Transaction ID

This is the transaction ID assigned by the merchant to the Authorization.

Amount

This is the amount of the Authorization.

Settlements response details

The following details may be returned for settlements:

Parameter Description

Record Sequence

This is the confirmation number assigned by Paysafe to the transaction.

Settlement Status

This is the current status of the Settlement transaction. Possible values are:

•    B – Batched

•    E – Error

•    P – Pending

•    C – Complete

•    K – Cancelled

•    HO – Hold

•    DE – Declined

•    MI – Manual

Transaction Date/Time

This is the date and time the Settlement was processed.

Merchant Transaction ID

This is the transaction ID assigned by the merchant to the Settlement.

Amount

This is the amount of the Settlement.

Credits response details

The following details may be returned for credits:

Parameter Description

Record Sequence

This is the confirmation number assigned by Paysafe to the transaction.

Settlement Status

This is the current status of the Settlement transaction. Possible values are:

•    B – Batched

•    E – Error

•    P – Pending

•    C – Complete

•    K – Cancelled

•    HO – Hold

•    DE – Declined

•    MI – Manual

Transaction Date/Time

This is the date and time the Settlement was processed.

Merchant Transaction ID

This is the transaction ID assigned by the merchant to the Settlement.

Amount

This is the amount of the Settlement.

Chargebacks response details

The following details may be returned for chargebacks:

Parameter Description

Chargeback ID

This is the Record ID in our Dispute Management system. Each chargeback has a unique Record ID to identify it.

Authorization Transaction ID

This is the transaction ID assigned by Paysafe to the original Authorization.

Authorization Merchant Transaction ID

This is the transaction ID assigned by the merchant to the original Authorization.

Settlement Merchant Transaction ID

This is the transaction ID assigned by the merchant to the Settlement that was charged back.

Card Ending

This is the last 4 digits of the credit card used for the original Authorization.

Original Settlement Date

This is the date of the Settlement of the original Authorization.

Format = yyyy-mm-dd

Original Settlement Amount

This is the amount that was settled against the original Authorization.

Currency Code

This is the currency of the merchant account.

Chargeback Amount

This is the amount that is being charged back against the Settlement.

Reason Code

This is the reason the transaction was charged back. 

ARN

This is the Acquirer’s Reference Number, a unique identification reference number assigned to each settlement transaction by the acquirer.

Original Authorization Code

This is the authorization code assigned by the issuing bank and returned by Paysafe if the transaction was process via the Direct Payment protocol.

CBTY Code

This is the type of chargeback. Possible values are:

•    1 – Chargeback

•    2 – Chargeback Reversal

•    C – Risk Only Notice

•    D – Denied/Lost Representment

•    RET – Retrieval Request

Disputed Flag

This flag indicates whether a transaction is being disputed. Possible values are:

•    Null

•    Yes

FMA Posting Date

This is the date the chargeback was posted to the merchant account.

Format = yyyy-mm-dd

Direct Debit response details

The following details may be returned for Direct Debit transactions:

Parameter Description

Echeck ID

This is the confirmation number assigned by Paysafe to the transaction.

Echeck Status

This is the current status of the Direct Debit transaction. Possible values are:

•    AP – Approved mandate

•    C – Complete batch

•    CL – Cleared transaction

•    DE – Declined

•    E – Error batch

•    F – Failed

•    PR1 – Presented 1

•    PR2 – Presented 2

•    RE – Rejected

•    REF – Rejected final

•    RF – Refunded

•    RV – Reversed

•    W – Waiting to be batched

•    X – Cancelled

Presentation Date

This is the date and time the transaction was processed.

Merchant Transaction ID

This is the transaction ID assigned by the merchant to the transaction.

Amount

This is the amount of the transaction. This value will be 0.0 when the txnType was set to dd-mandate-bacs.

Filtered Status

When the dateType child element of ddOptions is set to “initiation” (default), this value is the same as the Echeck Status value, above in this table.

When the dateType child element of ddOptions is set to “status_change”, this is the status that was used for the search.

Here are the statuses returned in each of the search scenarios.

Presented

•    C

Represented

•    PR1

•    PR2

Returned

•    RE

•    REF

Latest Status Update Time

This is the date and time of the latest status update.

Return Code

This is the return code if the mandate or transaction has been returned by the banking network.

NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.

Bank Reference

This is the full reference used to send to the banking network.

•    For dd-mandate-bacs, this will be the 10-character mandateReference.

•    For dd-charge-bacs, this will be 18 characters comprising the 10-character mandateReference and 8 characters for the echeck ID of the transaction (charge).

NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.

Effective Date

This is returned for dd-mandate-bacs requests only. It is the date the mandate will become active with the bank. Transactions may not be requested against this mandate before the effective date. Once the mandate becomes active, the value returned for this field will be null.

NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.

Reason codes

Chargeback reason codes

One of the following chargeback reason codes may be returned with a chargebacks response:

Card Brand Code Description

MC

01

Requested Transaction Data Not Received

MC

02

Requested item illegible

MC

07

Warning Bulletin File

MC

08

Requested/Required Authorization Not Obtained

MC

12

Account Number Not on File

VI

30

Services Not Provided or Merchandise Not Received

MC

31

Transaction Amount Differs

MC

34

Duplicate Processing

MC

35

Card Not Valid or Expired

MC

37

Fraudulent Mail/Phone Order Transaction

MC

40

Fraudulent Processing of Transaction

MC

41

Canceled Recurring Transaction

VI

41

Canceled Recurring Transaction

MC

42

Late Presentment

MC

47

Exceeds Floor Limit, Not Authorized, and Fraudulent Transaction

MC

49

Questionable Merchant Activity

MC

50

Credit Posted as a Debit

MC

53

Cardholder Dispute Defective/Not as Described

VI

53

Not as Described/Defective Merchandise

MC

54

Cardholder Dispute - Not Elsewhere classified (US Only)

MC

55

Non-Receipt of Merchandise

VI

57

Fraudulent Multiple Transactions

MC

59

Services Not Rendered

MC

60

Credit Not Processed

VI

60

Requested Copy Illegible

MC

62

Counterfeit Transaction Magnetic Stripe POS Fraud

VI

62

Counterfeit Transaction

MC

63

Cardholder Does Not Recognize – Potential Fraud

VI

71

Authorization Request Declined/Declined Authorization

VI

72

No Authorization / Transaction Exceeds Floor Limit

VI

73

Expired Card

VI

74

Late Presentment

VI

75

Cardholder Does Not Recognize the Transaction

VI

76

Incorrect Transaction Code

VI

77

Non-Matching Account Number

VI

79

Requested Transaction Information Not Received

VI

80

Incorrect transaction amount or account number

VI

81

Fraudulent transaction – Card Present Environment

VI

82

Duplicate Processing

VI

83

Fraudulent Transaction – Card Absent Environment

VI

85

Credit Not Processed

VI

86

Paid by Other Means

Retrieval request reason codes

One of the following retrieval request reason codes may be returned with a chargebacks response:

Card Brand Code Description

MC

05

Chargeback Support – Card Holder Does Not Agree with Amount Billed

MC

21

Cardholder Inquiry – Does Not Recognize Transaction (Merchant Name, City, State or Date)

MC

22

Cardholder Inquiry – Disagrees With Billing

MC

23

Cardholder Inquiry – Needs for Personal Records

MC

24

Cardholder Inquiry – No Reason Code

VI

28

Cardholder Requests Copy Bearing Signature

VI

29

Request for T&E Documents

VI

30

Cardholder Dispute, Cardholder Request Draft

VI

33

Legal Process or Fraud Analysis

VI

34

Repeat Request for Copy

MC

41

Legal/Fraud Analysis – Signature Verification

MC

42

Potential Chargeback or Compliance Documentation

MC

43

Legal/Fraud – Imprint Verification

Discover chargeback and retrieval request reason codes

One of the following chargeback or retrieval request reason codes may be returned with a chargebacks response:

Code Description

AL

Cardholder challenges the validity of an airline card sale.

AP

Cardholder challenges the validity of multiple recurring payments card sales after expiration or cancellation of the recurring payments plan agreement.

AW

Incorrect transaction amount or account number/transaction amount differs.

CA

Cardholder challenges the validity of a cash advance or cash over transaction, other than a Discover ATM transaction.

CD

Cardholder challenges the validity of a card transaction because the transaction should have resulted in a credit rather than a card sale.

RG

Cardholder challenges the validity of a card sale due to non-receipt of goods and/or services.

UA11

Swiped card transaction – No cardholder signature obtained.

UA12

Swiped card transaction – Invalid cardholder signature obtained.

UA18

Swiped card transaction – Illegible copy of transaction receipt.

UA21

Keyed card transaction – No cardholder signature obtained.

UA22

Keyed card transaction – Invalid cardholder signature obtained.

UA23

Keyed card transaction – Invalid card imprint.

UA28

Keyed card transaction – Illegible copy of transaction documentation.

RN1, RN2

Cardholder alleges that an expected credit from the merchant was not received or was insufficient in amount.

DP

Cardholder alleges that a single card sale was posted more than once to the cardholder’s account.

RM

Cardholder challenges the validity of a card sale because the goods or services delivered by the merchant were not of the quality or condition agreed upon.

NA

Issuer disputes a card sale because the merchant did not obtain a positive authorization response for the amount of the card transaction that is subject to dispute, as represented in sales data.

UA01

Cardholder or issuer challenges the validity of a card sale because no authorization request was attempted by the merchant.

CR

Cardholder challenges the validity of a card transaction because the cardholder cancelled the underlying reservation with the merchant.

NC

Cardholder challenges the validity of a card sale and no other reason code applies.

DA

Issuer challenges the validity of a card sale because the merchant received a declined authorization response and the issuer cannot collect the card sale amount from the cardholder.

EX

Cardholder or issuer challenges the validity of a card sale because the card had expired on or before the card transaction date and the merchant did not obtain a positive authorization response.

IC

Cardholder or issuer disputes a card sale because the transaction documentation received in response to a ticket retrieval request is either illegible or is missing a valid, legible card imprint (if required).

IN

Issuer disputes a card transaction because the card number provided by the merchant is not valid.

IS

Cardholder or issuer disputes a card sale because transaction documentation received in response to a ticket retrieval request does not include a valid, legible cardholder signature where required for the card transaction.

LP

Cardholder or issuer disputes a card sale because the acquirer or merchant submitted sales data for the card sale more than 30 calendar days after the authorization request and the card sale was not for a delayed delivery card sale.

SV

Cardholder or issuer disputes a prepaid gift card transaction because the merchant did not obtain a positive authorization response for the amount of the card sale subject to dispute.

TF

Discover initiates a chargeback of a card transaction because the acquirer or merchant did not comply with the applicable operating regulations.

UA10

Request transaction receipt for swiped card transaction.

UA20

Request transaction documentation for keyed card transaction.

UA30

Request transaction documentation for card not present card transaction.

UA31

Card not present card transaction – Invalid proof of delivery obtained by acquirer or merchant.

UA38

Card Not present card transaction – Illegible copy of transaction documentation.

UA02

Cardholder or issuer challenges the validity of a card sale because the issuer provided a declined authorization response.

UA03

Cardholder or issuer challenges the validity of a card sale because the amount billed to the cardholder exceeds amount authorized by the issuer.

UA32

Cardholder or issuer challenges the validity of a card not present card transaction because the acquirer or merchant did not obtain address verification or did not obtain and submit the CID with the authorization request.

UA99

Cardholder or issuer challenges the validity of a card sale and the acquirer or merchant did not comply with the applicable operating regulations in connection with the card sale.

R2

Credit not processed.

A

Cardholder dispute, cardholder request draft.
On this Page