Chapter 2

XML Report Formats

This chapter describes the format of these CyberSource XML reports:

XML Conventions

Reports

See Appendix A, XML Report DTDs for the document type definitions (DTDs) for XML reports.

XML Conventions

To understand how a report in XML format is constructed, you need to become familiar with the syntax and the data types used for XML reports.

Syntax

Each report is described as follows.

Report Declaration

These conventions are used to describe the report:

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE Report SYSTEM URIreference>

<Report Name= CDATA

Version=NMTOKEN

xmlns=CDATA

MerchantID=CDATA

ReportStartDate=CDATA

ReportEndDate=CDATA>

Note The value of URIreference is the same as that for xmlns. In addition, whether you are operating in test or live mode, the namespace always refers to ebctest instead of ebc.

Element Declaration

These conventions are used to describe the syntax of each XML element:

(Element)

(ChoiceOne) | (ChoiceTwo)

(ComplexElement)

(RequiredRecurringElement)+

(OptionalElement)?

(OptionalRecurringElement)*

</Sample>

Note The DTDs for the reports may use a syntax with the ?, +, or * character inside the parentheses. For example, instead of (OptionalElement)?, the DTD may use (OptionalElement?). Either syntax is acceptable.

**Table 7** Conventions for XML Syntax
Convention	Description
<Sample>	Parent of the following elements.
Attribute=CDATA	Name of the attribute, followed by the XML data format for the attribute.
(Element)	Required element. Must appear only once.
(ChoiceOne) \| (ChoiceTwo)	Either element <ChoiceOne> or <ChoiceTwo> but not both.
(ComplexElement)	Element with one or more children.
(RequiredRecurringElement)+	Required element. Can appear one or more times.
(OptionalElement)?	Optional element. Can appear once or be omitted.
(OptionalRecurringElement)*	Optional element. Can appear zero or more times.

Data Types and Lengths

This chapter uses the following terms to refer to the data type of each field:

• Alphanumeric: String containing letters, numbers, and special characters (for example, @, #, and %). All text uses UTF-8 character encoding.

• Boolean: Single character; T for true or F for false.

• Amount: An amount, including a decimal point if necessary.

• Date: YYYY-MM-DD, where:

• YYYY is the four-digit year

• MM is the two-digit month

• DD is the two-digit day

• Date Time: YYYY-MM-DDTHH:MM:SS[+ | -]HH:MM, where:

• YYYY is the four-digit year.

• MM is the two-digit month.

• DD is the two-digit day.

• THH:MM:SS is the time, with HH representing hours, MM representing minutes, and SS representing seconds.

• [+ | -]HH:MM is the time zone’s offset from Greenwich Mean Time (GMT), with HH representing hours and MM representing minutes. The number is prefixed by either a plus (+) or minus (-) to indicate whether the offset adds to or subtracts from GMT.

For example, the offset for Pacific Daylight Time is -07:00.

• Numeric: string containing numbers.

The data lengths indicate the maximum length of each field.

Reports

Payment Batch Detail Report

Payment Events Report

Payment Submission Detail Report

Query for a Single Transaction

Transaction Exception Detail Report

User Management Report

Payment Batch Detail Report

The Payment Batch Detail Report contains transactions processed with these applications:

• Bank transfer and bank transfer refund

• Credit card capture and credit

• Direct debit and direct debit refund

• Electronic check debit and electronic check credit

• PayPal transactions

• Bill Me Later transactions

The report includes only transactions that CyberSource has sent to the payment processor.

Note Transactions appear in the Payment Batch Detail Report before funds are transferred to or from your merchant bank account. To determine whether funds have been transferred, you must reconcile the Payment Batch Detail Report with your bank statements.

For more information about reconciling transactions, see the Credit Card Services Implementation Guide and the Electronic Check Services Implementation Guide.

The <Report> element is the root element of the report.

Syntax

<Report Name=CDATA

Version=NMTOKEN

xmlns=CDATA

MerchantID=CDATA

ReportStartDate=CDATA

ReportEndDate=CDATA>

(Batches)

</Report>

**Table 8** Attributes of <Report>
Attribute Name	Description	Data Type and Length
Name	Name of the report. This element always contains the text Payment Batch Detail.	Alphanumeric (100)
Version	Version number of the report. The current version number is 1.0.	Numeric (10)
xmlns	XML namespace for the report. The namespace for the current version is https://ebctest.cybersource.com/ebctest/reports/dtd/ pbdr.dtd.	Alphanumeric (100)
MerchantID	CyberSource merchant ID used for the transactions in the report.	Alphanumeric (30)
ReportStartDate	First date included in the report.	DateTime (25)
ReportEndDate	Last date included in the report.	DateTime (25)

**Table 9** Child Elements of <Report>
Element Name	Description
<Batches>	Payment batches that are included in the report. See <Batches> for a list of child elements.

Example <Report> Element

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE Report SYSTEM "https://ebctest.cybersource.com/ebctest/reports/dtd/pbdr.dtd">

<Report Name="Payment Batch Detail"

Version="1.0"

xmlns="https://ebctest.cybersource.com/ebctest/reports/dtd/pbdr.dtd"

MerchantID="sample"

ReportStartDate="2001-06-25T07:00:00-07:00"

ReportEndDate="2001-06-26T07:00:00-07:00">

...

</Batches>

</Report>

The <Batches> element contains all of the payment batches that are included in the report.

Syntax

(Batch)*

</Batches>

**Table 10** Child Elements of <Batches>
Element Name	Description
<Batch>	Requests associated with a payment batch. See <Batch> for a list of child elements and attributes.

Example <Batches> Element

<Batch BatchID="10101"

BatchDate="2001-08-15">

...

</Batch>

</Batches>

<Batch>

The <Batch> element contains the requests associated with a payment batch. The element’s attributes provide information about the payment batch.

Syntax

<Batch BatchID=CDATA

BatchDate=CDATA>

(Requests)

</Batch>

**Table 11** Attributes of <Batch>
Attribute Name	Description	Data Type and Length
BatchID	CyberSource batch in which the transaction was sent.	Numeric (39)
BatchDate	Date when the batch was sent to the processor.	Date (10)

Example <Batch> Element

<Batch BatchID="10101"

BatchDate="2001-08-15">

...

</Requests>

</Batch>

The <Requests> element contains all of the requests from a payment batch.

Syntax

(Request)*

</Requests>

**Table 12** Child Elements of <Requests>
Element Name	Description
<Request>	Information about a payment transaction. See <Request> for a list of child elements and attributes.

Example <Requests> Element

<Request RequestID="0062929390000167905114"

MerchantReferenceNumber="58EA07517FE5A71C016884DCB">

...

</Request>

</Requests>

The <Request> element contains information about a payment transaction.

Syntax

<Request RequestID=CDATA

MerchantReferenceNumber=CDATA>

(TransactionReferenceNumber)

(PaymentMethod)

(CurrencyCode)

(Amount)

(Application)

</Request>

**Table 13** Attributes of <Request>
Attribute Name	Description	Data Type and Length
RequestID	Unique identifier generated by CyberSource for the transaction.	Numeric (26)
MerchantReferenceNumber	Merchant-generated order reference or tracking number.	Alphanumeric (50)

**Table 14** Child Elements of <Request>
Element Name	Description	Data Type and Length
<TransactionReferenceNumber>	Reference number that you use to reconcile your CyberSource reports with your processor reports. This field corresponds to the <service>_reconciliationID (Simple Order API) and to the <service>_trans_ref_no (SCMP API) reply fields.	Alphanumeric (60)
<PaymentMethod>	Type of card or bank account. This field can contain one of these values: If your company uses CyberSource to process a private label card, this field can also contain the name of your private label card.	Alphanumeric (50)
<PaymentMethod>		Alphanumeric (50)
<CurrencyCode>	ISO currency code used for the transaction.	Alphanumeric (5)
<Amount>	Amount of the transaction.	Amount (19)
<Application>	CyberSource payment application processed for the transaction.	Alphanumeric (50)

Example <Request> Element

<Request RequestID="0062929390000167905114"

MerchantReferenceNumber="58EA07517FE5A71C016884DCB">

<TransactionReferenceNumber>SJZPTM07Y8O5
</TransactionReferenceNumber>

</Request>

Payment Events Report

This report contains payment notifications received from the processor for these types of transactions that you submitted to CyberSource:

• Bank transfers

• China payments and refunds

• Credit card transactions processed with the CyberSource Global Payment Service

• Direct debits

• Electronic check debits and credits with TeleCheck, AmeriNet, or Paymentech

• PayPal payments

Report Generation for the Global Payment Service

The report is generated daily Monday through Friday unless CyberSource does not receive a data file from the processor, receives the data file after the cut-off time, or receives an empty data file. Because the report is not generated on weekends, the report that you download on Mondays contains all your weekend transactions. You should ensure that your implementation can handle reports that contain transactions spanning multiple processing days.

The report is generated for the date when CyberSource processes the file, not for the date when the processor submits the file. Because of cut-off and processing times, transactions that you process on Day 1 will most likely appear on the report on Day 3.

If the generation of the report is delayed, you are notified. Because the report generated after a delay may span more than one day, ensure that you can track the delayed reports.

When CyberSource needs to regenerate a report, the entire report is generated, not only selected transactions. You are notified as soon as the new version of the report is available. Ensure that your implementation can recognize and process only the transactions that were modified or added to the report.

Transaction Exceptions for the Global Payment Service

Although most reports contain transactions that you can match, you should prepare your implementation to recognize these payment and refund exceptions. In some cases, you may need to search your system manually for the original request ID, which remains in the CyberSource system for six months.

• Rejected payments and refunds

Although the reply that you receive from CyberSource may indicate that a transaction was successful, the processor may occasionally reject a transaction. Rejected transactions do not appear on the Payment Events Report. However, Customer Support will notify you by email if rejections occur.

• Delayed payments

You need to be aware that payments may be occasionally delayed.

• Unmatched payments and refunds

Unmatched events occur when the processor generates an event that cannot be matched or when the event is older than six months. If CyberSource cannot match the payment or refund to a specific transaction, CyberSource generates a new request ID for the unmatched event.

• Corrections to payments and refunds

When the amount of the original event is changed, or the event is reversed, you need to update the original payment or refund.

You may also see duplicate payments and refunds in the same or different reports. You can ignore these events because they will match an existing request ID.

The <Report> element is the root element of the report.

Syntax

<Report Name=CDATA

Version=NMTOKEN

xmlns=CDATA

MerchantID=NMTOKEN

ReportStartDate=NMTOKEN

ReportEndDate=NMTOKEN>

(Requests)

</Report>

**Table 15** Attributes of <Report>
Attribute Name	Description	Data Type and Length
MerchantID	CyberSource merchant ID used for the transaction.	Alphanumeric (30)
Name	Name of the report. This field always contains the text Payment Events.	Alphanumeric (100)
ReportStartDate	First date that is included in the report.	DateTime (25)
ReportEndDate	Last date that is included in the report.	DateTime (25)
Version	Version number of the report. The current version number is 1.0.	Numeric (10)
xmlns	XML namespace for the report. The namespace for the current version is https://ebc.cybersource.com/ebc/reports/dtd/per.dtd.	Alphanumeric (100)

**Table 16** Child Elements of <Report>
Element Name	Description
<Requests>	Contains all of the requests in the report. See <Requests> for a list of child elements.

Example <Report> Element

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE Report SYSTEM "https://ebc.cybersource.com/ebc/reports/dtd/per.dtd">

<Report Name="Payment Events"

Version="1.0"

xmlns="https://ebc.cybersource.com/ebc/reports/dtd/per.dtd"

MerchantID="CyberSource"

ReportStartDate="2002-08-16T08:00:00-07:00"

ReportEndDate="2002-08-17T08:00:00-07:00">

...

</Requests>

</Report>

The <Requests> element contains all the requests that are included in the report.

Syntax

(Request)*

</Requests>

**Table 17** Child Elements of <Requests>
Element Name	Description
<Request>	Information about a single request. See <Request> for a list of child elements and attributes.

Example <Requests> Element

<Request RequestID="0004223530000167905139"

MerchantReferenceNumber="3C515C71D48F631">

...

</Request>

</Requests>

The <Request> element contains information about the type of payment transaction.

Syntax

<Request RequestID=CDATA

MerchantReferenceNumber=CDATA>

(BankTransfer) | (CreditCard) | (DirectDebit) | (Check) | (PayPal)

</Request>

**Table 18** Attributes of <Request>
Attribute Name	Description	Data Type and Length
RequestID	Unique identifier generated by CyberSource for the transaction. If your payment processor is Global Collect, the value inserted into this field may be 1 followed by 21 zeros in these cases: • The transaction is older than six months, and the request ID is no longer stored. • The transaction information sent by the processor, excluding a valid request ID.	Numeric (26)
MerchantReferenceNumber	Merchant-generated order reference or tracking number.	Alphanumeric (50)

**Table 19** Child Elements of <Request>
Element Name	Description
<BankTransfer>	Information about a bank transfer transaction, a China payment, or a China refund. See <BankTransfer>, <CreditCard>, and <DirectDebit> below for a list of child elements and attributes.
<CreditCard>	Information about a credit card transaction, a China payment, or a China refund. See <BankTransfer>, <CreditCard>, and <DirectDebit> below for a list of child elements and attributes.
<DirectDebit>	Information about a direct debit transaction. See <BankTransfer>, <CreditCard>, and <DirectDebit> below for a list of child elements and attributes.
<Check>	Information about a check transaction. See <Check> for a list of child elements and attributes.
<PayPal>	Information about a PayPal transaction. See <PayPal> for a list of child elements and attributes.

Example <Request> Element

MerchantReferenceNumber="3C515C71D48F631">

...

</BankTransfer>

</Request>

The <BankTransfer>, <CreditCard>, and <DirectDebit> elements contain information about transactions that use these payment types. Information about China payments and China refunds is contained in the <CreditCard> element for international credit card transactions and in the <BankTransfer> element for Chinese bank card and PayEase eWallet transactions. All three elements have the same attributes and child elements. The <BankTransfer> element is used below to show the syntax for all three elements.

Syntax

<BankTransfer Event=CDATA

EventDate=NMTOKEN>

(TransactionReferenceNumber)

(MerchantCurrencyCode)

(MerchantAmount)

(ConsumerCurrencyCode)

(ConsumerAmount)

(ProcessorMessage)?

</BankTransfer>

**Table 20** Attributes of <BankTransfer>, <CreditCard>, and <DirectDebit>
Attribute Name	Description	Data Type and Length
Event	Type of event that occurred for the transaction. Values for bank transfers, credit cards, and direct debits: • Chargeback: The customer did not authorize the transaction. For more details about the decline, see <ProcessorMessage>. • Correction: The payment or refund was corrected, or the bank was unable to credit the customer's account; the values is either positive or negative. • Failed: The account was invalid or disabled. For more details about the decline, see <ProcessorMessage>. • Other: The processor reported an unanticipated event.	Alpha (20)
	• Payment: The payment was received by the processor’s bank; the value is always positive. • Refund: The money was returned to the customer; the value is always negative. For more details about the refund, see <ProcessorMessage>. • Reversal: A payment was reversed. For more details about the reversal, see <ProcessorMessage>. • Settled: The transaction has been settled: the payment has been received, or the refund has been given to the customer. • Settled Unmatched: A bank transfer payment has been received but cannot be matched to the original request.
	Values for China payments and China refunds: • Chargeback: The original payment transaction is being disputed by the cardholder or the cardholder’s bank. • Payment Abnormal: The payment has been held up for regulatory or legal reasons. • Payment Declined: The processor has refused the payment request.
	• Payment Failed: The payment request failed. The reason is not specified. • Payment Funded: The processor has submitted a transfer to the merchant's bank account as a result of a settled payment. • Payment Initiated: The payment request was received from the merchant.
	• Payment Lost: The processor does not acknowledge receiving the payment request. • Payment Pending Proc: The payment has not been completed. It is awaiting settlement by the processor. • Payment Settled: The payment has been confirmed by the processor and is expected to be funded.
	• Refund Abnormal: The refund has been held up for regulatory or legal reasons. • Refund Declined: The processor has refused the refund request. • Refund Failed: The refund request failed. The reason is not specified.
	• Refund Funded: The processor has submitted a transfer to the merchant's bank account as a result of a settled refund. • Refund Pending Cyb: The refund has not been completed. It is awaiting transmission by CyberSource. • Refund Pending Proc: The refund has not been completed. It is awaiting settlement by the processor.
	• Refund Settled: The refund has been confirmed by the processor and is expected to be funded. • Unknown: The processor does not acknowledge receiving the request.
EventDate	Date of the event.	DateTime (25)

**Table 21** Child Elements of <BankTransfer>, <CreditCard>, and <DirectDebit>
Element Name	Description	Data Type and Length
<ConsumerAmount>	The amount deposited or withdrawn from the customer’s account for the event.	Amount (19)
<ConsumerCurrencyCode>	ISO currency code of the customer’s currency.	Alphanumeric (5)
<MerchantAmount>	The amount deposited or withdrawn from the merchant’s account for the event.	Amount (19)
<MerchantCurrencyCode>	ISO currency code of the merchant’s currency.	Alphanumeric (5)
<ProcessorMessage>	Additional information about the event from the processor, such as an error message or reason. For Global Collect direct debit reversals, this field contains a banking reversal code. See Appendix D, Banking Reversal Codes in the Payment Events Report .	Alphanumeric (255)
<TransactionReferenceNumber>	Reference number that you use to reconcile your CyberSource reports with your processor reports. This field corresponds to the <service>_reconciliationID (Simple Order API) and to the <service>_trans_ref_no (SCMP API) reply fields.	Alphanumeric (60)

Example <BankTransfer> Element

<BankTransfer Event="Payment"

EventDate="2003-02-16T00:00-07:00">

</BankTransfer>

<Check>

The <Check> element contains information about transactions that use this payment type if your check processor is AmeriNet, TeleCheck, or Paymentech.

Syntax

<Check Event=CDATA

EventDate=NMTOKEN>

(TransactionReferenceNumber)

(MerchantCurrencyCode)

(MerchantAmount)

(ConsumerCurrencyCode)

(ConsumerAmount)

(FeeCurrencyCode)

(FeeAmount)

(ProcessorMessage)?

</Check>

Important Depending on your check processor, the impact of the type of event in the table below on the movement of funds may differ. Contact your processor to understand the implications of each event type for your payment process.

**Table 22** Attributes of <Check>
Attribute Name	Description	Data Type and Length
Event	Type of event that occurred for the check transaction. The values that you receive vary with the processor. Successful events Immediately after a transaction is submitted, this field contains one of these values: • Payment: Payment has been received. The value is always positive. • Refund: A refund (credit) occurred. The value is always negative. For AmeriNet only. After six days, if the bank does not notify