Simple Order API Fields
Formatting Restrictions
Unless otherwise noted, all of the field names listed are case sensitive, and the fields accept special characters, such as @, #, and %.
* 
The values of the item_#_ fields must not contain carets (^) or colons (:) because these characters are reserved for use by CyberSource services. The values of all request fields must not contain new lines or carriage returns. However, they can contain embedded spaces and any other printable characters. All leading and trailing spaces will be removed.
Data Type Definitions
For more information about these data types, see the World Wide Web Consortium (W3C) XML Schema Part 2: Datatypes specification:
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
■
Integer—Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}.
■
String—Sequence of letters, numbers, spaces, and special characters, such as @ and #.
Request Fields
See Getting Started with CyberSource Advanced for the Simple Order API for information on how name-value pair names relate to their corresponding XML element names.
Table 4
Request Fields for the Simple Order API 
Request Field
Description
Required (R) or Optional (O)
Data Type & Length
bankInfo_bankCode
Code used to identify the customer’s bank.
If the BBAN is included, the bankInfo_bankCode field and the bankInfo_branchCode field are required if the billTo_country value is FR (France).
If the BBAN is included, the bankInfo_bankCode field is required if the billTo_country value is one of the following:
■
AT: Austria
■
CY: Cyprus
■
DE: Germany
■
ES: Spain
■
FI: Finland
■
GB: Great Britain
■
GR: Greece
■
IE: Ireland
■
IT: Italy
■
MC: Monaco
■
MT: Malta
■
PT: Portugal
■
SI: Slovenia
■
SK: Slovakia
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (10)
bankInfo_branchCode
Code used to identify the branch of the customer’s bank when you are not using the IBAN.
If the BBAN is included, the bankInfo_bankCode field and the bankInfo_branchCode fields are required if the billTo_country value is FR (France).
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (10)
bankInfo_country
Country in which the bank is located. Possible values are the two-character ISO Standard Country Codes for the countries listed in Supported Countries.
Validate (R)
Direct Debit (R for standalone direct debits. O for follow-on direct debits.)
Refund (R for standalone refunds. O for follow-on refunds.)
String (2)
bankInfo_swiftCode
Bank’s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC).
Note Required when including the IBAN. See SEPA Direct Debit Services.
Validate (See description)
Direct Debit (See description)
Refund (See description)
String
(11)
billTo_city
City for the billing address.
Validate (R)
Direct Debit (R for standalone direct debits. O for follow-on direct debits.)
Refund (R for standalone refunds. O for follow-on refunds.)
String (20)
billTo_country
Country for the billing address. Possible values are the two-character ISO Standard Country Codes.
Validate (R)
Direct Debit (R)
Refund (R)
String (2)
billTo_email
Customer’s email address including the full domain name.
Example: jdoe@example.com
Validate (R)
Direct Debit (R for standalone direct debits. O for follow-on direct debits.)
Refund (R for standalone refunds. O for follow-on refunds.)
String (50)
billTo_firstName
Customer’s first name. The size of the billTo_firstName and billTo_lastName fields combined cannot exceed 27 characters.
Validate (R)
Direct Debit (R)
Refund (R)
String (See description)
billTo_lastName
Customer’s last name. The size of the billTo_firstName and billTo_lastName fields combined cannot exceed 27 characters.
Validate (R)
Direct Debit (R)
Refund (R)
String (See description)
billTo_postalCode
Postal code for the billing address. The postal code must consist of 5 to 9 digits.
If the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
Validate (R if billTo_country is US or CA)
Direct Debit (R if billTo_country is US or CA)
Refund (R if billTo_country is US or CA)
String (10)
billTo_state
State for the billing address. Required if billTo_country value is U.S. or Canada. Otherwise optional. Possible values are the State, Province, and Territory Codes for the United States and Canada.
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (2)
billTo_street1
Street address for the billing address.
Validate (R)
Direct Debit (R for standalone direct debits. O for follow-on direct debits.)
Refund (R for standalone refunds. O for follow-on refunds.)
String (30)
billTo_street2
Additional street address information for the billing address.
Validate (O)
Direct Debit (O)
Refund (O)
String (28)
directDebitRefundService_directDebitRequestID
The requestID value returned from a previous request for the directDebitService service. Providing this information creates a follow-on direct debit refund and reduces the number of API fields you must provide. For more information about follow-on services, see Getting Started with CyberSource Advanced for the Simple Order API.
Refund (R for follow-on refunds. Not used for standalone refunds.)
String (26)
directDebitRefundService_directDebitRequestToken
The requestToken value returned from a previous request for the directDebitService service.
The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.
For more information about request tokens, see Getting Started with CyberSource Advanced for the Simple Order API.
Refund (O for follow-on refunds. Not used for standalone refunds.)
String (256)
directDebitRefundService_run
Flag indicating whether or not to include the directDebitRefundService service in your request. Possible values:
■
true: include the service in your request.
■
false (default): do not include the service in your request.
Refund (R)
String (5)
directDebitService_mandateAuthenticationDate
The date of when the mandate was authenticated. The format is yyyymmdd
See Direct Debit Mandate Lodgement.
Direct Debit (See description)‘
Numeric (8)
directDebitService_mandateID
The identification reference for the direct debit mandate.
See Direct Debit Mandate Lodgement.
Direct Debit (See description)
String (35)
directDebitService_recurringType
Indicates whether the direct debit is the first or last direct debit associated with the direct debit mandate, or one in between. The possible values are:
■
1: first direct debit associated with this mandate.
■
2: subsequent direct debit(s) associated with this mandate.
■
3: last direct debit associated with this mandate.
■
5: new direct debit mandate. See Direct Debit Mandate Lodgement.
■
6: cancel the direct debit mandate.
■
7: change the direct debit mandate from manual to electronic.
Direct Debit (See description)
Numeric (1)
directDebitService_run
Flag indicating whether or not to include directDebitService in your request. Possible values:
■
true: include the service in your request.
■
false (default): do not include the service in your request.
Direct Debit (R)
String (5)
directDebitService_validateRequestID
The requestID value returned from a previous request for the directDebitValidateService service. Providing this information creates a follow-on direct debit and reduces the number of API fields you must provide. For more information about follow-on services see Getting Started with CyberSource Advanced for the Simple Order API.
Debit (R for follow-on direct debits. Not used for standalone direct debits.)
String (26)
directDebitService_validateRequestToken
The requestToken value returned from a previous request for the directDebitValidateService service.
The field is an encoded string that contains no confidential information, such as an account number or card verification number. The string can contain a maximum of 256 characters.
For more information about request tokens, see Getting Started with CyberSource Advanced for the Simple Order API.
Debit (O for follow-on direct debits. Not used for standalone direct debits.)
String (256)
directDebitValidateService_run
Flag indicating whether or not to include the directDebitValidateService service in your request. Possible values:
■
true: include the service in your request.
■
false (default): do not include the service in your request.
Validate (R)
String (5)
fundTransfer_accountNumber
Customer’s bank account number. If this value consists of more than 16 digits, the request will fail.
Validate (R)
Direct Debit (See description)
Refund (R for standalone refunds. O for follow-on refunds.)
String (16)
fundTransfer_bankCheckDigit
Code used to validate the customer’s account number. Required for France. Not used in other countries.
Validate (R for France.)
Direct Debit (R for France.)
Refund (R for France.)
String (2)
fundTransfer_iban
International Bank Account Number (IBAN.)
See SEPA Direct Debit Services.
 
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (34)
item_#_productCode
Type of product. This value is also used to determine the product category (electronic, handling, physical, service, or shipping). The default value is default. See Product Codes for the valid values.
If you set this field to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_quantity, item_#_productName, and item_#_productSKU fields are required.
For more information about required item-level fields, see Getting Started with CyberSource Advanced for the Simple Order API.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
item_#_productName
Product’s name. Required if item_#_productCode is not default, stored_value, or one of the values related to shipping or handling.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
item_#_productSKU
Product identifier code. Required if item_#_productCode is not default, stored_value, or one of the values related to shipping or handling.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
item_#_quantity
Quantity of the product being purchased. The default is 1. Required if item_#_productCode is not default, stored_value, or one of the values related to shipping or handling.
Validate (O)
Direct Debit (O)
Refund (O)
Integer (10)
item_#_taxAmount
Tax amount associated with this item. The field is additive. For example, if you send one item including the unitPrice field of 10.00 and the taxAmount field of 0.80, and you send another item with the unitPrice field of 20.00 and the taxAmount field of 1.60, the total amount authorized will be for 32.40, not 30.00 with 2.40 of tax included.
The item_#_unitPrice field and the item_#_taxAmount field must be in the same currency.
If you include the item_#_taxAmount field, and you also include the taxService service in your request, the taxService service will not calculate tax for the item. Instead, it will return the value in the item_#_taxAmount field.
Validate (O)
Direct Debit (O)
Refund (O)
String (15)
item_#_unitPrice
Per-item price of the product. You must include either this field or purchaseTotals_grandTotalAmount in your request. This value cannot be negative. See the information about items and grand totals in Getting Started with CyberSource Advanced for the Simple Order API.
You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated to the correct number of decimal places.
Validate (See description)
Direct Debit (See description)
Refund (See description)
Integer (12)
linkToRequest
Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the Simple Order API.
Direct Debit (O)
String (26)
merchantID
Your CyberSource merchant ID.
Validate (R)
Direct Debit (R)
Refund (R)
String (30)
merchantReferenceCode
Merchant-generated order reference or tracking number.
Important Do not use the following punctuation symbols in this value: pipe (|), caret (^), percent symbol (%), backslash (\), forward slash (/).
Validate (R)
Direct Debit (R)
Refund (R)
String (22)
orderRequestToken
The request token value returned from a previous request. This value links the previous request to the current follow-on request. This field is an encoded string that does not contain any confidential information, such as account numbers or card verification numbers. The string can contain a maximum of 256 characters.
For more information about request tokens, see Getting Started with CyberSource Advanced for the Simple Order API.
Debit (O for follow-on direct debits. Not used for standalone direct debits.)
Refund (R for follow-on refunds. Not used for standalone refunds.)
String (256)
prenoteTransaction
Indicates whether the merchant intends to perform a pre-note transaction and to forward mandate information to the issuer. The possible values are:
■
true: include pre-note transaction in your request.
■
false: do not include pre-note transaction in your request.
This field is optional for standalone direct debit with BBAN requests. It is not used in other requests. If you include the prenoteTransaction field in your request, you must also include the purchaseTotals_grandTotalAmount field in your request and set the value to 0.
Note Based on the BACS Automated Direct Debit Instruction Service (AUDDIS), U.K. merchants have to lodge the mandate ID prior to a direct debit deposit. The process requires the biller to send a pre-notification to the payer at least five calendar days before collecting the payment. See UK Domestic Direct Debits (BACS)
Direct Debit (See description)
 
String (5)
purchaseTotals_currency
Currency used for the order. Possible values are the ISO Standard Currency Codes for the currencies listed in Supported Countries.
Validate (R)
Direct Debit (R)
Refund (R)
Integer (3)
purchaseTotals_grandTotalAmount
Grand total for the order. You must include either this field or item_#_unitPrice in your request. For more information about items and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
Note If you include the prenoteTransaction field in your request, you must also include this field in your request and set the value to 0.
Validate (See description)
Direct Debit (See description)
Refund (See description)
Integer (12)
shipTo_city
City to which the product will be shipped.
Direct Debit (R if any shipTo_ fields are included in the request.)
String (20)
shipTo_country
Country to which the product will be shipped. Possible values are the two-character ISO Standard Country Codes.
Direct Debit (O)
String (2)
shipTo_firstName
First name of the person receiving the product. The size of shipTo_firstName and shipTo_lastName fields combined cannot exceed 27 characters.
Direct Debit (O)
String (60)
shipTo_lastName
Last name of the person receiving the product. The size of shipTo_firstName and shipTo_lastName fields combined cannot exceed 27 characters.
Direct Debit (O)
String (60)
shipTo_postalCode
Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
If the shipping country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If the shipping country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
Direct Debit (R if shipTo_country is US or CA)
String (10)
shipTo_state
State or province to which the product will be shipped. Required if shipTo_country=US or CA.Possible values are the State, Province, and Territory Codes for the United States and Canada.
Direct Debit (See description)
String (2)
shipTo_street1
First line of the address to which the product will be shipped.
Direct Debit (R if any shipTo_ fields are included in the request.)
String (28)
shipTo_street2
Second line of the address to which the product will be shipped.
Direct Debit (O)
String (28)
voidService_voidRequestID
Request ID of the direct debit or direct debit refund you want to void.
Void (R)
String (26)
Reply Fields
 
Table 5
Reply Fields for the Simple Order API 
Reply Field
Description
Returned By
Data Type & Length
decision
Summary of the result for the overall request. Possible values:
■
ACCEPT
■
ERROR
■
REJECT
Validate
Direct Debit
Refund
String (6)
directDebitRefundReply_amount
Amount of the direct debit refund.
Refund
String (15)
directDebitRefundReply_processorResponse
Response code from the processor.
Refund
String (10)
directDebitRefundReply_reasonCode
Numeric value that indicates the result of the direct debit refund request. See Reason Codes, for the possible values.
Refund
Integer (5)
directDebitRefundReply_reconciliationID
Reference number you can use to reconcile the transaction.
Refund
String (22)
directDebitRefundReply_requestDateTime
Time the direct debit refund was requested. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2006-08-11T22:47:57Z is equal to August 11, 2006, at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), also known as Greenwich Mean Time.
Refund
String (20)
directDebitReply_amount
Amount of the direct debit.
Direct Debit
String (15)
directDebitReply_processorResponse
Response code from the processor.
Direct Debit
String (10)
directDebitReply_reasonCode
Numeric value that indicates the result of the direct debit request. See Reason Codes, for the possible values.
Direct Debit
Integer (5)
directDebitReply_reconciliationID
Reference number you can use to reconcile the transaction.
Direct Debit
String (22)
directDebitReply_requestDateTime
Time the direct debit was requested. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2006-08-11T22:47:57Z is equal to August 11, 2006, at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), also known as Greenwich Mean Time.
Direct Debit
String (20)
directDebitValidateReply_amount
The amount sent in the direct debit validate request in either the item_#_unitPrice or purchaseTotals_grandTotalAmount fields.
Validate
String (15)
directDebitValidateReply_bankSwiftCode
Bank’s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC).
Validate
String
(11)
directDebitValidateReply_iban
International Bank Account Number (IBAN).
Validate
String (34)
directDebitValidateReply_processorResponse
Response code from the processor.
Validate
String (10)
directDebitValidateReply_reasonCode
Numeric value that indicates the result of the direct debit validate request. See Reason Codes, for the possible values.
Validate
Integer (5)
directDebitValidateReply_reconciliationID
Reference number you can use to reconcile the transaction.
Validate
String (22)
directDebitValidateReply_requestDateTime
Time the direct debit validate was requested. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2006-08-11T22:47:57Z is equal to August 11, 2006, at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), also known as Greenwich Mean Time.
Validate
String (20)
invalidField_0...N
Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end- user interaction. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API.
Validate
Direct Debit
Refund
String (100)
merchantReferenceCode
Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters.
Validate
Direct Debit
Refund
String (50)
missingField_0...N
Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API.
Validate
Direct Debit
Refund
String (100)
purchaseTotals_currency
Currency used for the order. Possible values are the ISO Standard Currency Codes for the currencies listed in Supported Countries.
Validate
Direct Debit
Refund
String (5)
reasonCode
Numeric value that indicates the result of the overall request. See Reason Codes, for the possible values.
Validate
Direct Debit
Refund
Integer (5)
requestID
Identifier for the request.
Validate
Direct Debit
Refund
String (26)
requestToken
Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account or card verification number. The string can contain a maximum of 256 characters.
For more information about request tokens, see Getting Started with CyberSource Advanced for the Simple Order API.
Validate
Direct Debit
Refund
String (256)
voidReply_amount
Total amount of the void.
Void
Decimal (15)
voidReply_currency
Currency used for the transaction. Possible values are the ISO Standard Currency Codes for currencies.
Void
Integer (3)
voidReply_reasonCode
Numeric value that indicates the result of the overall request. See Reason Codes, for the possible values.
Void
Integer (5)
voidReply_requestDateTime
Time at which the void was requested in UTC. See Data Type Definitions, for the field’s format.
Void
Date and time (20)
Reason Codes
The codes in the following table give the results of your Simple Order API request. They are returned in the reasonCode and <service>_reasonCode reply fields.
* 
Because CyberSource can add reply fields and reason codes at any time, proceed as follows:
■
You should parse the reply data according to the names of the fields instead of their order in the reply. For more information on parsing reply fields, see the documentation for your client.
■
Your error handler should use the decision field to obtain the result if it receives a reason code that it does not recognize.
Table 6
Reason Codes for the Simple Order API  
Reason Code
Description
100
Successful transaction.
102
One or more fields in the request contains invalid data.
Possible action: See the reply fields invalidField_0...N for which fields are invalid. Resend the request with the correct information.
150
Error: General system failure.
See the documentation for your CyberSource client for information about how to handle retries in the case of system errors.
203
Error: General decline of the account. No other information provided by the processor or the bank.
Possible action: Request a different account number or other form of payment.