SCMP API Fields
Formatting Restrictions
Unless otherwise noted, all of the fields listed are order and case insensitive, and the fields accept special characters, such as @, #, and %.
Request-level and offer-level field names and values must not contain carets (^) or colons (:). However, they can contain embedded spaces and any other printable characters. If you use more than one consecutive space, the extra spaces will be removed.
Data Type Definitions
■
Date and time—The format is YYYY-MM-DDThhmmssZ. For example, 2002-08-11T224757Z is equal to August 11, 2002, at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time.
■
Decimal—Number that includes a decimal point. Examples: 23.45, -0.1, 4.0, 90809.0468.
■
Integer—Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}.
■
Non-negative integer—Whole number greater than or equal to zero {0, 1, 2, 3, ...}.
■
Positive integer—Whole number greater than zero {1, 2, 3, ...}.
■
String—Sequence of letters, numbers, spaces, and special characters, such as @ and #.
Request Fields
 
Table 4
Request-Level Fields for the SCMP API 
Request Field
Description
Required (R) or Optional (O)
Data Type & Length
bank_account_number
Customer’s bank account number. If this value consists of more than 16 digits, the request will fail.
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 (16)
bank_check_digit
Code used to validate the customer’s account number.
Important Required if the billTo_country value is ES (Spain), FR (France), IT (Italy), MC (Monaco), or PT (Portugal).
Validate (See description.)
Direct Debit (See description.)
Refund (See description.)
String (2)
bank_code
Code used to identify the customer’s bank when you are including the BBAN and not the IBAN in the request.
Important 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
Note If the BBAN is included, the bankInfo_bankCode field and the bankInfo_branchCode field are required if the billTo_country value is FR (France).
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (10)
bank_country
Country where 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)
bank_iban
International Bank Account Number (IBAN.)
See SEPA Direct Debits.
Validate (See description)
Direct Debit (See description)
Refund (See description)
String (34)
bank_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 Debits.
Validate (See description)
Direct Debit (See description)
Refund (See description)
String
(11)
bill_address1
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)
bill_address2
Additional street address information for the billing address.
Validate (O)
Direct Debit (O)
Refund (O)
String (28)
bill_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)
bill_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)
bill_state
State for the billing address. Required if bill_country value is US or CA. 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)
bill_zip
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 bill_country is US or CA)
Direct Debit (R if bill_country is US or CA)
Refund (R if bill_country is US or CA)
String (10)
branch_code
Code used to identify the branch of the customer’s bank when you are including the BBAN and not the IBAN in the request.
Important Required if the billTo_country value is ES (Spain), FR (France), GR (Greece), IT (Italy), MC (Monaco), or PT (Portugal).
Note 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)
currency
Currency used for the order. Possible values are the ISO Standard Currency Codes for currencies.
Validate (R)
Direct Debit (R)
Refund (R)
Integer (3)
customer_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)
customer_firstname
Customer’s first name. The size of the customer_firstname field and the customer_lastname field combined cannot exceed 27 characters.
Validate (R)
Direct Debit (R)
Refund (R)
String (See description)
customer_lastname
Customer’s last name. The size of the customer_firstname field and the customer_lastname field combined cannot exceed 27 characters.
Validate (R)
Direct Debit (R)
Refund (R)
String (See description)
direct_debit_mandate_authentication_date
The date of when the mandate was authenticated. The format is yyyymmdd.
Important Required for lodging a UK direct debit mandate, otherwise optional. See Direct Debit Mandate Lodgement.
Direct Debit (See description)
Direct Debit Refund (See description)
Numeric (8)
direct_debit_recurring_type
Indicates a new direct debit mandate, or 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.
Important Required for lodging a UK direct debit mandate; otherwise, it is optional. See Direct Debit Mandate Lodgement.
Direct Debit (See description)
Direct Debit Refund (See description)
Numeric (1)
direct_debit_request_id
The request_id value returned from a previous request for the ics_direct_debit 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 SCMP API.
Refund (R for follow-on refunds. Not used for standalone refunds.)
String (26)
direct_debit_request_token
The request_token value returned from a previous request for the ics_direct_debit 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 SCMP API.
Refund (O for follow-on refunds. Not used for standalone refunds.)
String (256)
grand_total_amount
Grand total for the order. You must include either this field or the amount offer-level field in your request. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP API.
Note Required for lodging a UK direct debit mandate, and the value must be set to 0. See Direct Debit Mandate Lodgement.
Validate (See description)
Direct Debit (See description)
Refund (See description)
Integer (12)
ics_applications
CyberSource services to process the request.
Validate (R)
Direct Debit (R)
Refund (R)
String (255)
link_to_request
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 SCMP API.
Direct Debit (O)
String (26)
mandate_id
The unique identification reference for the direct debit mandate.
Important Required for lodging a UK direct debit mandate; otherwise it is optional. See Direct Debit Mandate Lodgement.
Direct Debit (See description)
Direct Debit Refund (See description)
String (35)
merchant_id
Your CyberSource merchant ID.
Validate (R)
Direct Debit (R)
Refund (R)
String (30)
merchant_ref_number
Merchant-generated order reference or tracking number.
Important Do not use the following symbols in this value: pipe (|), caret (^), percent symbol (%), backslash (\), forward slash (/).
Validate (R)
Direct Debit (R)
Refund (R)
String (22)
order_request_token
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 SCMP API.
Debit (R for follow-on direct debits. Not used for standalone direct debits.)
Refund (R for follow-on refunds. Not used for standalone refunds.)
String (256)
prenote_transaction
Indicates whether the merchant intends to perform a pre-note transaction and to forward mandate information to the issuer. 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 notification to the payer at least five calendar days before collecting the payment.
The possible values are:
■
yes: include pre-note transaction in your request.
■
no: do not include pre-note transaction in your request.
Important You must include the prenote_transaction field in your request and set the grand_total_amount value to 0. See Direct Debit Mandate Lodgement.
Direct Debit (See description)
 
String (5)
ship_to_address1
First line of the address to which the product will be shipped.
Direct Debit (R if any ship_to_ fields are included in the request.)
String (28)
ship_to_address2
Second line of the address to which the product will be shipped.
Direct Debit (O)
String (28)
ship_to_city
City to which the product will be shipped.
Direct Debit (R if any ship_to_ fields are included in the request.)
String (20)
ship_to_country
Country to which the product will be shipped. Possible values are the two-character ISO Standard Country Codes.
Direct Debit (O)
String (2)
ship_to_firstname
First name of the person receiving the product. The size of the ship_to_firstname field and the ship_to_lastname field combined cannot exceed 27 characters.
Direct Debit (O)
String (60)
ship_to_lastname
Last name of the person receiving the product. The size of the ship_to_firstname field and the ship_to_lastname field combined cannot exceed 27 characters.
Direct Debit (O)
String (60)
ship_to_state
State or province to which the product will be shipped. Required if ship_to_country=US or Canada. Possible values are the State, Province, and Territory Codes for the United States and Canada.
Direct Debit (See description)
String (2)
ship_to_zip
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 ship_to_country is US or CA)
String (10)
validate_request_id
The request_id value returned from a previous request for the ics_direct_debit_validate 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 SCMP API.
Debit (R for follow-on direct debits. Not used for standalone direct debits.)
String (26)
validate_request_token
The request_token value returned from a previous request for the ics_direct_debit_validate 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 SCMP API.
Debit (O for follow-on direct debits. Not used for standalone direct debits.)
String (256)
void_request_id
Request ID of the direct debit or direct debit refund you want to void.
Void (R)
String (26)
Offer-Level Fields
 
Table 5
Offer-Level Fields 
Offer-Level Field
Description
Required (R) or Optional (O)
Data Type & Length
amount
Per-item price of the product. You must include either the offer0 and this field or the request-level field grand_total_amount in your request. This value cannot be negative. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP 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)
merchant_product_sku
Product identifier code. Required if product_code is not the default value, stored_value, or one of the values related to shipping or handling.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
product_code
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 or handling, the quantity, product_name, and merchant_product_sku fields are required. For more nformation about required offer-level fields, see Getting Started with CyberSource Advanced for the SCMP API.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
product_name
Product’s name. Required if product_code is not default, stored_value, or one of the values related to shipping or handling.
Validate (O)
Direct Debit (O)
Refund (O)
String (30)
quantity
Quantity of the product being purchased. The default is 1. Required if product_code is not default, stored_value, or one of the values related to shipping and/or handling.
Validate (O)
Direct Debit (O)
Refund (O)
Integer (10)
tax_amount
Tax amount associated with this item. The field is additive. For example, if you send the following offer line fields:
offer0=amount:10.00^
quantity:1^tax_amount:0.80
offer1=amount:20.00^
quantity:1^tax_amount:1.60
the total amount authorized will be for 32.40, not 30.00 with 2.40 of tax included.
The amount field and the tax_amount field must be in the same currency.
If you include the tax_amount field, and you also include the ics_tax service in your request, the ics_tax service will not calculate tax for the item. Instead, it will return the value in the tax_amount field.
Validate (O)
Direct Debit (O)
Refund (O)
String (15)
Reply Fields
 
Table 6
Reply Fields for the SCMP API 
Reply Field
Description
Returned By
Data Type & Length
client_lib_version
Information about the client library used to request the transaction.
Validate
Direct Debit
Refund
String (50)
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)
direct_debit_amount
Amount of the direct debit.
Direct Debit
String (15)
direct_debit_rcode
One-digit code that indicates whether the ics_direct_debit request was successful:
■
-1: An error occurred.
■
0: The request was declined.
■
1: The request was successful.
Direct Debit
Integer (1)
direct_debit_refund_amount
Amount of the direct debit refund.
Refund
String (15)
direct_debit_refund_rcode
One-digit code that indicates if the ics_direct_debit_refund request was successful:
■
-1: An error occurred.
■
0: The request was declined.
■
1: The request was successful.
Refund
Integer (1)
direct_debit_refund_request_time
Time the direct debit refund was requested. The format is YYYY-MM-DDThhmmssZ. For example, 2006-08-11T224757Z 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
Date and time (20)
direct_debit_refund_response_code
Response code from the processor.
Refund
String (10)
direct_debit_refund_rflag
One-word description of the result for the ics_direct_debit_refund service request. See Reply Flags, for the possible values.
Refund
String (50)
direct_debit_refund_rmsg
Message that explains direct_debit_refund_rflag.
Refund
String (255)
direct_debit_refund_trans_ref_no
Reference number you can use to track the transaction.
Refund
String (22)
direct_debit_request_time
Time the direct debit was requested. The format is YYYY-MM-DDThhmmssZ. For example, 2006-08-11T224757Z 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
Date and time (20)
direct_debit_response_code
Response code from the processor.
Direct Debit
String (10)
direct_debit_rflag
One-word description of the result for the ics_direct_debit request. See Reply Flags, for the possible values.
Direct Debit
String (50)
direct_debit_rmsg
Message that explains direct_debit_rflag.
Direct Debit
String (255)
direct_debit_trans_ref_no
Reference number you can use to track the transaction.
Direct Debit
String (22)
direct_debit_validate_amount
The amount sent in the direct debit validate request in either grand_total_amount or the amount field for offer0.
Validate
String (15)
direct_debit_validate_bank_swift_code
Bank’s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC).
Validate
String
(11)
direct_debit_validate_iban
International Bank Account Number (IBAN).
Validate
String (34)
direct_debit_validate_rcode
One-digit code that indicates if the ics_direct_debit_validate request was successful:
■
-1: An error occurred.
■
0: The request was declined.
■
1: The request was successful.
Validate
Integer (1)
direct_debit_validate_request_time
Time the direct debit validate was requested. The format is YYYY-MM-DDThhmmssZ. For example, 2006-08-11T224757Z 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
Date and time (20)
direct_debit_validate_response_code
Response code from the processor.
Validate
String (10)
direct_debit_validate_rflag
One-word description of the result for the ics_direct_debit_validate request. See Reply Flags, for the possible values.
Direct Debit
String (50)
direct_debit_validate_rmsg
Message that explains direct_debit_validate_rflag.
Direct Debit
String (255)
direct_debit_validate_trans_ref_no
Reference number you can use to track the transaction.
Validate
String (22)
ics_rcode
One-digit code that indicates if the entire request was successful:
■
-1: An error occurred.
■
0: The request was declined.
■
1: The request was successful.
Validate
Direct Debit
Refund
Integer (1)
ics_rflag
One-word description of the result for the entire request. See Reply Flags, for the possible values.
Validate
Direct Debit
Refund
String (50)
ics_rmsg
Message that explains ics_rflag.
Validate
Direct Debit
Refund
String (255)
merchant_ref_number
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)
request_id
Identifier for the request.
Validate
Direct Debit
Refund
String (26)
request_token
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 SCMP API.
Validate
Direct Debit
Refund
String (256)
void_rcode
Indicates whether the service request was successful. Possible values:
■
-1: An error occurred.
■
0: The request was declined.
■
1: The request was successful.
Void
Integer (1)
void_rflag
One-word description of the result of the void request. See Reply Flags.
Void
String (50)
void_rmsg
Message that explains the reply flag void_rflag. Do not display this message to the customer, and do not use this field to write an error handler.
Void
String (255)
void_void_amount
Total amount of the void.
Void
Decimal (15)
void_void_currency
Currency used for the transaction. Possible values are the ISO Standard Currency Codes for currencies.
Void
Integer (3)
void_void_request_time
Time at which the void was requested in UTC. See Data Type Definitions, for the field’s format.
Void
Date and time (20)
Reply Flags
* 
CyberSource reserves the right to add new reply flags at any time. Your system must be able to process these new reply flags.
A reply flag is associated with an entire request or a specific service:
■
Entire request—the flag is in the ics_rflag field with a message in the ics_rmsg field.
■
Individual service—the flag is in the <service>_rflag field with a message in the <service>_rmsg field.
Table 7
Reply Flags 
Reply Flag
Description
Returned By
DCARDREFUSED
The bank declined the transaction.
Note Declines can be due to insufficient funds, which cannot be determined during validation.
Validate
Direct Debit
Refund
DINVALIDDATA
Data provided is not consistent with the request.
Validate
Direct Debit
Refund
ESYSTEM
System error. Wait a few minutes before re-sending your request. You must design your transaction management system to correctly handle CyberSource system errors. The error may indicate a valid CyberSource system error or a processor rejection due to invalid data. In either case, CyberSource recommends that you do not design your system to endlessly retry sending a transaction. See the documentation for your CyberSource client for information on handling system errors and retries.
Note If you receive the ESYSTEM flag in your reply along with the following error message, your system’s clock is incorrect. You must adjust your system’s clock for your time zone; otherwise your transactions will be rejected.
Error message: The request ID generated by your client is incorrect because your system's clock does not match your local time. Please adjust your system's clock to your local time, and resend your request.
Validate
Direct Debit
Refund
SOK
The transaction was successful.
Validate
Direct Debit
Refund