|
|
|
|
|
|
Introduction to Batch Request Processing
This chapter describes how to use CyberSource’s batch request processing system.
Overview of Batch Request Processing
Batch request processing allows you to send a single file to CyberSource with a group of ICS service requests instead of sending individual requests for online transmission. You may want to use a batch file if it fits your implementation better than sending individual requests.
At any time during the day, you can create and send a batch request file to CyberSource according to the file format and transmission protocol discussed in this document. The information that you provide for each request in the batch is the same information that you provide for an individual service request. We read the file, validate the file’s syntax, and send you an email indicating whether the file passed the syntax validation (see Batch Receipt Response for more information). If the file passes, we create a separate ICS request for each transaction and insert the information into our database. We then send the information to the respective processor(s) according to our normal processor batch schedule.
Unlike with most processors, with CyberSource you only need to create one batch file. You can include transactions that use different currencies, countries, merchant IDs, and card types in a single file, eliminating the burden of tracking these separately. You can also include requests for different ICS services in the same file. For example, you can include authorization, capture, and credit transactions in one file. You may include a capture and credit for the same order in a single file, but if you do, the credit must be a stand-alone credit. This means you must provide the customer’s name, billing address, and credit card information in that credit request record.
Most of the ICS services can be accessed by using a batch request file. These are the services that you may not request in a batch file:
• Credit card authorization reversal (ccAuthReversalService)
• Payer authentication enrollment check (payerAuthEnrollService)
• Bank transfer (bankTransferService)
• PayPal payment (payPalPaymentService) and credit (payPalCreditService)
Currently you may send batch request files in CSV format only. The format for the batch file consists of:
• A file header, followed by a blank line
• A data header, followed by a new line
• One or more data records, each separated by a new line
• A trailer record indicating the end of the file
Each section of the file is described below.
The file follows CSV field formatting rules. Use quotation marks (") to enclose any field that contains a comma. For example:
"reference=UK office, John Smith"
The file header consists of comma-separated name-value pairs using the fields listed below.
|
Field Name |
Description |
Required or Optional |
|---|---|---|
|
merchantID |
Your CyberSource merchant ID. If you are using multiple merchant IDs in the batch file, use the main merchant ID here (see Using Multiple Merchant IDs for more information). |
Required |
|
batchID |
Batch identifier that you assign (alphanumeric, maximum 8 characters). The batch ID must be unique. |
Required |
|
creationDate |
Creation date of the file. Use format YYYY-MM-DD. |
Optional |
|
recordCount |
The total number of data records in the file. |
Required |
|
reference |
Your reference notes for the batch. |
Optional |
|
statusEmail |
Email address or alias where CyberSource sends the file receipt notification (see Batch Receipt Response). |
Required |
|
targetAPIVersion |
CyberSource updates the ICS transaction API periodically. When you request an ICS service by using the Simple Order API, you must specify which version of the API you want to use. We suggest that you set this field to the same value that you configure your CyberSource ICS client to use (this is the client you use to send individual ICS requests). To determine the latest API version available, go to https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/ At the time of this guide’s publication, the latest API version is 1.12. IMPORTANT Make sure to set this value correctly. Setting it to a value that does not exist will prevent your batch file from being processed. |
Required |
In the file header, you may also include any ICS service API fields that will have a constant value throughout the file. For example, if you plan to use only euros as the currency for all of the requests, instead of declaring a column in the data header for purchaseTotals_currency, you can include purchaseTotals_currency=EUR in the file header. Where you place it in the header does not matter. Any field that you include in the header that is not in the list directly above will be treated as an API field.
Example Example of a File Header
merchantID=infodev,batchID=12345,creationDate=2004-09-22,recordCount=3,reference=Additional information,purchaseTotals_currency=EUR,statusEmail=notify@abccorp.com,targetAPIVersion=1.12
You use the data header to declare the CyberSource Simple Order API fields that you want to use for the requests in the file. Use a comma-separated list of the fields. The order in which you list the fields in the data header does not matter. You can include any API field that the ICS service uses. See the Implementation Guide that corresponds to the ICS service for the list of fields the service uses and whether they are required or optional. For example, see the Credit Card Services Implementation Guide for information about authorizations, captures, and credits.
Important Make sure to include all of the fields that the ICS service requires. If any required fields are missing from the data header or file header (for example, if you do not include ccCaptureService_run for all of your capture requests), then all of the requests will be rejected once CyberSource begins processing them.
You may include multiple ICS services in one request (for example, credit card authorization and capture), just as you would with an individual online request.
If you plan to use multiple merchant IDs in a single batch file, include merchantID as one of the API fields in the data header. See Using Multiple Merchant IDs for more information.
CyberSource encourages you to use the purchaseTotals_grandTotalAmount API field even though it is optional for your requests. We use it as part of a check sum to validate whether we received the entire file. See Trailer Record for more information. You do not have to include a value for purchaseTotals_grandTotalAmount for all of the records. If you do not want to include the value for a particular record, leave it blank; do not set it to 0.
As mentioned previously, if you have a required API field that will have a constant value for every request in the file, you can include that API field in the file header instead of including the field in the body of the file itself.
Example Example of a Data Header
A request for the capture service might include these API fields:
• ccCaptureService_run
• ccCaptureService_authRequestID
• purchaseTotals_currency
• merchantReferenceCode
• purchaseTotals_grandTotalAmount
This is the corresponding data header:
ccCaptureService_run,ccCaptureService_authRequestID,purchaseTotals_currency,merchantReferenceCode,purchaseTotals_grandTotalAmount
Each data record consists of a comma-separated list of the values corresponding to the API fields in the data header. The maximum allowable size of the file is 60,000 data records, or 60MB, whichever is smaller. The order of your requests in the file does not matter; requests for different ICS services may be mixed together. Similarly, you can intermix card types and currencies.
Make sure that the first three letters of every data record are not END, as you use END to indicate the trailer record (see below).
The last item in the file is the trailer record, which consists of two required parts:
• The single word END followed by a comma
• SUM: The sum of all of the purchaseTotals_grandTotalAmount values for all of the records in the file. When you calculate the sum, use a positive number for both payments and credits (do not use a negative value for credits), and ignore the fact that you might be using different currencies. If you leave all of the purchaseTotals_grandTotalAmount values blank in the file, then set SUM=0.
For example:
END,SUM=1014.37 (when using purchaseTotals_grandTotalAmount values)
or
END,SUM=0 (when leaving purchaseTotals_grandTotalAmount values blank)
CyberSource encourages you to use the purchaseTotals_grandTotalAmount API field in the records because we use the sum that you provide to validate that we received the entire file. Make sure that the sum you calculate accurately reflects the sum of the values that you have included for the individual records.
If you have multiple CyberSource merchant IDs, you can submit a single batch file that contains requests that use different merchant IDs. To use multiple merchant IDs:
1 Determine which one of your merchant IDs will be your main merchant ID.
2 Contact CyberSource Customer Support with the list of all the merchant IDs you will be using.
Customer Support will configure your account to use multiple merchant IDs.
3 In the file header of the batch file, set the merchantID field to your main merchant ID.
4 In the data header, include merchantID in the list of API fields you will include in the data records.
5 In each data record, set the merchantID field to the specific merchant ID you want to use for that request. If you do not specify a merchant ID in the data record, CyberSource uses the main merchant ID that you specified in the file header.
See Example with Multiple Merchant IDs for an example.
Example Example with Only Captures
merchantID=infodev,batchID=12345,creationDate=2004-09-22,recordCount=3,"reference=UK office, John Smith",statusEmail=notify@abccorp.com,targetAPIVersion=1.12
ccCaptureService_run,ccCaptureService_authRequestID,purchaseTotals_currency,merchantReferenceCode,purchaseTotals_grandTotalAmount
true,1234567891234567,EUR,ABC12320398,327.49
true,1234567891234568,GBP,ABC97611927,187.65
true,1234567891234569,EUR,ABC09177294,499.23
END,SUM=1014.37
Example Example with Both Captures and Credits
This example has the same capture requests as the previous example, but it also includes a credit request for $14.99 (the credit is unrelated to any of the captures in the file). Note that the data header includes additional fields used for credits, and that ccCaptureService_run=false and ccCreditService=true for the credit data record.
merchantID=infodev,batchID=12345,creationDate=2004-09-22,recordCount=4,"reference=UK office, John Smith",statusEmail=notify@abccorp.com,targetAPIVersion=1.12
ccCaptureService_run,ccCaptureService_authRequestID,ccCreditService_run,ccCreditService_captureRequestID,purchaseTotals_currency,merchantReferenceCode,purchaseTotals_grandTotalAmount
true,1234567891234567,false,,EUR,ABC12320398,327.49
true,1234567891234568,false,,GBP,ABC97611927,187.65
true,1234567891234569,false,,EUR,ABC09177294,499.23
false,,true,1234567891999994,CAD,ABC39882097,14.99
END,SUM=1029.36
Example Example with Multiple Merchant IDs
In this example, infodev is the main merchant ID, while infoeast and infowest are additional merchant IDs. The first request defaults to using infodev.
merchantID=infodev,batchID=12345,creationDate=2004-09-22,recordCount=3,"reference=UK office, John Smith",statusEmail=notify@abccorp.com,targetAPIVersion=1.12
ccCaptureService_run,ccCaptureService_authRequestID,purchaseTotals_currency,merchantReferenceCode,purchaseTotals_grandTotalAmount,merchantID
true,1234567891234567,EUR,ABC12320398,327.49,
true,1234567891234568,GBP,ABC97611927,187.65,infoeast
true,1234567891234569,EUR,ABC09177294,499.23,infowest
END,SUM=1014.37
You submit the batch file to CyberSource using HTTPS. The security for the file submission is based on HTTPS and SSL and uses client certificates as part of the SSL handshake. To access the URLs listed below, your client must provide the same client certificate that you use to request regular individual ICS Simple Order API transactions. The client certificate is stored in a PKCS12 file named <merchantID>.p12 and is protected by a single password.
When testing, your client should submit the file to the test URL at https://batchtest.cybersource.com/upload/BatchFileUpload. See Testing for more information about testing your system.
When in production, your client should submit the file to the production URL at https://batch.cybersource.com/upload/BatchFileUpload.
See Chapter 2, Java Sample Code for Uploading Batch Files for more information about how you can upload files to CyberSource.
Once the file has been received, we validate the syntax and send you a confirmation email indicating whether the file passed the validation. You specify in the header of the file the email address or alias where you want the email notifications to be sent. We will send the email notification generally within 30 minutes of batch receipt; however, actual timing depends on system load.
Table 2 lists the possible subject lines of the email notification:
|
Subject Line |
Reason and Remedy |
|---|---|
|
SUCCESS: Batch ID <Batch ID #> - Validation |
The file was received and passed the validation checks. CyberSource will process the requests in the file. No action is required on your part. |
|
ON HOLD: Batch ID <Batch ID #> - Validation |
Reason: The batch ID or the checksum value appears to match the values for another batch file that has already been processed. Remedy: CyberSource will contact you to discuss the file. |
|
FAILED: Batch ID <Batch ID #> - Validation |
Reason: The file did not pass the validation checks. Remedy: Look at the contents of the email and follow the suggested remedy. If you need to resend the file, use the same batch ID that you used for the original file unless otherwise instructed in the email. |
We will not process any of the requests in the batch file if there is any type of syntax error. If multiple records in the file have errors, we will send only one email with the line number of the first failed record.
Examples of typical errors that might occur are:
• CyberSource does not recognize the merchant ID that you specified in the file.
• The recordCount that you specified in the file header does not match the actual number of data records in the file.
• The file is missing the trailer record.
• A specific data record in the file does not have the correct number of fields as specified in the data header (the email will indicate the line number of the problem data record).
Once the batch file is validated, CyberSource begins processing the transactions. Transaction processing time depends on the time of day and the size of your batch. CyberSource’s standard settlement submissions are from midnight to midnight Pacific Time. Be sure to submit your file early enough to allow time for CyberSource to process the batch before the submission deadline.
Once we process all of the requests in the batch, we create two types of CSV-formatted response files that you can use to determine the results of the requests in the batch:
• Full file: This file includes the results for all of the requests in your batch. The file name is <merchantID>.<batchID>.<date batch file received>.reply.all. For example: infodev.12345.20041130.reply.all.
• Exception file: This file only includes results for the requests where decision does not equal ACCEPT. The file name is <merchantID>.<batchID>.<date batch file received>.reply.rejected. For example: infodev.12345.20041130.reply.rejected.
The reports are available in the Reports area of the Enterprise Business Center. You can download them as you download other CyberSource reports (see Additional Reports).
The format for both of the files includes:
• A file header, followed by a blank line
• One or more data records, each separated by a new line
The file header consists of a list of comma-separated name-value pairs, including these fields:
• merchantID
• batchID
• creationDate
• reference
If you included the creationDate and/or reference fields in the batch file header, the fields appear in the response file header with your values.
Example Example Response File Headers
merchantID=infodev,batchID=12345,creationDate=2004-09-22,reference="UK office, John Smith"
The data records provide the API reply information for the requests in the batch file. Each data record consists of a comma-separated list of name-value pairs showing the API reply information for a single request. The name-value pairs can be in any order.
Note The order of the data records in the response file may not necessarily correspond to the order of the requests in the batch file. Use the value of the merchantReferenceCode to link the result in the response file to the corresponding request from the batch file.
Example Example of a Response File
This example shows a full file, including two successful requests and one failed request. The failed request is the second data record in the example (in bold).
merchantID=infodev,batchID=12345,creationDate=2004-09-22,reference="UK office, John Smith"
merchantReferenceCode=ABC12320398,ccCaptureReply_reasonCode=100,reasonCode=100,decision=ACCEPT,ccCaptureReply_reconciliationID=1018546244150167904178,requestID=1018546244150167904178,ccCaptureReply_amount=327.49,ccCaptureReply_requestDateTime=2004-09-23T22:43:53Z;purchaseTotals_currency=EUR
merchantReferenceCode=ABC141854,ccCaptureReply_reasonCode=241,reasonCode=241,decision=REJECT,requestID=1018546227570167904150
merchantReferenceCode=ABC39882097,ccCreditReply_reasonCode=100,reasonCode=100,decision=ACCEPT,ccCreditReply_reconciliationID=1018546230720167904150,requestID=1018546230720167904150,ccCreditReply_amount=14.99,ccCreditReply_requestDateTime=2004-09-23T22:44:33Z;purchaseTotals_currency=CAD
Additional results of processing your requests are available in these CyberSource reports:
• Payment Submission Detail Report: This report shows all payments and credits submitted to your processor(s) for settlement. If your file has an error, the file is not processed, and so the file’s requests do not appear in this report.
• Transaction Detail Report: This report shows all your requests processed by CyberSource, including requests for all ICS service types, and both successful and failed transactions.
You can download these reports daily. See the CyberSource Reporting User’s Guide for general information about CyberSource reports. See the CyberSource Reporting Developer’s Guide for information about report format and downloading. Both guides are available in the services documentation area of the Support Center.
When testing your system, upload your batch file to the test URL and not the production URL. The test URL is https://batchtest.cybersource.com/upload/BatchFileUpload.
You will receive batch receipt emails for your test batch files. You can also download the corresponding batch response files from the Reports area of the test version of the Enterprise Business Center at https://ebctest.cybersource.com.
|
|
|
|
|
|