batch release specification - paypal batch release specification ... bh003 batch header invalid...

Batch Release Specification

Last updated: June 2011


10127.en_US-201106

© 2011 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners.The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349.Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Batch Release Specification 3

1 Batch Release Specification

This supplement details how Release (RL) fields are accommodated into the batch interface.

General Structure of a Batch-Input FileThis section details the structure of a Batch-Input file.The format for all the record types are identical to those listed in the 2.0 Batch Processing File Formats Specification, except for the following:

Batch Footer (BF) includes the following new field: totalReleaseTransactionsCount.File Version (FV) is 4.0.Addition of a new record type for Release called RL.

A batch-input file comprises the following seven record types. The type of each record is indicated by a two-character record-type identifier, followed by other fields. The record types and their identifiers are as follows:

FV — File Version (see “File Version (FV)” on page 4)FH — File Header (see “File Header (FH)” on page 4)BH — Batch Header (see “Batch Header (BH)” on page 4)<Identifier varies by transaction type> — Individual transaction record (see “Transaction Records” on page 4)BF — Batch Footer (see “Batch Footer (BF)” on page 5)FF — File Footer (see “File Footer (FF)” on page 5)CS — Checksum (see “Checksum (CS)” on page 5)

The overall format of the batch file is as follows. Each value must be enclosed in double quotes, and values are separated by a comma. Optional or missing fields are represented by two consecutive commas (no quotes are required).

"FV","4.0" File version"FH",…………… File header (up to 1,000 batch-input files per day)

"BH",……………… Batch #1 header (up to 99 batches per file). Batch #1 transaction records .

"BF",……………… Batch #1 footer"BH",……………… Batch #2 header

.

. Batch #2 transaction records

.

Batch Release SpecificationGeneral Structure of a Batch-Input File

1


"BF",……………… Batch #2 footer.. Other batches.

"FF",………………… File footer"CS","checksumValue" Checksum

File Version (FV)

The File Version optionally identifies the batch-interface version used to process the file. It has the following format: "FV", version

IMPORTANT: The file version is 4.0.

File Header (FH)

There is one File Header per batch-input file. The File Header has the following format:"FH",fileDate,fileSequenceNumber,batchCount,partnerEmailAddress

For the receipt file, the file header will have the following format:"FH",fileDate,fileSequenceNumber,batchCount,partnerEmailAddress,fileHeaderValidationCode

Batch Header (BH)

Each batch file can contain multiple batches, and each batch must start with a Batch Header record. The Batch Header has the following format:"BH",batchID,currencyType,merchantEmailAddress

For the receipt file, the batch header will have the following format:"BH",batchID,currencyType,merchantEmailAddress,batchHeaderValidationCode

Transaction Records

Individual transaction types have a unique record identifier and input fields. The transaction record type supported is Release (RL).


Batch Release SpecificationRelease Transaction Record

1

Batch Footer (BF)

The Batch Footer follows the last input record for each batch. The Batch Footer has the following format:"BF",currencyType,totalCreditTransactionsInBatch,totalCreditTransactionsAmount,totalDebitTransactionsInBatch,totalDebitTransactionsAmount,totalInvoiceItemsCount,totalInvoiceItemsAmount,totalReleaseTransactionsCount

For the receipt file, the batch footer will have the following format:"BF",currencyType,batchFooterValidationCode,totalCreditTransactionsInBatch,totalCreditTransactionsAmount,totalDebitTransactionsInBatch,totalDebitTransactionsAmount,totalInvoiceItemsCount,totalInvoiceItemsAmount,totalReleaseTransactionsCount

Table 1.1 contains descriptions for the new field added:

File Footer (FF)

There is one File Footer for every batch-input file, to balance the File Header. The File Footer has the following format:"FF",batchCount

Checksum (CS)

The checksum guarantees the integrity of the input file. It has the following format:"CS","checksumValue"

Release Transaction RecordThis section lists details about the release transaction record:

1. RL - New line item defined for release transactions.

TABLE 1.1 Batch Footer Input-Record Fields

Field Description

totalReleaseTransactionsCount

Number of release transactions in this batch.Type: numericField Width: 5Required: Yes

Batch Release SpecificationRelease Transaction Record

1


2. Each individual RL line item corresponds to a release transaction request.

– PayPal Transaction ID - The seller-side transaction ID that is returned during the transaction as a response to the Do EC call.

– External Tracking ID - The ID that is sent in during the release request and passed back in the response.


Batch Release SpecificationRelease Record - Request, Receipt, and Results

1

Release Record - Request, Receipt, and ResultsThis section lists the various release record fields. Refer to Table 1.2 for descriptions for the fields.

Release Request Record (RL)ItemNumber,RLToken,PayPalTransactionID,ExternalTrackingID

Release ReceiptItemNumber,RLToken,PayPalTransactionID,ExternalTrackingID, ValidationReturnCode

Release ResultsItemNumber,RLToken,PayPalTransactionID,ExternalTrackingID,CurrencyCode,ReleaseAmount,ResultReturnCode

Release Record Fields

Table 1.2 lists release fields and their descriptions:

TABLE 1.2 Release Fields

Field Description

Item Number Sequence number of this item in the file.Items numbers must be in sequence, and incremented by one from the previous item number. For example, the following item number sequence is incorrect and causes a validation error: 1, 2, 3, 4, 7, 8. Item numbers in a new batch in the same file continue from the last number in the previous batch.Type: NumericField Width: 6Blank: NoRequired: Yes


1


RLToken Release Identifier. It is always set to “RL”.Type: StringField Width: 3Blank: NoRequired: Yes

PayPalTransactionID The seller-side transaction ID that is returned during transaction as a response to the Do EC call.Type: AlphanumericField Width: 19Blank: NoRequired: Yes

ExternalTrackingID The ID that is sent in during the release request and passed back in the response.Type: AlphanumericField Width: 64Blank: NoRequired: No

CurrencyCode Currency code of the release transaction. It must be a three-character ISO currency code. This is an output only field. Type: StringField Width: 3Blank: No

ValidationReturnCode Batch-validation code. This is an output only field.Type: String (starting with BV and followed by a numeric value, such as BV000)Field Width: 16Blank: No

ReleaseAmount Amount of the release transaction. This is an output only field.Type: StringField Width: 45Blank: NoLimitations:

Must not exceed $10,000 USD in any currency. No currency symbol.No thousands separator.Decimal separator must be appropriate to the currency type.

TABLE 1.2 Release Fields (Continued)

Field Description



1

ResultReturnCode RL batch processing result code. This is an output only field.Type: String (starting with RL and followed by a numeric value, such as RL000)Field Width: 16Blank: No

TABLE 1.2 Release Fields (Continued)

Field Description

Batch Release SpecificationRelease (RL) Sample Files

1


Release (RL) Sample FilesThis section includes examples of the following:

Request File SampleReceipt File SampleSuccessful Result File SamplePartially Successful Result File Sample

Request File Sample"FV","4.0""FH","20110309","022","01","[email protected]""BH","01","USD"," [email protected]""1","RL","1582249551076972V","5099695""2","RL","50U09782KM5925051","5826290""3","RL","3X394624BH216770M","3741168""BF","USD","0","0.0","0","0.0","0","0.0","3""FF","01""CS","1C55972E74897F02652EFE1FF5F82CBD"

Receipt File Sample

"FH","20110309","22","1","[email protected]","FS000""BH","1","USD","[email protected]","BS000""1","RL","1582249551076972V","5099695","BV000""2","RL","50U09782KM5925051","5826290","BV000""3","RL","3X394624BH216770M","3741168","BV000""BF","USD","BS000","0","0.00","0","0.00","0","0.00","3""FF","1""CS","29621EB37EBEA990E22C377699E88F40"

Successful Result File Sample"FH","20110309","22","1","[email protected]""BH","1","USD","[email protected]""1","RL","1582249551076972V","5099695","9.41","RL000""2","RL","50U09782KM5925051","5826290","19.21","RL000""3","RL","3X394624BH216770M","3741168","8.63","RL000""BF","USD","0","0.00","0","0.00","0","0.00","3""FF","1""CS","EB52E0F0CDEDD8578730CD24505642E2"



1

Partially Successful Result File Sample"FH","20110319","13","1","[email protected]""BH","1","USD","[email protected]""1","RL","66P623666Y7712030","7762512","","","RL001""2","RL","0TK546043U6479642","4341221","USD","10.11","RL000""3","RL","8W9872372C543384M","7768121","USD","12.43","RL000""BF","USD","0","0.00","0","0.00","0","0.00","2""FF","1""CS","E61278BB84FF71F677315E8EED537080"

NOTE: In case of failed release request, the CurrecyCode and ReleaseAmount will be set to blank.


1


2

Batch Release Specificatio

Error Codes

Validation Error Codes

TABLE 2.1 Validation Error Codes

Error Code Pertains to... Description

BF004 Batch footer Invalid currency type. Currency type mismatch with currency type in Batch Header.

BF006 Batch footer Invalid total credit transaction count for batch

BF007 Batch footer Invalid total debit transaction count for batch

BF008 Batch footer Invalid total credit transaction amount for batch

BF009 Batch footer Invalid total debit transaction amount for batch

BF010 Batch footer Invalid total invoice item count

BF011 Batch footer Invalid total invoice item amount

BF012 Batch footer Invalid total release transaction count

BH003 Batch header Invalid batch ID

BH004 Batch header Invalid currency type

BH005 Batch header Merchant email address does not match allowable set of values

BH006 Batch header Partner permission not available to process the capture

BV001 Transaction Invalid transaction parameter

BV003 Transaction Line number: Not incremental

BV005 Transaction Transaction ID or authorization ID: Invalid

BV006 Transaction Transaction ID required

BV007 Transaction Invalid currency type. Currency type mismatch with currency type in Batch Header.

BV009 Transaction Invalid invoice

BV010 Transaction Invalid refund amount

BV011 Transaction The partial refund amount must be a positive amount.

BV012 Transaction The memo field contains invalid characters.

n 13

Error CodesValidation Error Codes

14

BV026 Transaction Invalid expiration year

BV028 Transaction Invalid amount

BV030 Transaction Invalid soft descriptor

BV031 Transaction Invalid block. Something is wrong in File Header or Batch Header.

BV032 Transaction Partner does not have permissions

BV033 Transaction Invalid shipping company

BV034 Transaction ShippingCompany is required, since TrackingNumber is present

BV035 Transaction Invalid tracking number

BV036 Transaction TrackingNumber is required, since ShippingCompany is present

BV037 Transaction Invalid AID data: one or more invalid fields in AID data (ABR and ALR data)

BV038 Transaction Invalid transaction type

BV039 Transaction Invalid item amount

BV040 Transaction Invalid invoice date

BV041 Transaction Invalid invoice identifier

BV042 Transaction Invalid invoice exchange rate

BV043 Transaction Release ID not found

BV044 Transaction Release amount does not correlate with exchange rate

BV045 Transaction Invalid invoice batch identifier

BV046 Transaction Duplicate invalid ID

BV047 Transaction Invalid invoice transaction currency type

BV048 Transaction Merchant not enabled invoice

BV049 Transaction RF memo not per TDNR standard

BV050 Transaction Invalid invoice withdrawal not supported

CS001 Checksum Missing checksum record

CS002 Checksum Checksum invalid for file

FD001 Entire file This is a duplicate file

FE001 Entire file Empty file

FF002 File footer Invalid batch count

FH003 File footer Invalid file version




Batch

Error CodesValidation Error Codes

FH004 File header Invalid file date

FH006 File header Invalid sequence number

FH008 File header Invalid batch count

FH009 File header Dropbox merchant email address does not match allowable set of values

FI006 Entire file File not found

FI007 Entire file File validation failed

FN001 Filename Missing merchant account ID

FN002 Filename Incorrect transaction type

FN004 Filename Missing request

FN005 Filename Missing year

FN006 Filename Missing month

FN007 Filename Missing day

FN008 Filename Incorrect date

FN009 Filename Missing sequence number

FN010 Filename Incorrect filename extension

FP001 Entire file MerchantID in filename does not match the one in the File Header.

FV001 File version Invalid version number in FV line



Release Specification 15

Error CodesRelease Error Codes

16

Release Error Codes

TABLE 2.2 Release Error Codes

Error Code Description

RL000 Release funds success

RL001 Funds not held

RL002 Invalid transaction ID

RL003 Release funds failed


Batch


Release Specification 17


18

batch release specification - paypal batch release specification ... bh003 batch header invalid...

Documents