Signature Reconciliation Feed Implementation Guidelines

Agathe - Technical Writer

Last edited: December 20, 2023 14:38

Version 2.4.4 – October 2023

Introduction

The Signature Reconciliation Feed provides transaction and payment data to publishers who use our u1 Signature matching functionality. Use the feed to match your Signature data with payment information. To receive these reports, you must have an FTP or SFTP over SSH server and be enabled to receive the Signature Reconciliation Feed, as detailed in these implementation guidelines.

Report Types

Four reports are sent in XML format as part of the Signature Reconciliation Feed: the Daily u1 Transaction Report, two monthly reports, and the Payment Report; click the + for more information on a specific report:

Daily u1 Transaction Report

Sent daily, this report provides detailed, transaction-level reporting of all u1 transactions that have been matched, or confirmed, from the previous day. Any unconfirmed, or unmatched, transactions are sent with the next file. On the fourth day of each month, the report also includes all unmatched transaction data from the previous month.

Note

If an unmatched transaction from this list is confirmed after we have sent it as unmatched, the same transaction ID will be sent again.

Monthly Reports

Two reports are sent monthly: the Monthly u1 report is sent on the fourth of the month and the Dailyu1_Monthly is sent on the fifth of the month. These reports are identical and contain u1 transactions processed in the previous month. They show all final data for that month and can be used to reconcile data in case of a missing Daily u1 report.

Adjustments from the Publisher Payments statements are not reflected in these reports but are reflected in the Payment Report.

Payment Report

This report is sent daily and includes order and SKU details of payments issued the previous day. If no payments are issued in a day, the report will still be sent but will not contain data. Confirming with its transaction-level detail, advertiser payments can be easily reconciled with the u1 data. If you cannot use this file, then use the Advanced Reports API daily to pull payment IDs for payments issued, invoice numbers paid by advertisers, and order-level details from each invoice.

Daily u1 Transaction Report

Click the + for more information on the different aspects of the Daily u1 Transaction Report:

File Name

The Daily u1 transaction report has a file name that includes your SID and the time in GMT that the file was generated.

For example: 2574052_Dailyu1_20XXJune01-1649.xml if 2574052 is the SID and 16:49 is the time.

Top Level Data Structure

The main tag is <XROOT> and </XROOT>.

The next nested tag is <PRJ_LOYALTY_METADATA_HDR> and </PRJ_LOYALTY_METADATA_HDR>.

Note

The close tag appears directly above </XROOT> at the bottom of the file.

Metadata

This is an example of the metadata:

<FILENAME>2574052_Dailyu1_20XXJune01-1645.xml</FILENAME>
<SID>2574052</SID>
<START_DATE>20XX-05-31</START_DATE>
<END_DATE>20XX-06-01</END_DATE>
<REPORT_TYPE>u1 Member Daily Feed</REPORT_TYPE>

The tags are <FILENAME>, <SID>, <START_DATE>, <END_DATE>, and <REPORT_TYPE>.

Transaction Data

There is only one type of record in this file, u1 Daily Data. Its tags are <PRJ_LOYALTY_u1_DAILY> and </PRJ_LOYALTY_u1_DAILY>. There is one record for each transaction.

This is an example of a Daily Data record:

<MEMBER_ID>u1_here</MEMBER_ID>
<MATCH_DATE>20XX-May-31</MATCH_DATE>
<MATCH_TIME>1730</MATCH_TIME>
<MERCHANT_PARTNER_ID>33</MERCHANT_PARTNER_ID>
<MERCHANT_PARTNER_NAME>Rakuten Affiliate Network merchant</MERCHANT_PARTNER_NAME>
<PRODUCT_SKU_NUMBER>1</PRODUCT_SKU_NUMBER>
<PRODUCT_NAME>HEADPHONES</PRODUCT_NAME>
<TRANSACTION_ID>123</TRANSACTION_ID>
<ORDER_ID>21</ORDER_ID>
<TRANSACTION_DATE>20XX-May-30</TRANSACTION_DATE>
<TRANSACTION_TIME>1807</TRANSACTION_TIME>
<SALES_AMOUNT>99.95</SALES_AMOUNT>
<QUANTITY>1</QUANTITY>
<BASELINE_COMMISSION>10</BASELINE_COMMISSION>
<ADJUSTED_COMMISSION>0</ADJUSTED_COMMISSION>
<TOTAL_COMMISSION>10</TOTAL_COMMISSION>
<PROCESS_DUE_DATE>20XX-May-31</PROCESS_DUE_DATE>
<PROCESS_DUE_TIME>1701</PROCESS_DUE_TIME>

The tags are: <MEMBER_ID>, <MATCH_DATE>, <MATCH_TIME>, <MERCHANT_PARTNER_ID>, <MERCHANT_PARTNER_NAME>, <PRODUCT_SKU_NUMBER>, <PRODUCT_NAME>, <TRANSACTION_ID>, <ORDER_ID>, <TRANSACTION_DATE>, <TRANSACTION_TIME>, <SALES_AMOUNT>, <QUANTITY>, <BASELINE_COMMISSION>, <ADJUSTED_COMMISSION>, <TOTAL_COMMISSION>, <PROCESS_DUE_DATE>, and <PROCESS_DUE_TIME>.

Consult Appendix A for definitions of these tags.

Monthly u1 Report

Click the + for more information on the different aspects of the Monthly u1 Report:

File Name

The first monthly report, Monthlyu1 Report, is sent on the fourth day of the month. Its file name includes your SID and the time in GMT that the file was generated.

For example: 2574052_Monthlyu1_20XXJune04-1645.xml if 2574052 is the SID and 16:45 is the time.

Top Level Data Structure

The main tag is <XROOT> and </XROOT>.

The next nested tag is <PRJ_LOYALTY_METADATA_HDR> and </PRJ_LOYALTY_METADATA_HDR>. Note that the close tag appears directly above </XROOT> at the bottom of the file.

Metadata

This is an example of the metadata:

<FILENAME>2574052_Monthlyu1_20XXJune04-1645.xml</FILENAME> 
<SID>2574052</SID> 
<START_DATE>20XX-05-01</START_DATE> 
<END_DATE>2011-05-31</END_DATE> 
<REPORT_TYPE>u1 Member Monthly Feed</REPORT_TYPE>

The tags are <FILENAME>, <SID>, <START_DATE>, <END_DATE>, and <REPORT_TYPE>.

Transaction Data

There is only one type of record in this file: monthly adjusted commission data. It is identified by tags <PRJ_LOYALTY_u1_DAILY> and </PRJ_LOYALTY_u1_DAILY>.

This is an example of a monthly data record:

<TRANSACTION_ID>E31DACCA3234ECC27253A14FB5C59F38</TRANSACTION_ID> 
<ADJUSTED_COMMISSION>5</ADJUSTED_COMMISSION> 
<TOTAL_COMMISSION>50</TOTAL_COMMISSION>

The tags are <TRANSACTION_ID>, <ADJUSTED_COMMISSION>, and <TOTAL_COMMISSION>.

Consult Appendix A for definitions of these tags.

The Transaction ID can be matched against the Daily u1 report to identify a transaction.

Dailyu1_Monthly Report

Click the + for more information on the different aspects of the Dailyu1_Monthly Report:

File Name

The Dailyu1_Monthly Report is sent on the fifth day of the month. Its file name includes your SID and the time in GMT that the file was generated.

For example: 2574052_Dailyu1_Monthly_20XXJune05-1649.xml where 2574052 is the SID and 16:49 is the time.

Top Level Data Structure

The main tag is <XROOT> and </XROOT>. The next nested tag is <PRJ_LOYALTY_METADATA_HDR> and </PRJ_LOYALTY_METADATA_HDR>.

Note

The close tag is directly above </XROOT> at the bottom of the file.

Metadata

This is an example of the metadata:

<FILENAME>2574052_Dailyu1_Monthly_20XXJune01-1645.xml</FILENAME> 
<SID>2574052</SID> 
<START_DATE>20XX-05-01</START_DATE> 
<END_DATE>20XX-05-31</END_DATE> 
<REPORT_TYPE>u1 Member Monthly Feed</REPORT_TYPE>

The tags are <FILENAME>, <SID>, <START_DATE>, <END_DATE>, and <REPORT_TYPE>.

Monthly u1 Data

There is only one type of record in this file: monthly u1 data. It is identified by tags <PRJ_LOYALTY_u1_DAILY> and </PRJ_LOYALTY_u1_DAILY>.

There is one record for each transaction.

This is an example of a monthly record:

<MEMBER_ID>u1_here</MEMBER_ID> 
<MATCH_DATE>20XX-May-31</MATCH_DATE> 
<MATCH_TIME>1730</MATCH_TIME> 
<MERCHANT_PARTNER_ID>33</MERCHANT_PARTNER_ID> 
<MERCHANT_PARTNER_NAME>Rakuten Affiliate Network merchant</MERCHANT_PARTNER_NAME> 
<PRODUCT_SKU_NUMBER>1</PRODUCT_SKU_NUMBER> 
<PRODUCT_NAME>HEADPHONES</PRODUCT_NAME> 
<TRANSACTION_ID>123</TRANSACTION_ID> 
<ORDER_ID>21</ORDER_ID> 
<TRANSACTION_DATE>20XX-May-30</TRANSACTION_DATE> 
<TRANSACTION_TIME>1807</TRANSACTION_TIME> 
<SALES_AMOUNT>99.95</SALES_AMOUNT> 
<QUANTITY>1</QUANTITY> 
<BASELINE_COMMISSION>10</BASELINE_COMMISSION> 
<ADJUSTED_COMMISSION>0</ADJUSTED_COMMISSION> 
<TOTAL_COMMISSION>10</TOTAL_COMMISSION> 
<PROCESS_DUE_DATE>20XX-May-31</PROCESS_DUE_DATE> 
<PROCESS_DUE_TIME>1701</PROCESS_DUE_TIME>

The tags here are: <MEMBER_ID>, <MATCH_DATE>, <MATCH_TIME>, <MERCHANT_PARTNER_ID>, <MERCHANT_PARTNER_NAME>, <PRODUCT_SKU_NUMBER>, <PRODUCT_NAME>, <TRANSACTION_ID>, <ORDER_ID>, <TRANSACTION_DATE>, <TRANSACTION_TIME>, <SALES_AMOUNT>, <QUANTITY>, <BASELINE_COMMISSION>, <ADJUSTED_COMMISSION>, <TOTAL_COMMISSION>, <PROCESS_DUE_DATE>, and <PROCESS_DUE_TIME>.

Consult Appendix A for definitions of these tags.

Unmatched Monthly u1 Transactions

This file includes transactions that matched for Member ID in that month. The file also includes unmatched transactions from the previous month. These transactions have the value null for Member ID and Match Date.

Payment Report

Click the + for more information on the different aspects of the Payment Report:

File Name

The payment reconciliation report file name includes your SID and the time in GMT that the file was generated.

For example: 2574052_Payment_20XXMay31- 1645.xml where 2574052 is the SID and 16:45 is the time.

Top Level Data Structure

The main tag is <PRJ_LOYALTY_METADATA_HDR> and </PRJ_LOYALTY_METADATA_HDR>.

Metadata

This is an example of the metadata:

<FILENAME>2574052_Payment_20XXMay31-1645.xml</FILENAME> 
<SID>2574052</SID> 
<START_DATE>20XX-05-30</START_DATE> 
<END_DATE>20XX-05-31</END_DATE> 
<REPORT_TYPE>Payment Feed</REPORT_TYPE>

The tags are <FILENAME>, <SID>, <START_DATE>, <END_DATE>, and <REPORT_TYPE>.

Payment Summary

Inside the metadata tag and after the metadata, the top level of data is the payment summary. Its tag is <PRJ_LOYALTY_PAYMENT_SUMMARY> and </PRJ_LOYALTY_PAYMENT_SUMMARY>. There is one payment summary per payment. It includes both data and a series of payment details.

This is an example of the payment summary data:

<PAYMENT_ISSUE_DATE>20XXMay31-1120</PAYMENT_ISSUE_DATE> 
<CHECK_ACH_NUMBER>12345</CHECK_ACH_NUMBER> 
<LS_PAYMENT_ID>67890</LS_PAYMENT_ID> 
<PAYMENT_TYPE>Domestic Check</PAYMENT_TYPE> 
<PAYMENT_CURRENCY>Dollar</PAYMENT_CURRENCY> 
<PAY_AMOUNT>10000.00</PAY_AMOUNT>

The tags are <PAYMENT_ISSUE_DATE>, <CHECK_ACH_NUMBER>, <LS_PAYMENT_ID>, <PAYMENT_TYPE>, <PAYMENT_CURRENCY>, and <PAY_AMOUNT>.

Consult Appendix B for definitions of these tags.

Payment Detail

As mentioned above, the payment summary includes a series of payment details in addition to this data.

The tags for payment details are <PRJ_LOYALTY_PAYMENT_DTL> and </PRJ_LOYALTY_PAYMENT_DTL>. There is one payment detail per invoice.

A record includes data about the payment and a series of transaction details. Data about the payment are formatted as such:

<PARTNER_NAME>Rakuten Affiliate Network Merchant</PARTNER_NAME> 
<PARTNER_ID>32</PARTNER_ID> 
<INVOICE_NUMBER>25243</INVOICE_NUMBER> 
<INVOICE_PERIOD_START_DATE>20XXMay01- 0000</INVOICE_PERIOD_START_DATE> 
<INVOICE_PERIOD_END_DATE>20XXMay31-0000</INVOICE_PERIOD_END_DATE> 
<COMMISSION_AMT_EARNED>100.00</COMMISSION_AMT_EARNED> 
<FORWARD_BALANCE_AMT>0</FORWARD_BALANCE_AMT> 
<ADJUSTMENT_BONUS_AMT>0</ADJUSTMENT_BONUS_AMT> 
<HOLD_AMT>0</HOLD_AMT> 
<PAYMENT_AMT>100.00</PAYMENT_AMT>

The tags are <PARTNER_NAME>, <PARTNER_ID>, <INVOICE_NUMBER>, <INVOICE_PERIOD_START_DATE>, <INVOICE_PERIOD_END_DATE>, <COMMISSION_AMT_EARNED>, <FORWARD_BALANCE_AMT>, <ADJUSTMENT_BONUS_AMT>, <HOLD_AMT>, and <PAYMENT_AMT>.

Consult Appendix B for definitions of these tags.

Transaction Detail

As mentioned above, each payment detail includes a series of transaction details. There is one Transaction Detail for each transaction covered by the invoice. The tags for a Transaction Detail are <PRJ_LOYALTY_TRANSACTION_DTL> and </PRJ_LOYALTY_TRANSACTION_DTL>.

There is one record for each transaction detail. Here is a sample transaction detail:

<MEMBER_ID>u1_here</MEMBER_ID> 
<MATCH_DATE>20XX-May-31</MATCH_DATE> 
<MATCH_TIME>1730</MATCH_TIME> 
<MERCHANT_PARTNER_ID>33</MERCHANT_PARTNER_ID> 
<MERCHANT_PARTNER_NAME>Rakuten Affiliate Network merchant</MERCHANT_PARTNER_NAME> 
<PRODUCT_SKU_NUMBER>1</PRODUCT_SKU_NUMBER> 
<PRODUCT_NAME>HEADPHONES</PRODUCT_NAME> 
<TRANSACTION_ID>123</TRANSACTION_ID> 
<ORDER_ID>21</ORDER_ID> 
<TRANSACTION_DATE>20XX-May-30</TRANSACTION_DATE> 
<TRANSACTION_TIME>1807</TRANSACTION_TIME> 
<SALES_AMOUNT>99.95</SALES_AMOUNT> 
<QUANTITY>1</QUANTITY> 
<BASELINE_COMMISSION>10</BASELINE_COMMISSION> 
<ADJUSTED_COMMISSION>0</ADJUSTED_COMMISSION> 
<TOTAL_COMMISSION>10</TOTAL_COMMISSION> 
<PROCESS_DUE_DATE>20XX-May-31</PROCESS_DUE_DATE> 
<PROCESS_DUE_TIME>1701</PROCESS_DUE_TIME>

Consult Appendix A for definitions of these tags.

Enablement Process

Contact Customer Support to request enablement for the Signature Reconciliation Feed. You may be asked by Customer Support to validate the relevance of the feed to your business model.

After you request enablement, the Customer Support team will update your account settings to allow you to add credentials to your FTP/SFTP server in a new form available on the Reporting Interface. See Self-Managing Signature Reconciliation Feed for instructions on adding your credentials.

Self-Managing Signature Reconciliation Feed

Once Customer Support has completed your initial request, you will see a Manage Signature Reconciliation Feed button on the right of the Reporting Interface:

Click the button to open the feed-management modal:

There are two main sections on this modal:

Status: select to Enable or Disable the delivery of the Signature Reconciliation Feed. If you disable delivery, you will stop receiving the feed from the following day and until you select to enable delivery once more.
Protocol: select a delivery protocol and set delivery information for us to send your feed. You can choose between FTP, SFTP, and SSH delivery methods and must supply the following information in order to complete enablement:
- FTP Location
- Port
- Username
- Password for FTP and SFTP; Private Key for SSH.

We recommend you test the upload prior to saving configuration. A 1KB file called test.txt will be sent to the location configured to confirm that the connection has been successful.

Once your protocol settings have been configured, set the status to Enabled and click Set Delivery. You should begin receiving files the following day.

Further Assistance

Contact your Publisher Manager or Customer Support for questions regarding the Signature Reconciliation Feed.

Appendix A: Definitions for Transaction

Consult Appendix A for transaction definitions.

Appendix B: Definitions for Payment Reconciliation Report

Consult Appendix B for Payment Reconciliation report definitions.

Signature Reconciliation Feed 2.4.4_October_2023.pdf
(300 KB)