Submission Report Specification (Open Wallet API)
DOCS
Last updated: Aug 15th, 7:23am
Important: Open Wallet is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal account manager.
This report contains all relevant transactions between 12:00 AM to 11:59 PM PST of the day after the transaction. Each submission file has transactions for a given financial instrument. Transactions across instruments are not mixed in a single file.
File specifications
The following specifications apply to the submission report file:
| Record length | 2000 byte fixed length. |
| File format | UTF-8 encoded. |
| Transmission day and time | The day of the transaction before 2 AM PST. |
| File direction | In general, transmitted from PayPal to partner. |
Field specifications
The following specifications apply to the Submission report fields:
Submission file header
The full file contains only one file header.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SFHR001 | Yes | Corresponds to the record type and must be the first item in the record. The SFHR001 constant indicates a file header record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 8 8 and 15 | 00000001 | Yes | Contains a record sequence number to monitor the integrity and continuity of data in a file. The header record is always set to 00000001. Each subsequent record in the file must be incremented to the RECORD_NUMBER value in the preceding record plus 1.The number of records per file must not exceed 99999999. | |
| 3 | CLIENT_ID | Alphanumeric, uppercase, left justified, character space filled (if no value) | 11 16 and 26 | -- | Yes | The unique PayPal-assigned ID. | |
| 4 | FILE_DIRECTION | Alphanumeric, uppercase, left justified, character space filled (if no value) | 1 16 and 26 | -- | Yes | The unique PayPal-assigned ID. | |
| 5 | FILE_REFERENCE_NUMBER | Alphanumeric, uppercase, left justified, character space filled (if no value) | 12 28 and 39 | Unique system-generated file reference number (unique across PayPal) | Yes | Contains a submitter-specified file reference number. Can be used to track this file. Value must be unique for each submitted file. A file identification and tracking cross-reference to the corresponding File Validation Report. | |
| 6 | FILE_CREATION_DATE | Numeric, CCYYMMDD | 8 40 and 47 | The date when the submission file was created (PST) | Yes | Corresponds to the date when the submitter created the file. The format is CCYYMMDD, where:
20200215 for February 15, 2020. | |
| 7 | FILE_CREATION_TIME | Numeric, HHMMSS (24-hour clock) | 6 48 and 53 | The time when the submission file was created (PST) | Yes | Corresponds to the time when the submitter created the file. The format is HHMMSS, where
143000 for 2:30 PM. | |
| 8 | FILE_VERSION_NUMBER | Alphanumeric | 8 54 and 61 | Version of the file | Yes | Version of the file. | |
| 9 | FILLER | Alphanumeric | 1939 62 and 2000 | Character spaces | Yes | PayPal internal use only. |
Submission batch header
A single file can contain multiple batch headers, which are sorted by product and wallet brand.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SDPR001 | Yes | Corresponds to the record type and must be the first item in the record. The SDPR001 constant indicates a detail primary record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 8 8 and 15 | 00000003 | Yes | Contains a record sequence number to monitor the integrity and continuity of data in a file. The header record is always assigned 00000001. Each subsequent record must be incremented by 1 more than the RECORD_NUMBER entry in the preceding record.The number of records per file must not exceed 99999999. | |
| 3 | PRODUCT_ID | Alphanumeric, uppercase, left justified, character space filled (if no value) | 11 16 and 26 | -- | Yes | The unique PayPal-assigned ID. | |
| 4 | WALLET_BRAND | Numeric, right justified, zero filled (if no value) | 3 27 and 29 |
| Yes | Wallet associated with the specific attraction | |
| 5 | FILLER | Alphanumeric | 1971 30 and 2000 | Character spaces | Yes | PayPal internal use only. |
Submission detail primary record
Only one Yes record per transaction.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SDPR001 | Yes | Corresponds to the record type and must be the first item in the record. The SDPR001 constant indicates a detail primary record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 8 8 and 15 | 00000003 | Yes | Contains a record sequence number to monitor the integrity and continuity of data in a file. The header record is always set to 00000003. Each subsequent record must be incremented to the RECORD_NUMBER value in the preceding record plus 1.The number of records per file must not exceed 99999999. | |
| 3 | REFERENCE_FINANCIAL_INSTRUMENT_ID | Numeric | 15 16 and 30 | -- | Yes | Uniquely identifies the P2P Pass instrument used for the transaction. Equivalent to the FPAN in the card world. | |
| 4 | PAYER ID | Alphanumeric | 19 31 and 49 | -- | Yes | The sender's PayPal account number. | |
| 5 | TRANSACTION_TYPE | Alphanumeric | 2 50 and 51 |
| Yes | Type of transaction. Depending on the product and file direction, results in a credit to PayPal or a debit from PayPal. | |
| 6 | TRANSACTION_DATE | Numeric, CCYYMMDD | 8 52 and 59 | Transaction Date (PST) | Yes | Corresponds to the date when the submitter created the file. The format is CCYYMMDD, where:
| |
| 7 | TRANSACTION_TIME | Numeric, HHMMSS (24-hour clock) | 6 60 and 65 | Transaction Time (PST) | Yes | Corresponds to the time when the submitter created the file. The format is HHMMSS, where:
143000 for 2:30 PM. | |
| 8 | ISSUER_ORIGINATION_ID | Alphanumeric | 15 66 and 80 | In P2P Pass discussions, this was referred to as the Amex Origination ID | Conditional | This ID is unique. This ID is always generated by the issuer for every transaction from the issuer. PayPal includes this ID in the API call it makes to the issuer as part of executing that transaction from the issuer. | |
| 9 | REFERENCE_KEY | Alphanumeric | 20 81 and 100 | RRN | Yes | PayPal generates and sends this ID to Amex for every original transaction API call | |
| 10 | REFUND_REFERENCE_KEY | Alphanumeric | 20 101 and 120 | Refund/Reversal RRN | Conditional | PayPal generates and sends this ID to Amex for reverse money movement API calls associated with the original transaction | |
| 11 | APPROVAL_ID | Alphanumeric, left-justified, character space filled | 12 121 and 132 | Unique ID received from the client when the authorization and reserve funds request is approved in real time | Yes | This field should contain the same value the issuer transmitted in the original authorization response message. This value must be unique. In cases where an approval code is inapplicable, such as credit transactions, fill this field with character space. | |
| 12 | REFUND_APPROVAL_ID | Alphanumeric, left-justified, character space filled | 12 133 and 144 | -- | Conditional | Should contain the same value transmitted from the issuer in the refund/reversal response to reverse the original transaction. Must be unique. In cases where an approval code does not apply, such as credit transactions, this field must be character space filled. | |
| 13 | AMOUNT | Numeric, right justified, zero filled (if no value) | 12 145 and 156 | Transaction amount in the currency designated by the currency code field | Yes | Contains the total transaction amount in the currency designated by the currency code. Zero-value transactions are not accepted. | |
| 14 | CURRENCY_CODE | Alphanumeric, uppercase | 3 157 and 159 | Currency code of the transaction | Yes | Contains the code of the currency used to execute the original transaction. It corresponds to the currency used for the AMOUNT field. The currency code format supports both ISO alpha and numeric values. For example, the ISO alpha code for U.S. Dollars is USD, and the numeric code is 840 . | |
| 15 | CONVERSION_RATE | Alphanumeric | 6 160 and 165 | -- | No | -- | |
| 16 | SEQUENCE_NUMBER | Numeric, zero-filled if no value | 6 166 and 171 | -- | No | -- | |
| 17 | CLEARING NUMBER | Numeric, zero-filled if no value | 6 172 and 177 | -- | No | -- | |
| 18 | SETTLEMENT_ID | Alphanumeric | 20 178 and 197 | -- | No | -- | |
| 19 | REFUND_SETTLEMENT_ID | Alphanumeric | 20 198 and 217 | -- | No | -- | |
| 20 | INSTRUMENT_EXPIRY_DATE | Numeric | 4 218 and 221 | -- | No | -- | |
| 21 | MERCHANT_ID | Alphanumeric | 2 222 and 233 | -- | No | -- | |
| 22 | FILLER | Alphanumeric | 1767 234 and 2000 | Character spaces | Yes | For PayPal internal use only |
Submission detail associated record
A No record. The primary record might have zero or multiple records tied to it.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SDAR002 | No | Corresponds to the record type and must be the first item in the record. The SDAR002 constant indicates a detail associated record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 8 8 and 15 | -- | No | Contains a record sequence number to monitor the integrity and continuity of data in a file. The header record is always set to 00000001. Each subsequent record must be incremented to the RECORD_NUMBER value in the preceding record plus 1.The number of records per file must not exceed 99999999. | |
| 3 | FILLER | Alphanumeric | 1985 16 and 2000 | Character spaces | No | Reserved for PayPal internal use. |
Submission batch trailer
One file can contain multiple batch trailers, which correspond to the number of batch headers and are sorted by product and wallet brand.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SBTR001 | Yes | Corresponds to the record type and must be the first item in the record. The SBTR001 constant indicates a batch trailer record. | |||||||||||||
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 7 8 and 14 | Yes | Contains a record sequence number to monitor the integrity and continuity of data in a file. The Header record is always assigned the value 00000001; and each subsequent record in the file must be incremented to a value "1" more than the RECORD_NUMBER entry.The number of records per file must not exceed 99999999. | ||||||||||||||
| 3 | PRODUCT_ID | Alphanumeric, uppercase, left justified, character space filled | 11 15 and 25 | -- | Yes | The unique PayPal-assigned ID for a product. | |||||||||||||
| 4 | WALLET_BRAND | Numeric, right justified, zero filled | 3 26 and 28 |
| Yes | Wallet associated with the specific transaction. | |||||||||||||
| 5 | TOTAL_NUMBER_OF_BATCH_TRANSACTIONS | Numeric, right justified, zero filled | 8 29 and 36 | -- | Yes | Total number of 'Detail Primary Records' (DPR001) in this batch. | |||||||||||||
| 6 | TOTAL_NUMBER_OF_BATCH_CREDIT_TRANSACTIONS | Numeric, right justified, zero filled | 8 37 and 44 | -- | Yes | -- | |||||||||||||
| 7 | TOTAL_BATCH_CREDIT_AMOUNT | Numeric, right justified, zero filled | 20 45 and 64 | -- | Yes | -- | |||||||||||||
| 8 | TOTAL_NUMBER_OF_BATCH_DEBIT_TRANSACTIONS | Numeric, right justified, zero filled | 8 65 and 72 | -- | Yes | -- | |||||||||||||
| 9 | TOTAL_BATCH_DEBIT_AMOUNT | Numeric, right justified, zero filled | 20 73 and 92 | -- | Yes | -- | |||||||||||||
| 10 | NET_BATCH_AMOUNT | Alphanumeric, uppercase, two decimal places implied, right justified, zero-filled, signed positive or negative | 20 93 and 112 | TOTAL_BATCH_CREDIT_AMOUNTTOTAL_BATCH_DEBIT_AMOUNT | Yes | For US dollar (USD) and Canadian dollar (CAD) transactions, two decimal places are implied. An uppercase alpha code replaces the last digit in the transaction. This code indicates a debit amount. The debit codes and their numeric equivalents are:
| |||||||||||||
| 11 | FILLER | Alphanumeric | 8 113 and 2000 | Character spaces | Yes | Reserved for PayPal internal use. |
Submission file trailer
The full file contains only one file trailer. The file trailer corresponds to the submission file header.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | SFTR001 | Yes | Corresponds to the record type and must be the first item in the record. The SFTR001 constant indicates a header record. | |||||||||||||
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled | 8 8 and 15 | 00000001 | Yes | Contains a record sequence number to monitor the integrity and continuity of data in a file. The header record is always set to 00000001. Each subsequent record must be incremented to the RECORD_NUMBER value in the preceding record plus 1.The number of records per file must not exceed 99999999. | |||||||||||||
| 3 | CLIENT_ID | Alphanumeric, uppercase, left justified, character space filled | 11 16 and 26 | -- | Yes | Unique PayPal-assigned ID. | |||||||||||||
| 4 | FILE_DIRECTION | Alphanumeric, uppercase, left justified, character space filled | 1 27 and 27 | -- | Yes | Direction in which to send the submission file:
| |||||||||||||
| 5 | FILE_REFERENCE_NUMBER | Alphanumeric, uppercase, left justified, character space filled | 12 28 and 39 | System-generated file reference number, unique across PayPal | Yes | Contains a submitter-specified file reference number. Can be used to track this file. Value must be unique for each submitted file. A file identification and tracking cross-reference to the corresponding File Validation Report. | |||||||||||||
| 6 | FILE_CREATION_DATE | Numeric, CCYYMMDD | 8 40 and 47 | Date the file was created (PST) | Yes | Corresponds to the date when the submitter created the file. The format is CCYYMMDD, where:
20200215 for February 15, 2020. | |||||||||||||
| 7 | FILE_CREATION_TIME | Numeric, HHMMSS (24-hour clock) | 6 48 and 53 | Time the file was created (PST) | Yes | Corresponds to the time when the submitter created the file. The format is HHMMSS, where
143000 for 2:30 PM. | |||||||||||||
| 8 | FILE_VERSION_NUMBER | Alphanumeric | 8 54 and 61 | Version of the File | Yes | Version of the File | |||||||||||||
| 9 | TOTAL_NUMBER_OF_BATCHES | Numeric, right justified, zero filled | 8 62 and 61 | -- | Yes | -- | |||||||||||||
| 10 | TOTAL_NUMBER_OF_FILE_TXNS | Numeric, right justified, zero filled | 8 62 and 69 | Yes | -- | ||||||||||||||
| 11 | TOTAL_NUMBER_OF_FILE_CREDIT_TXNS | Numeric, right justified, zero filled | 8 70 and 77 | -- | Yes | -- | |||||||||||||
| 12 | TOTAL_FILE_CREDIT_AMOUNT | Numeric, right justified, zero filled | 20 78 and 97 | -- | Yes | -- | |||||||||||||
| 13 | TOTAL_NUMBER_OF_FILE_DEBIT_TXNS | Numeric, right justified, zero filled | 8 98 and 105 | -- | Yes | -- | |||||||||||||
| 14 | TOTAL_FILE_DEBIT_AMOUNT | Numeric, right justified, zero filled | 20 106 and 125 | -- | Yes | -- | |||||||||||||
| 15 | NET_FILE_AMOUNT | Alphanumeric, uppercase, two decimal places implied, right justified, zero-filled, signed positive or negative | 20 126 and 145 | Sum of all NET_BATCH_AMOUNTs | Yes | For US dollar (USD) and Canadian dollar (CAD) transactions, two decimal places are implied. An uppercase alpha code replaces the last digit in the transaction. This code indicates a debit amount. The debit codes and their numeric equivalents are:
| |||||||||||||
| 16 | NET_FILE_ABSOLUTE_AMOUNT | Numeric, right justified, zero filled | 20 146 and 165 | NET_FILE_AMOUNT removing the sign | -- | NET_FILE_AMOUNT removing the sign | |||||||||||||
| 17 | PAYMENT_DIRECTION | Alphanumeric, uppercase, left justified, character space filled (if no value) | 1 166 and 166 | -- | Yes | Direction in which to send the submission file:
| |||||||||||||
| 18 | FILLER | Alphanumeric | 1834 167 and 2000 | Character spaces | Yes | Reserved for PayPal internal use. |