Merchant File Upload

Mass merchant upload enables you to board or update multiple merchants using an XML or CSV file. You can also search for uploaded files and view file status reports. Only administrator users can use the merchant file upload feature. Use the following links to download the complete XSD or CSV files:

http://apps.cybersource.com/library/documentation/dev_guides/Universal_Management_Portal/MerchantCommonServiceType.xsd

http://apps.cybersource.com/library/documentation/dev_guides/Universal_Management_Portal/MerchantBoardingTemplate.csv

http://apps.cybersource.com/library/documentation/dev_guides/Universal_Management_Portal/CyberSourceThroughVisaNet.xsd

Guidelines and Assumptions

1	XML and CSV are the supported file formats.

2	The XML file should conform to the XSDs.

3	The CSV file should conform to the CSV template.

4	Boarding Request ID is a unique identifier and is required in each file.

5	The file should contain a unique merchant ID for each merchant to be boarded.

6	At least one board merchant or update merchant request is required in the file.

7	The update request submitted should have all relevant entity level details populated to update the entity information successfully.

8	The Organization ID, Batch Group, and Processor Name information will be provided by CyberSource, as these are specific for each Reseller.

Field Specifications

N = Numeric

A = Alphanumeric

Table 6

Field Specifications

Field Name	Field Description	Field Length/Data Type	Required/Optional
organizationId	OrganizationID/ResellerID as assigned by CyberSource for the reseller	AN	Required
boardingRequestId	Unique request ID for the service request.	8-36AN	Required
merchantId	Merchant Identifier	6-30AN	Required
name	Merchant Name	25AN	Required. In addition to alphanumeric characters, the following special characters are allowed: space _ + . - * " / ' & , ( ) ! $ ; : ? @ #
emailAddress	Merchant Email Address	30AN	Optional
phone	Merchant Phone	14AN	Required -Phone is allowed for 13 digits, can also accept plus (+) for international along with 13 digits.
Time Zone	Merchant Time Zone	N	Optional
websiteUrl	Merchant Web Site URL	100AN	Optional
firstName	Contact First Name	50AN	Optional (Business Contact is used)
lastName	Contact Last Name	50AN	Optional (Business Contact is used)
emailAddress	Contact Email	50AN	Optional (Business Contact is used)
Phone	Contact Phone	14AN	Optional (Business Contact is used). Phone is allowed for 13 digits, can also accept plus (+) for international along with 13 digits.
processorName	This is provided by CyberSource. Name of the Processor that is being used by the Reseller / Organization.	AN	Required
acquirerCountryCode	Code that identifies the country of the acquiring institution for the merchant. This field is used in all messages related to a customer transaction. The value used in the original transaction must be used in any subsequent messages, including responses.	3N	Required
acquirerFileDestinationBin	BIN (Bank Identification Number) to which the capture file is sent.	6N	Required
acquirerIca	MasterCard assigned BIN for the acquirer.	6N	Optional
acquiringInstitutionId	BIN of the merchant's acquiring financial institution.	11N (Visa assigned BIN values are 6N in length. The maximum length supported by the spec is 11)	Required
acquiringDiscoverInstitutionId	Acquiring Discover Institution ID	11N (Visa assigned BIN values are 6N in length. The maximum length supported by the spec is 11)	Optional - Required for a few processors when Discover Card is selected.
categoryCode	Four-digit code that indicates merchant's type of product or service.	4N	Required
standardIndustryCode	Four-digit code that indicates merchant's type of product or service.	4N	Optional
directConnectProgram	Direct Connect Program	AN	Optional (default->02_DC)
batchGroup	Defines the transaction cutoff time and batch file delivery time for processing batch payment files for payment gateways.	AN	Optional. The batch group value will be provided by CyberSource.
airlineDataEnabled	When enabled, allows merchant to accept airline data in transactions.	Enabled/Disabled/Ignored	Optional
quasiCashEnabled	When enabled, allows merchant to process quasi-cash transactions.	true/false	Optional
partialAuthEnabled	When enabled, allows merchant to send partial authorization transactions.	true/false	Optional
interchangeOptimization Enabled	When enabled, ensures the best rate possible for the merchant's transactions.	true/false	Optional
verificationValue	Ten-digit number that identifies merchant participating in Select Merchant Fee (SMF) programs. This number is unique to each merchant.	10N	Optional
splitShipmentEnabled	When enabled, allows merchant to split an order into multiple shipments with multiple captures.	true/false	Optional
transactionRefNumber Enabled	Transaction Reference Number required for transactions.	true/false	Optional
paymentType	Payment card types supported by CyberSource Through VisaNet Processors - VISA, MasterCard, JCB, Discover, American Express, Diners Club.	N	Required
currencyCode	Currency code combination with paymentType	N	Required
processorValue	Processor Merchant IDs	15 AN	Required
paymentType	Payment card types supported by CyberSource Through VisaNet Processors -VISA, MasterCard, JCB, Discover, American Express, and Diners Club.	N	Required
currencyCode	Currency code combination with paymentType	N	Required
processorValue	Processor Terminal IDs	8	AN Required
type	Product Type	N	Required - Currently, it is Virtual_Terminal.
profileId	Profile ID that was registered with UMP application.	AN	Required
profileName	Profile Name	5-100AN	Required
profileDescription	Profile Description	5-250AN	Required
addressLine1	First line of merchant street address.	60AN	Required
addressLine2	Second line of merchant street address.	60AN	Optional
City	Merchant City	25AN	Required
State/Province	Merchant State or Province	AN	Conditional (required for USA, Canada, and Australia)
postalOrZipCode	Merchant Postal or Zip code	14AN	Conditional (required for USA, Canada, and Australia)
Country	Merchant Country	N	Required

Response Status Codes

The table below contains specific response status codes and their descriptions.

Table 7

Response Status Codes

Message	Description
Failed	An error occurred while processing the request.
In Progress	Request processing is in progress.
Partial Success	Some of the merchants in the request were processed but others had errors.
Pending	The request is pending due to an issue and will continue after some time.
Successful	The request was successfully processed.

Error Codes

When failures occur during request processing, the response XML provides the information necessary in order to explain the cause of the failure, including the error code and error description.

An error code range is defined based on components like errors in the merchant information, processor information, user details, product settings, and admin and contact details. Each component maps to a different range of error codes.

System- and database-related errors are included in a different range.

Table 8

Error Code Ranges

Error Code Range	Error Description
E1001 - E2000	Errors in the merchant information.
E2001 - E3000	Errors in the merchant contact and administrator information.
E3001 - E4000	Errors in the processor information.
E4001 - E5000	Errors in the product settings information.
E5001 - E6000	System and database errors.

Specific Error Codes and Descriptions

The table below contains specific error codes and their descriptions.

Table 9

Error Codes

Error Code	Description
E1001	Merchant Name is required.
E1002	Merchant Name can accept alphanumeric characters, spaces, and some special characters.
E1003	Merchant Name cannot exceed 25 characters.
E1004	Merchant Address is required.
E1005	Merchant Address can accept only alphanumeric characters and spaces.
E1006	Merchant Address cannot exceed 60 characters.
E1007	Merchant Address 2 can accept only alphanumeric characters and spaces.
E1008	Merchant Address 2 cannot exceed 60 characters.
E1009	Merchant City is required.
E1010	Merchant City can accept only alphanumeric characters and spaces.
E1011	Merchant City cannot exceed 13 characters.
E1012	Merchant State or Province can contain only alphanumeric characters.
E1013	Merchant State specified is not present in the allowed US states list.
E1014	Merchant Postal Code does not meet the postal code standard of the specified country.
E1015	Merchant Country is required.
E1016	Merchant Country can contain only alphanumeric characters.
E1017	Merchant Country is three characters.
E1018	Merchant Country specified is not present in the allowed countries list.
E1019	Merchant Phone Number is required.
E1020	Merchant Phone Number does not meet the phone number standard.
E1021	Merchant email address is not in the correct format.
E1022	Merchant email address cannot exceed 30 characters.
E1023	Merchant Time Zone is required.
E1024	Merchant Time Zone is not present in the allowable time zone list.
E1025	Merchant ID <value> is already in use.
E1026	Account ID <value> is already in use.
E1027	Merchant ID format is invalid: <value>
E1028	Merchant ID <value> not found.
E1029	Merchant is already activated.
E1030	Company configuration already exists for profile <value>.
E1031	Merchant mapping already exists for platform <value>.
E1032	Attempted to add a duplicate merchant profile using profileId <value>.
E1033	Merchant URL is invalid.
E1034	Merchant URL cannot exceed 13 characters.
E1035	Invalid merchant status.
E1036	Invalid transition of Merchant status from <value> to <value>.
E1037	System Error while performing update for merchant information.
E1038	Merchant ID is required.
E1039	Merchant ID cannot exceed 30 characters.
E1040	Merchant ID can contain only alphanumeric characters and underscores.
E1041	Merchant ID not found.
E1042	Boarding Request ID is required.
E1043	Boarding Request ID must be between eight and 36 characters.
E1044	Boarding Request ID can contain only alphanumeric characters and hyphen.
E2001	Contact First Name is required.
E2002	Contact First Name cannot exceed 50 characters.
E2003	Contact Last Name is required.
E2004	Contact Last Name must be between two and 50 characters.
E2005	Contact Email Address is required.
E2006	Contact Email Address is not in the correct format.
E2007	Contact Email cannot exceed 100 characters.
E2008	Contact Phone Number is required.
E2009	Contact Phone Number does not meet the phone number standard.
E2010	Business information was not found for profile <value>.
E2011	Company configuration already exists for profile <value>.
E2012	System Error while performing update for contact information.
E2013	Business contact information is required.
E3001	<value> is not a valid attribute name for processor <value>.
E3002	<value> is not a valid processor name.
E3003	The processor type <value> is not a supported processor for the <value> gateway platform.
E3004	The solution type <value> is not supported in this context.
E3005	Merchant ID <value> was not boarded with solution type <value>.
E3006	More than one active processor has been specified for merchant ID <value>.
E3007	<value> processor configuration already exists for profile <value>.
E3008	Processor configuration was not found for profile <value>.
E3009	Multiple configurations for processor <value> are not supported.
E3010	<value> is not a valid attribute name for a miscellaneous configuration item.
E3011	Invalid currency code.
E3012	Invalid payment type.
E3013	Processor Name is required.
E3014	Processor Name is not valid.
E3015	At least one merchant ID is required for a Visa payment type.
E3016	At least one merchant ID is required for a Visa payment type.
E3017	Merchant ID for <value> currency with payment type <value> should have a minimum of 2 characters.
E3018	Merchant ID for <value> currency with payment type <value> cannot exceed <value> characters.
E3019	Merchant ID for <value> currency with payment type <value> can contain only alphanumeric characters.
E3020	Terminal ID for <value> currency with payment type <value> should have a minimum of two characters.
E3021	Terminal ID for <value> currency with payment type <value> cannot exceed <value> characters.
E3022	Terminal ID for <value> currency with payment type <value> can contain only alphanumeric characters.
E3023	<value> is a required field.
E3024	Not a valid value for field <value>.
E3025	<value> can contain only numbers.
E3026	<value> can contain only alphanumeric characters.
E3027	<value> cannot exceed 1 characters.
E3028	<value> should have a minimum of 1 character(s).
E3029	System Error while performing update for processor information.
E4001	Profile Name is required.
E4002	Profile Name cannot exceed 100 characters.
E4003	Profile Name does not exist.
E4004	Profile Description cannot exceed 250 characters.
E4005	System Error while performing update for products.
E5001	Database error updating <value> with <value>.
E5002	Account Boarding on Cybs failed for Profile ID <value> using Account ID <value>.
E5003	Merchant Boarding on Cybs failed for Profile ID <value> using Merchant ID <value>.
E5004	Merchant Activation on Cybs failed for Profile ID <value> using Merchant ID <value>.
E5005	Generic System Error during merchant update.
E7001	Invalid request identifier in the URL. Verify and resubmit the request.
E7002	Request is being processed. Check back later.
E7003	Duplicate boarding request Id. Correct and submit the request again.
E7004	Request does not contain xml payload. Correct and submit the request again.

Boarding Multiple Merchants

XML and CSV are the supported file formats for the file upload.

 

Step 1

From the Merchants drop-down menu, choose Merchant File Upload.

Step 2

On the Upload Files tab, click Browse.

Step 3

Navigate to the merchant file.

Step 4

Click Upload.

The file is uploaded. The upload status of the file appears in the File Upload History table.

 

Updating Multiple Merchants

XML and CSV are the supported file formats for the file upload.

 

Step 1

From the Merchants drop-down menu, choose Merchant File Upload.

Step 2

On the Upload Files tab, click Browse.

Step 3

Navigate to the merchant file.

Step 4

Click Upload.

The file is uploaded. The upload status of the file appears in the File Upload History table.

 

Downloading XML or CSV Detail Report

 

Step 1

From the Merchants drop-down menu, choose Merchant File Upload.

Step 2

In the File Upload History table, click the link for the detail report that you want to download.

 

The Detail Report can also be downloaded from the Search Results on the Find Files tab.

 

Searching for Mass Boarding Files

 

Step 1

From the Merchants drop-down menu, choose Merchant File Upload.

Step 2

On the Find Files tab, enter your search criteria. You can search by Boarding Request ID, File Status, Uploaded By, and Upload Date.

Step 3

Click Search.

The file(s) matching your search criteria are displayed in the Search Results.