Confirmation Report Specification (Open Wallet API)
DOCS
Last updated: Aug 15th, 7:41am
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.
The confirmation report specification contains the status of relevant transactions in the submission file. The response appears on the day after the transmission of the submission file.
Each confirmation file and submission file contains transactions for one financial instrument.
File specifications
The following specifications apply to the confirmation report file:
| Record length | 2000 byte fixed length. |
| File format | UTF-8 encoded. |
| Transmission day and time | Day D+1 before 8 AM PST. |
| File direction | In general, transmitted from partner to PayPal. |
Field specifications
The following specifications apply to the submission report fields:
Confirmation file header
The file contains only one file header.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric and uppercase | 7 1 and 7 | CFHR001 | Yes | Corresponds to the record type and must be the first item in the record. The constant CFHR001 in this field indicates that this is a file header record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, and 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 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 | Echo back from submission file. | Yes | Unique ID assigned by PayPal to its client | |
| 4 | FILE_DIRECTION | Alphanumeric, uppercase, left justified, character space filled (if no value) | 1 27 and 27 | -- | Yes | Direction in which to send the submission file:
| |
| 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) Echo back from submission file. | Yes | Contains a submitter-specified file reference number. Can be used to track this file. Value must be unique for each submitted file. Use this value as a file identification and tracking cross-reference to the file validation report. | |
| 6 | FILE_CREATION_DATE | Numeric, CCYYMMDD | 8 40 and 47 | Date the Confirmation 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 Confirmation 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 Confirmation File | Yes | Version of the File | |
| 9 | SUBMISSION_FILE_TRACKING_NUMBER | Alphanumeric, uppercase, left justified, character space filled (if no value) | 12 62 and 73 | Unique ID to track the submission file from client side (repeated from the ACK File) | Yes | -- | |
| 10 | FILLER | Alphanumeric | 1927 74 and 2000 | Character spaces | Yes | Reserved for PayPal internal use. |
Confirmation batch header
Contains as many batch headers as the submission file contains, sorted by product and wallet brand. Each batch header is echoed back corresponding to the batch header in the submission file.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | CBHR001 | Yes | Corresponds to the record type and must be the first item in the record. The CBHR001 constant indicates a batch header record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, and zero filled (if no value) | 8 8 and 15 | 00000002 | 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 | PRODUCT_ID | Alphanumeric, uppercase, left justified, character space filled (if no value) | 11 16 and 26 | -- | Yes | The unique PayPal-assigned ID for a product. | |
| 4 | WALLET_BRAND | Numeric, right justified, zero filled (if no value) | 3 27 | 29 | 001- PayPal 002-VENMO | Yes | Wallet associated with the specific transaction |
| 5 | FILLER | Alphanumeric | 1971 30 | 2000 | Character spaces | Yes | Reserved for PayPal internal use. |
Confirmation detail primary record
The number of detail primary records matches the number of records in the submission file. Each of these records has a status to indicate if the client accepted or rejected these records.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | CDPR001 | Yes | Corresponds to the record type and must be the first item in the record. The CDPR001 constant indicates a detail primary record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, and 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 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 | REFERENCE_FINANCIAL_INSTRUMENT_ID | Numeric | 15 16 | 30 | Echo back from submission file. | Yes | This is the field that is used to uniquely identify the P2P Pass instrument used for the transaction. It is equivalent to the FPAN in the Card world. |
| 4 | PAYER ID | Alphanumeric | 19 31 | 49 | Echo back from submission file. | Yes | This is the Sender's PayPal account number |
| 5 | TRANSACTION_TYPE | Alphanumeric | 2 50 | 51 | 01= CAPTURE 02=REFUND 03=WITHDRAWALS | Yes | The type of transaction. Depending on the product and file direction, this results in a credit to PayPal or a debit from PayPal. |
| 6 | TRANSACTION_DATE | Numeric, CCYYMMDD | 8 52 | 59 | Echo back from submission file. | Yes | Corresponds to the date when the submitter created the file. The format is CCYYMMDD, where:
20200215 for February 15, 2020. |
| 7 | TRANSACTION_TIME | Numeric, HHMMSS (24-hour clock) | 6 60 | 65 | Echo back from submission file. | 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 | 80 | Echo back from submission file. | 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 | 100 | Echo back from submission file. | Yes | This is a PayPal-generated ID that is sent to Amex for every original transaction API call |
| 10 | REFUND_REFERENCE_KEY | Alphanumeric | 20 101 | 120 | Echo back from submission file. | Conditional | This is a PayPal-generated ID that will sent into Amex for all reverse money movement API calls associated with the original transaction. |
| 11 | APPROVAL_ID | Alphanumeric, left justified, character space filled | 12 121 and 132 | Echo back from submission file. | Yes | This field should contain the same value that was transmitted from the issuer in the original authorization response message. This value must be unique. In cases where an approval code is inapplicable (e.g., credit transactions), this field must be character space filled. | |
| 12 | REFUND_APPROVAL_ID | Alphanumeric, left justified, character space filled | 12 133 | 144 | Echo back from submission file. | Conditional | This field should contain the same value transmitted from the issuer in the refund and reversal response to reverse the original transaction. This value must be unique. In cases where an approval code is inapplicable (e.g., credit transactions), this field must be character space filled. |
| 13 | AMOUNT | Numeric, right justified, zero filled (if no value) | 12 145 and 156 | Echo back from submission file. | 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 | 159 | Echo back from submission file. | 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 | Echo back from submission file. | No | -- | |
| 16 | SEQUENCE NUMBER | Numeric, zero filled if no value | 6 166 and 171 | Echo back from submission file. | No | -- | |
| 17 | CLEARING NUMBER | Numeric, zero filled if no value | 6 172 and 177 | Echo back from submission file. | No | -- | |
| 18 | SETTLEMENT_ID | Alphanumeric | 20 178 | 197 | Echo back from submission file. | No | -- |
| 19 | REFUND_SETTLEMENT_ID | Alphanumeric | 20 198 and 233 | Echo back from submission file. | No | -- | |
| 20 | INSTRUMENT_EXPIRY_DATE | Numeric | 4 218 and 221 | -- | No | -- | |
| 21 | MERCHANT_ID | 1Alphanumeric | 2 222 and 233 | -- | No | -- | |
| 22 | TRANSACTION_STATUS | Alphanumeric | 2 234 and 235 | Status of the transaction submitted in the submission file/Real time SMS (Withdrawals) | Yes | 01 - Transaction approved 02 - Transaction approved | |
| 23 | DECLINED_TRANSACTION_REASON_CODE | Alphanumeric, space filled (if no value) | 5 236 and 240 | Reason for decline if the Transaction status is 'Declined' | Conditional | -- | |
| 24 | FILLER | Alphanumeric | 1760 241 and 2000 | Character spaces | Yes | Reserved for PayPal internal use. |
Confirmation detail associated record
A No record. The primary record may have multiple associated confirmation detail records.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |
|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | CDAR001 | No | Corresponds to the record type and must be the first item in the record. The CDAR001 indicates a detail associated record. | |
| 2 | RECORD_NUMBER | Numeric, right justified, and 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. |
Confirmation batch trailer
Each batch trailer echoes back according to the number of batch trailers in the submission file. Batch trailers 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 | CBTR001 | Yes | Corresponds to the record type and must be the first item in the record. The constant "CBTR001" in this field indicates that this is a Batch Trailer Record | |||||||||||||
| 2 | RECORD_NUMBER | Numeric, right justified, zero filled (if no value) | 7 8 | 14 | 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 | PRODUCT_ID | Alphanumeric, uppercase, left justified, character space filled | 11 15 | 25 | -- | Yes | The unique PayPal-assigned ID for a product. | ||||||||||||
| 4 | WALLET_BRAND | Numeric, right justified, zero filled | 3 26 | 28 | 001- PayPal 002-VENMO | Yes | Wallet associated with the specific transaction | ||||||||||||
| 5 | TOTAL_NUMBER_OF_ACCEPTED_BATCH_TRANSACTIONS | Numeric, right justified, zero filled | 8 29 | 36 | -- | Yes | Total number of accepted 'Detail Primary Records' (DPR001)in this batch | ||||||||||||
| 6 | TOTAL_NUMBER_OF_ACCEPTED_BATCH_CREDIT_TRANSACTIONS | Numeric, right justified, zero filled | 8 37 | 44 | -- | Yes | -- | ||||||||||||
| 7 | TOTAL_ACCEPTED_BATCH_CREDIT_AMOUNT | Numeric, right justified, zero filled | 20 45 | 64 | -- | Yes | -- | ||||||||||||
| 8 | TOTAL_NUMBER_OF_ACCEPTED_BATCH_DEBIT_TRANSACTIONS | Numeric, right justified, zero filled | 8 65 | 72 | -- | Yes | -- | ||||||||||||
| 9 | TOTAL_ACCEPTED_BATCH_DEBIT_AMOUNT | Numeric, right justified, zero filled | 20 73 | 92 | -- | Yes | -- | ||||||||||||
| 10 | NET_ACCEPTED_BATCH_AMOUNT | Alphanumeric, uppercase, two decimal places implied, right justified, zero-filled, signed positive or negative 20 93 | 112 | TOTAL_ACCEPTED_BATCH_CREDIT_AMOUNT - TOTAL_ACCEPTED_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 | 188Alphanumeric | 8 113 | 2000 | Character spaces | Yes | Reserved for PayPal internal use. |
Confirmation file trailer
The full file contains only one file trailer. It corresponds to the file header.
| Position | Field | Type | Length; Start and end positions | Value | Required? | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | RECORD_TYPE | Alphanumeric, uppercase | 7 1 and 7 | CFTR001 | Yes | Corresponds to the record type and must be the first item in the record. The constant "CFTR001" in this field indicates that this is 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 ID assigned by PayPal to its Client | |||||||||||||
| 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 27 and 27 | -- | Yes | System-generated file reference number. Unique across PayPal. Contains a submitter-specified file reference number. Can be used to track this file. Value must be unique for each submitted file. Use this value as a file identification and tracking cross-reference to the file validation report. | |||||||||||||
| 6 | FILE_CREATION_DATE | Numeric, CCYYMMDD | 8 40 | 47 | Date the confirmation 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 | 53 | Time the confirmation 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 | 61 | Version of the File | Yes | Version of the File | ||||||||||||
| 9 | SUBMISSION_FILE_TRACKING_NUMBER | Alphanumeric, uppercase, left justified, character space filled (if no value) | 12 62 | 73 | Unique ID to track the Submission file from Client side (Repeated from the ACK File) | Yes | -- | ||||||||||||
| 10 | TOTAL_NUMBER_OF_BATCHES | Numeric, right justified, zero filled | 8 74 | 73 | Echoed back from Submission File | Yes | -- | ||||||||||||
| 11 | TOTAL_NUMBER_OF_ACCEPTED_FILE_TXNS | Numeric, right justified, zero filled | 8 74 | 81 | -- | Yes | -- | ||||||||||||
| 12 | TOTAL_NUMBER_OF_ACCEPTED_FILE_CREDIT_TXNS | Numeric, right justified, zero filled | 8 82 | 89 | -- | Yes | -- | ||||||||||||
| 13 | TOTAL_ACCEPTED_FILE_CREDIT_AMOUNT | Numeric, right justified, zero filled | 20 90 | 109 | -- | Yes | -- | ||||||||||||
| 14 | TOTAL_NUMBER_OF_ACCEPTED_FILE_DEBIT_TXNS | Numeric, right justified, zero filled | 8 110 | 117 | -- | Yes | -- | ||||||||||||
| 15 | TOTAL_ACCEPTED_FILE_DEBIT_AMOUNT | Numeric, right justified, zero filled | 20 118 | 137 | -- | Yes | -- | ||||||||||||
| 16 | NET_ACCEPTED_FILE_AMOUNT | Alphanumeric, uppercase, two decimal places implied, right justified, zero-filled, signed positive or negative 20 138 | 157 | Sum of all the 'NET_ACCEPTED_BATCH_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:
| |||||||||||||
| 17 | NET_ACCEPTED_FILE_ABSOLUTE_AMOUNT | Numeric, right justified, zero filled | 20 158 | 177 | NET_ACCEPTED_FILE_AMOUNT removing the sign | -- | NET_ACCEPTED_FILE_AMOUNT removing the sign | ||||||||||||
| 18 | PAYMENT_DIRECTION | Alphanumeric, uppercase, left justified, character space filled (if no value) | 1 178 | 178 | -- | Yes | Direction in which the NET_ACCEPTED_FILE_ABSOLUTE_AMOUNT is to be paid
| ||||||||||||
| 19 | FILLER | 182Alphanumeric | 2 179 | 2000 | Character spaces | Yes | Reserved for PayPal internal use. |