Reply Fields

API Fields : Reply Fields

Reply Fields

Reply fields are sent using the following notification methods:

■

Merchant POST URL (see Receiving Merchant Notifications)

■

Merchant POST Email (see Receiving Merchant Notifications)

■

POSTed to the URL specified in the Transaction or Custom Cancel Response page (see Transaction Response Page)

Notification methods are enabled on the Notifications and Customer Response pages of your Secure Acceptance profile.

To ensure the integrity of the reply fields, a signature is included in the response. This signature is generated using the same secret_key value that was used to generate the request signature.

To verify that the reply fields have not been tampered with, create a signature using the fields listed in the signed_field_names reply field. This signature must be the same value that is included in the signature response field. Refer to the receipt page that is included in the sample scripts (see Samples in Scripting Languages).

Because CyberSource can add reply fields and reason codes at any time, proceed as follows:

■

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 scripting language.

■

The signature that you generate must be the same value that is included in the signature response field.

■

Your error handler should use the decision field to determine the transaction result if it receives a reason code that it does not recognize.

If configured, these reply fields are sent back to your Merchant POST URL or email. See Receiving Merchant Notifications. Your error handler should use the decision field to obtain the transaction result if it receives a reason code that it does not recognize.

Table 7

Reply Fields

Field

Description

Data Type & Length

auth_amount

Amount that was authorized.

String (15)

auth_avs_code

AVS result code. See AVS Codes.

String (1)

auth_avs_code_raw

AVS result code sent directly from the processor. Returned only if a value is returned by the processor.

String (10)

auth_card_payroll

Indicates whether the card is a payroll card.

Possible values:

■

Y: Yes

■

N: No

■

X: Does not apply / Unknown

Note This field is supported for Visa, Discover, Diners Club, and JCB on Chase Paymentech Solutions.

String (1)

auth_card_pinless_debit

Indicates whether the card is a PINless debit card.

Possible values:

■

Y: Yes

■

N: No

■

X: Does not apply / Unknown

Note This field is supported for Visa and Mastercard on Chase Paymentech Solutions.

String (1)

auth_card_prepaid

Indicates whether the card is a prepaid card. This information enables you to determine when a gift card or prepaid card is presented for use when establishing a new recurring or installment billing relationship.

Possible values:

■

Y: Yes

■

N: No

■

X: Does not apply / Unknown

Note This field is supported for Visa, Mastercard, Discover, Diners Club, and JCB on Chase Paymentech Solutions.

String (1)

auth_card_regulated

Indicates whether the card is regulated according to the Durbin Amendment. If the card is regulated, the card issuer is subject to price caps and interchange rules.

Possible values:

■

Y: Yes (assets greater than $10B)

■

N: No (assets less than $10B)

■

X: Does not apply / Unknown

Note This field is supported for Visa, Mastercard, Discover, Diners Club, and JCB on Chase Paymentech Solutions.

String (1)

auth_card_signature_debit

Indicates whether the card is a signature debit card. This information enables you to alter the way an order is processed. Possible values:

■

Y: Yes

■

N: No

■

X: Does not apply / Unknown

Note This field is supported for Visa, Mastercard, and Maestro (International) on Chase Paymentech Solutions.

String (1)

auth_cavv_result

Mapped response code for the Visa Secure and American Express SafeKey:

■

See Visa Secure Response Codes.

■

See American Express SafeKey Response Codes.

String (3)

auth_cavv_result_raw

Raw response code sent directly from the processor for Visa Secure and American Express SafeKey.

String (3)

auth_code

Authorization code. Returned only if a value is returned by the processor.

String (7)

auth_cv_result

CVN result code. See CVN Codes.

String (1)

auth_cv_result_raw

CVN result code sent directly from the processor. Returned only if a value is returned by the processor.

String (10)

auth_response

For most processors, this is the error message sent directly from the bank. Returned only if a value is returned by the processor.

String (10)

auth_time

Time of authorization in UTC.

String (20)

auth_trans_ref_no

Reference number that you use to reconcile your CyberSource reports with your processor reports.

For authorization requests, the transaction

reference number is returned only for

these processors:

■

American Express Direct

■

Asia, Middle East, and Africa Gateway

■

Atos

■

BML Direct

■

Chase Paymentech Solutions

■

Cielo

■

CyberSource through VisaNet

■

FDC Compass

■

FDC Nashville Global

■

Moneris

■

Worldpay VAP
Worldpay VAP was previously called Litle.

String (60)

bill_trans_ref_no

Reference number that you use to reconcile your CyberSource reports with your processor reports.

Note This field is not supported on CyberSource through VisaNet.

String (60)

bin_lookup_billing_currency

Cardholder’s billing currency. For the possible values, see ISO Standard Currency Codes.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (3)

bin_lookup_billing_currency_minor_digits

Number of decimal positions for amounts in the cardholder's billing currency.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_billing_currency_numeric_code

Three-digit numeric ISO code for the cardholder’s billing currency. Use the three-character ISO Standard Currency Codes.

String (3)

bin_lookup_card_product_category

Category of product, such as business, commercial, or consumer.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (no maximum length)

bin_lookup_card_sub_type

Kind of card, such as:

■

Charge

■

Credit

■

Credit/debit

■

Debit

■

Deferred debit

■

Prepaid

Note For security reasons, this field is only returned in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (no maximum length)

bin_lookup_card_type

Three-digit value that indicates the card type. For the possible values, see appendix “Card Types” in Credit Card Services Using the SCMP API or Credit Card Services Using the Simple Order API.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (3)

bin_lookup_card_type_name

Name of the card type.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (50)

bin_lookup_cross_border_eligible

Indicates whether cross-border transactions are supported. Cross border means that the issuer and acquirer are in different countries. Possible values:

■

Y: Supported

■

N: Not supported

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_issuer_country

Country of the issuing bank. For the possible values, see ISO Standard Country Codes.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (2)

bin_lookup_issuer_country_numeric_code

Three-digit numeric ISO code for the issuer’s country. See appendix “Numeric Country and Currency Codes” in Credit Card Services Using the SCMP API or Credit Card Services Using the Simple Order API.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (3)

bin_lookup_issuer_name

Bank that issued the card, such as Bank of America, Chase, or Wells Fargo.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (no maximum length)

bin_lookup_issuer_phone

Customer service phone number for the issuing bank.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (no maximum length)

bin_lookup_level_2_eligible

Indicates whether Level II transactions are supported. Possible values:

■

Y: Supported

■

N: Not supported

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_level_3_eligible

Indicates whether Level III transactions are supported. Possible values:

■

Y: Supported

■

N: Not supported

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_network#_aft_cross_border_eligible

Indicates whether cross-border AFT transactions are supported on network specified by the network ID value. Cross border means that the issuer and acquirer are in different countries. Possible values:

■

Y: Supported

■

N: Not supported

This field is returned only for debit networks that are supported for the card number submitted in the request.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_network#_aft_domestic_eligible

Indicates whether domestic AFT transactions are supported on network specified by the network ID value. Domestic means that the issuer and acquirer are in the same country. Possible values:

■

Y: Supported

■

N: Not supported

This field is returned only for debit networks that are supported for the card number submitted in the request.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_network#_network_id

Network identifier for the related elements in the array. For detailed information, see appendix “Network IDs and Sharing Group Codes” in Credit Card Services Using the SCMP API or Credit Card Services Using the Simple Order API.

This field is returned only for debit networks that are supported for the card number submitted in the request.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (4)

bin_lookup_network#_network_order

One or more codes that indicate which networks are supported for the card.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (5)

bin_lookup_network#_oct_cross_border_eligible

Indicates whether cross-border OCT transactions are supported on network specified by the network ID value. Cross border means that the issuer and acquirer are in different countries. Possible values:

■

Y: Supported

■

N: Not supported

This field is returned only for debit networks that are supported for the card number submitted in the request.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_network#_oct_domestic_eligible

Indicates whether domestic OCT transactions are supported on network specified by the network ID value. Domestic means that the issuer and acquirer are in the same country. Possible values:

■

Y: Supported

■

N: Not supported

This field is returned only for debit networks that are supported for the card number submitted in the request.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_oct_fast_funds_indicator

Indicates the issuer’s level of support for Fast Funds transactions. A Fast Funds transaction makes funds available to the recipient within 30 minutes. An issuer that supports original credit transactions (OCTs) but not Fast Funds transactions makes funds available within two business days.

■

B: Issuer supports Fast Funds for all transactions.

■

D: Issuer supports Fast Funds only for domestic transactions.

■

N: Issuer does not support Fast Funds.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications, not in the Receipt POST through the browser.

String (1)

bin_lookup_oct_gambling_eligible

Indicates whether the account can receive original credit transactions (OCTs) for gambling transactions. Possible values:

■

Y: Original credit transactions (OCTs) for gambling transactions are blocked.

■

N: Original credit transactions (OCTs) for gambling transactions are not blocked.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications (not in the Receipt POST through the browser).

String (1)

bin_lookup_oct_indicator

Indicates whether the account can receive Visa Direct transactions. Possible values:

■

A: Accepts Visa Direct transactions.

■

B: Accepts Visa Direct transactions.

■

C: Accepts Visa Direct transactions.

■

N: Does not accept Visa Direct transactions.

For information about Visa Direct, see Payouts.

Note For security reasons, this field is returned only in Merchant POST URL and Email notifications, not in the Receipt POST through the browser.

String (1)

decision

The result of your request. Possible values:

■

ACCEPT

■

DECLINE

■

REVIEW

■

ERROR

■

CANCEL

String (7)

echeck_debit_ref_no

Reference number for the transaction.

String (60)

echeck_debit_submit_time

Time when the debit was requested in UTC.

Date and Time (20)

invalid_fields

Indicates which request fields were invalid.

Variable

message

Reply message from the payment gateway.

String (255)

payer_authentication_cavv

Cardholder authentication verification value (CAVV). Transaction identifier generated by the issuing bank. This field is used by the payer authentication validation service.

String (50)

payer_authentication_eci

Electronic commerce indicator (ECI). This field is used by payer authentication validation and enrollment services. Possible values for Visa, American Express, and JCB:

■

05: Successful authentication.

■

06: Authentication attempted.

■

07: Failed authentication.

Possible values for Mastercard:

■

01: Merchant is liable.

■

02: Card issuer is liable.

String (3)

payer_authentication_enroll_e_commerce_indicator

Commerce indicator for cards not enrolled. This field contains one of these values:

■

internet: Card not enrolled or card type not supported by payer authentication. No liability shift.

■

js_attempted: JCB card not enrolled, but attempt to authenticate is recorded. Liability shift.

■

js_failure: J/Secure directory service is not available. No liability shift.

■

spa: Mastercard card not enrolled in the Identity Check program. No liability shift.

■

vbv_attempted: Visa card not enrolled, but attempt to authenticate is recorded. Liability shift.

■

vbv_failure: For payment processor Barclays, Streamline, AIBMS, or FDC Germany, you receive this result if Visa’s directory service is not available. No liability shift.

String (255)

payer_authentication_enroll_veres_enrolled

Result of the enrollment check. This field can contain one of these values:

■

Y: Card enrolled or can be enrolled; you must authenticate. Liability shift.

■

N: Card not enrolled; proceed with authorization. Liability shift.

■

U: Unable to authenticate regardless of the reason. No liability shift.

Note This field applies only to the Asia, Middle East, and Africa Gateway. If you are configured for this processor, you must send the value of this field in your authorization request.

The following value can be returned if you are using rules-based payer authentication:

■

B: Indicates that authentication was bypassed.

For rules-based payer authentication information see the Payer Authentication Using the SCMP API (PDF | HTML) or Payer Authentication Using the Simple Order API (PDF | HTML).

String (255)

payer_authentication_enroll_veres_enrolled

Result of the enrollment check. This field can contain one of these values:

■

Y: Card enrolled or can be enrolled; you must authenticate. Liability shift.

■

N: Card not enrolled; proceed with authorization. Liability shift.

■

U: Unable to authenticate regardless of the reason. No liability shift.

Note This field applies only to the Asia, Middle East, and Africa Gateway. If you are configured for this processor, you must send the value of this field in your authorization request.

The following value can be returned if you are using rules-based payer authentication:

■

B: Indicates that authentication was bypassed.

For rules-based payer authentication information see the Payer Authentication Using the SCMP API (PDF | HTML) or Payer Authentication Using the Simple Order API (PDF | HTML).

String (255)

payer_authentication_pares_status

Raw result of the authentication check. This field can contain one of these values:

■

A: Proof of authentication attempt was generated.

■

N: Customer failed or canceled authentication. Transaction denied.

■

U: Authentication not completed regardless of the reason.

■

Y: Customer was successfully authenticated.

String (255)

payer_authentication_proof_xml

XML element containing proof of enrollment verification.

For cards not issued in the U.S. or Canada, your bank can require this data as proof of enrollment verification for any payer authentication transaction that you re-submit because of a chargeback.

For cards issued in the U.S. or Canada, Visa can require this data for specific merchant category codes.

This field is HTML encoded.

Note This field is not returned for 3D Secure 2.0 transactions.

String (1024)

payer_authentication_reason_code

Numeric value corresponding to the result of the payer authentication request.

See Reason Codes.

String (5)

payer_authentication_specification_version

This field contains the 3D Secure version that was used to process the transaction. For example, 1.0.2 or 2.0.0.

String (20)

payer_authentication_transaction_id

Payer authentication transaction identifier used by Secure Acceptance to link the enrollment check and validate authentication messages.

String (20)

payer_authentication_uad

Mastercard Identity Check UCAF authentication data. Returned only for Mastercard Identity Check transactions.

String (32)

payer_authentication_uci

Mastercard Identity Check UCAF collection indicator. This field indicates if authentication data is collected at your web site. Possible values:

■

0: Authentication data not collected and customer authentication was not completed.

■

1: Authentication data not collected because customer authentication was not completed.

■

2: Authentication data collected. customer completed authentication.

String (1)

payer_authentication_validate_e_commerce_indicator

Indicator that distinguishes Internet transactions from other types. The authentication failed if this field is not returned. For Visa, if your payment processor is Streamline, Barclays, AIBMS, or FDC Germany, you receive the value vbv_failure instead of internet when payer_authentication_eci is not present.

The value of this field is passed automatically to the authorization service if you request the services together. This field contains one of these values:

■

aesk: American Express SafeKey authentication verified successfully.

■

aesk_attempted: Card not enrolled in American Express SafeKey, but the attempt to authenticate was recorded.

■

internet: Authentication was not verified successfully.

■

js: J/Secure authentication verified successfully.

■

js_attempted: JCB card not enrolled in J/Secure, but the attempt to authenticate was recorded.

■

spa: Mastercard Identity Check authentication verified successfully.

■

spa_failure: Mastercard Identity Check failed authentication.

■

vbv: Visa Secure authentication verified successfully.

■

vbv_attempted: Card not enrolled in Visa Secure, but the attempt to authenticate was recorded.

■

vbv_failure: Visa Secure authentication unavailable.

String (255)

payer_authentication_validate_result

Raw authentication data that comes from the card issuing bank that indicates whether authentication was successful and whether liability shift occurred. This field contains one of these values:

■

-1: Invalid PARes.

■

0: Successful validation.

■

1: Cardholder is not participating, but the attempt to authenticate was recorded.

■

6: Issuer unable to perform authentication.

■

9: Cardholder did not complete authentication.

String (255)

payer_authentication_xid

Transaction identifier generated by CyberSource Payer Authentication. Used to match an outgoing PA request with an incoming PA response.

String (28)

payment_token

Identifier for the payment details. The payment token retrieves the card data, billing information, and shipping information from the CyberSource database.

This payment token supercedes the previous payment token and is returned if:

■

The merchant is configured for a 16 digit payment token which displays the last four-digits of the primary account number (PAN) and passes Luhn mod-10 check. See Payment Tokens.

■

The customer has updated the card number on their payment token. This payment token supercedes the previous payment token and should be used for subsequent transactions.

You must be currently using CyberSource Payment Tokenization services. Populate this field with the customer subscription ID.

String (26)

paypal_address_status

Status of the street address on file with PayPal. Possible values:

■

None

■

Confirmed

■

Unconfirmed

String (12)

paypal_authorization_correlation_id

PayPal identifier that is used to investigate any issues.

String (20)

paypal_authorization_transaction_id

Unique identifier for the transaction.

String (17)

paypal_customer_email

Email address of the customer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page.

String (127)

paypal_do_capture_correlation_id

PayPal identifier that is used to investigate any issues.

String (20)

paypal_do_capture_transaction_id

Unique identifier for the transaction.

String (17)

paypal_ec_get_details_correlation_id

PayPal identifier that is used to investigate any issues.

String (20)

paypal_ec_get_details_request_id

Value of the request ID returned from a PayPal get details service request.

String (26)

paypal_ec_get_details_transaction_id

Unique identifier for the transaction.

String (17)

paypal_ec_order_setup_correlation_id

PayPal identifier that is used to investigate any issues.

String (20)

paypal_ec_order_setup_transaction_id

Unique identifier for the transaction.

String (17)

paypal_ec_set_request_id

Value of the request ID returned from a PayPal set service request.

String (26)

paypal_fee_amount

PayPal fee charged for the transaction. This value does not exceed the equivalent of 10,000 USD in any currency and does not include a currency symbol. The decimal separator is a period (.), and the optional thousands separator is a comma (,).

String (9)

paypal_order_request_id

Value of the request ID returned from a PayPal order setup service request.

String (26)

paypal_payer_id

Customer’s PayPal account identification number.

Alphanumeric

String (13)

paypal_payer_status

Customer’s status. Possible values:

■

verified

■

unverified

String (10)

paypal_pending_reason

Indicates the reason that payment is pending. Possible values:

■

address: Your customer did not include a confirmed shipping address, and your Payment Receiving preferences are set to manually accept or deny such payments. To change your preferences, go to the Preferences section of your PayPal profile.

■

authorization: The payment has been authorized but not settled. You need to capture the authorized amount.

■

echeck: Payment was made by an eCheck that has not yet cleared.

■

intl: You have a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment in your PayPal Account Overview.

■

multi-currency: You do not have a balance in the currency sent, and your Payment Receiving preferences are not set to automatically convert and accept this payment. You must manually accept or deny this payment in your PayPal Account Overview.

■

none: No pending reason.

■

order: The payment is part of an order that has been authorized but not settled.

■

paymentreview: The payment is being reviewed by PayPal for possible fraud.

■

unilateral: The payment was made to an email address that is not registered or confirmed.

■

verify: Your account is not yet verified. You must verify your account before you can accept this payment.

String (14)

paypal_pending_status

Status of the transaction. Possible values:

■

Canceled-Reversal: PayPal canceled the reversal, which happens when you win a dispute, and the funds for the reversal are returned to you.

■

Completed: PayPal completed the payment and added the funds to your account.

■

Denied: You denied a payment, which happens only if the payment was pending for the reason indicated in the reason_code field.

■

Expired: The authorization expired.

■

Failed: The payment failed. This event can happen only when the payment is made from your customer’s bank account.

■

In-Progress: The transaction is not complete yet.

■

None: No status.

■

Partially-Refunded: The payment was partially refunded.

■

Pending: The payment is pending for the reason indicated in the paypal_pending_reason field.

■

Processed: PayPal accepted the payment.

■

ReasonCode

■

Refunded: You refunded the payment.

■

Reversed: PayPal reversed the payment for the reason specified in the reason_code field. The funds were transferred from your account to the customer’s account.

■

Voided: The authorization was voided.

String (20)

paypal_protection_eligibility

Seller protection in force for the transaction. Possible values:

■

Eligible: You are protected by the PayPal Seller Protection Policy for unauthorized payment and item not received.

■

PartiallyEligible: You are protected by the PayPal Seller Protection Policy for item not received.

■

Ineligible: You are not protected under the PayPal Seller Protection Policy.

String (17)

paypal_protection_eligibility_type

Seller protection in force for the transaction. Possible values:

■

Eligible: You are protected by the PayPal Seller Protection Policy for unauthorized payment and item not received.

■

ItemNotReceivedEligible: You are protected by the PayPal Seller Protection Policy for item not received.

■

UnauthorizedPaymentEligible: You are protected by the PayPal Seller Protection Policy for unauthorized payment.

■

Ineligible: You are not protected under the PayPal Seller Protection Policy.

Note To enable the paypal_protection_eligibility_type field, contact CyberSource Customer Support to have your account configured for this feature.

String (32)

paypal_request_id

Identifier for the request generated by the client.

String (26)

paypal_token

Timestamped PayPal token that identifies that PayPal Express Checkout is processing the transaction. Save this value to send in future request messages.

String (20)

paypal_transaction_type

Indicates the PayPal transaction type.

Possible value: expresscheckout

String (16)

reason_code

Numeric value corresponding to the result of the payment card transaction request.

See Reason Codes.

String (5)

req_access_key

Authenticates the merchant with the application.

String (32)

req_aggregator_id

Value that identifies you as a payment aggregator. Obtain this value for the processor.

CyberSource through VisaNet

The value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCR6

■

Position: 95-105

■

Field: Mastercard Payment Facilitator ID

FDC Compass

This value must consist of uppercase characters.

Field Length

American Express Direct: 20

CyberSource through VisaNet: 11

FDC Compass: 20

FDC Nashville Global: 15

Required/Optional

American Express Direct: R for all aggregator transactions.

CyberSource through VisaNet: R for Mastercard aggregator authorizations; otherwise, not used.

FDC Compass: R for all aggregator transactions.

FDC Nashville Global: R for all aggregator transactions.

String (See description)

req_amount

Total amount for the order. Must be greater than or equal to zero.

String (15)

req_auth_indicator

Flag that specifies the purpose of the authorization. Possible values:

■

0: Preauthorization

■

1: Final authorization

Mastercard requires European merchants to indicate whether the authorization is a final authorization or a preauthorization.

To set the default for this field, contact CyberSource Customer Support.

String (1)

req_auth_type

Authorization type. Possible values:

■

AUTOCAPTURE: Automatic capture.

■

STANDARDCAPTURE: Standard capture.

■

verbal: Forced capture.

Asia, Middle East, and Africa Gateway; Cielo; Comercio Latino; and CyberSource Latin American Processing

Set this field to AUTOCAPTURE and include it in a bundled request to indicate that you are requesting an automatic capture. If your account is configured to enable automatic captures, set this field to STANDARDCAPTURE and include it in a standard authorization or bundled request to indicate that you are overriding an automatic capture.

Forced Capture

Set this field to verbal and include it in the authorization request to indicate that you are performing a forced capture; therefore, you receive the authorization code outside the CyberSource system.

Verbal Authorization

Set this field to verbal and include it in the capture request to indicate that the request is for a verbal authorization.

Cielo, Comercio Latino, and CyberSource Latin American Processing: String (15)

All other processors: String (11)

req_bill_payment

Flag that indicates that this payment is for a bill or for an existing contractual loan. Possible values:

■

Y: Bill payment or loan payment.

■

N (default): Not a bill payment or loan payment.

String (1)

req_bill_to_address_city

City in the billing address.

String (50)

req_bill_to_address_country

Country code for the billing address. Use the two-character ISO country codes.

String (2)

req_bill_to_address_line1

First line of the street address in the billing address.

String (60)

req_bill_to_address_line2

Second line of the street address in the billing address.

String (60)

req_bill_to_address_postal_code

Postal code for the billing address.

Note This field is required if bill_to_address_country is U.S. or CA.

When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]

Example 12345-6789

When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]

Example A1B 2C3

For the rest of the world countries, the maximum length is 10.

String (10)

req_bill_to_address_state

The two-character ISO state and province code. See State, Province, and Territory Codes for the United States and Canada.

Note This field is required for the U.S and Canada.

String (2)

req_bill_to_company_name

Name of the customer’s company.

String (40)

req_bill_to_email

Customer email address.

String (255)

req_bill_to_forename

Customer first name.

String (60)

req_bill_to_phone

Customer phone number.

String (15)

req_bill_to_surname

Customer last name.

String (60)

req_card_account_type

Flag that specifies the type of account associated with the card. The cardholder provides this information during the payment process.

Cielo and Comercio Latino
Possible values:

■

CR: Credit card

■

DB: Debit card

CyberSource through VisaNet
Possible values:

■

CH: Checking account

■

CR: Credit card account

■

SA: Savings account

This field is required for:

■

Debit transactions on Cielo and Comercio Latino.

■

Transactions with Brazilian-issued cards on CyberSource through VisaNet.

Note Combo cards in Brazil contain credit and debit functionality in a single card. Visa systems use a credit bank identification number (BIN) for this type of card. Using the BIN to determine whether a card is debit or credit can cause transactions with these cards to be processed incorrectly. CyberSource strongly recommends that you include this field for combo card transactions.

String (2)

req_card_expiry_date

Card expiration date.

String (7)

req_card_number

Card number. See Receiving Merchant Notifications.

String (20)

req_card_type

Type of card.

String (3)

req_company_tax_id

Company’s tax identifier. The the last four digits are not masked.

String (9)

req_complete_route

Concatenation of individual travel legs in the format:

SFO-JFK:JFK-LHR:LHR-CDG.

For a complete list of airport codes, see IATA’s City Code Directory.

In your request, send either the complete route field or the individual legs (journey_leg#_orig and journey_leg#_dest). If you send all the fields, the value of complete_route takes precedence over that of the journey_leg# fields.

String (255)

req_consumer_id

Identifier for the customer account. This value is defined when creating a customer subscription.

String (100)

req_currency

Currency used for the order.

String (3)

req_customer_cookies_accepted

Indicates whether the customer’s browser accepts cookies. This field can contain one of the following values:

■

true: Customer’s browser accepts cookies.

■

false: Customer’s browser does not accept cookies.

String (5)

req_customer_gift_wrap

Indicates whether the customer requested gift wrapping for this purchase. This field can contain one of the following values:

■

true: Customer requested gift wrapping.

■

false: Customer did not request gift wrapping.

String (5)

req_customer_ip_address

Customer IP address reported by your web server using socket information.

req_date_of_birth

Date of birth of the customer in the format: YYYYMMDD.

String (8)

req_debt_indicator

Flag that indicates a payment for an existing contractual loan. Possible values:

■

true: Loan payment.

■

false (default): Not a loan payment.

String (5)

req_departure_time

Departure date and time of the first leg of the trip. Use one of the following formats:

yyyy-MM-dd HH:mm z

yyyy-MM-dd hh:mm a z

yyyy-MM-dd hh:mma z

HH = 24-hour format

hh = 12-hour format

a = am or pm (case insensitive)

z = time zone of the departing flight.

String (29)

req_device_fingerprint_id

Field that contains the session ID for the fingerprint. The string can contain uppercase and lowercase letters, digits, and these special characters: hyphen (-) and underscore (_).

However, do not use the same uppercase and lowercase letters to indicate different sessions IDs.

The session ID must be unique for each merchant ID. You can use any string that you are already generating, such as an order number or web session ID.

String (88)

req_driver_license_number

Driver’s license number of the customer. The the last four-digits are not masked.

String (30)

req_driver_license_state

State or province from which the customer’s driver’s license was issued. Use the two-character State, Province, and Territory Codes for the United States and Canada.

String (2)

req_e_commerce_indicator

The commerce indicator for the transaction type.

Value: install

Note This field is required only for installment payments on CyberSource Latin American Processing.

String (13)

req_echeck_account_number

Account number. This number is masked.

Non-negative integer (17)

req_echeck_account_type

Account type. Possible values:

■

C: Checking

■

S: Savings (USD only)

■

X: Corporate checking (USD only)

String (1)

req_echeck_check_number

Check number.

Integer (8)

req_echeck_routing_number

Bank routing number. It is also called the transit number.

Non-negative integer (9)

req_echeck_sec_code

The authorization method for the transaction. Possible values:

■

CCD

■

PPD

■

TEL

■

WEB

String (3)

req_ignore_avs

Ignore the results of AVS verification. Possible values:

■

true

■

false

String (5)

req_ignore_cvn

Ignore the results of CVN verification. Possible values:

■

true

■

false

String (5)

req_installment_total_amount

Total amount of the loan that is being paid in installments.

Note This field is required only for installment payments on CyberSource Latin American Processing or CyberSource through VisaNet.

Amount (12)

req_installment_total_count

Total number of installment payments as part of an authorization.

Possible values: 1 to 99

Note This field is required only for installment payments on CyberSource Latin American Processing.

Numeric

String (2)

req_issuer_additional_data

Data defined by the issuer.

See the “Formats for Discretionary Data” section in Credit Card Services Using the SCMP API or Credit Card Services Using the Simple Order API.

Alphanumeric

String (256)

req_item_#_code

Type of product. # can range from 0 to 199.

String (255)

req_item_#_description

Description of the item. # can range from 0 to 199.

String (255)

req_item_#_name

Name of the item. # can range from 0 to 199.

String (255)

req_item_#_passenger_email

Passenger’s email address.

String (255)

req_item_#_passenger_forename

Passenger’s first name.

String (60)

req_item_#_passenger_id

ID of the passenger to whom the ticket was issued. For example, you can use this field for the frequent flyer number.

String (32)

req_item_#_passenger_phone

Passenger’s phone number. If the order is from outside the U.S., CyberSource recommends that you include the country code.

String (15)

req_item_#_passenger_status

Your company’s passenger classification, such as with a frequent flyer classification. In this case, you might use values such as standard, gold, or platinum.

String (32)

req_item_#_passenger_surname

Passenger’s last name.

String (60)

req_item_#_passenger_type

Passenger classification associated with the price of the ticket. You can use one of the following values:

■

ADT: Adult

■

CNN: Child

■

INF: Infant

■

YTH: Youth

■

STU: Student

■

SCR: Senior Citizen

■

MIL: Military

String (32)

req_item_#_quantity

Quantity of line items. # can range from 0 to 199.

String (10)

req_item_#_sku

Identification code for the product. # can range from 0 to 199.

String (255)

req_item_#_tax_amount

Tax amount to apply to the line item. # can range from 0 to 199. This value cannot be negative. The tax amount and the offer amount must be in the same currency.

String (15)

req_item_#_unit_price

Price of the line item. # can range from 0 to 199. This value cannot be negative.

String (15)

req_journey_leg#_dest

Airport code for the destination leg of the trip designated by the pound (#) symbol in the field name. A maximum of 30 legs can be included in the request. This code is usually three digits long; for example: SFO = San Francisco. Do not use the colon (:) or the dash (-). For a complete list of airport codes, see IATA’s City Code Directory.

In your request, send either complete_route field or the individual legs (journey_leg#_orig and journey_leg#_dest). If you send all the fields, the complete route takes precedence over the individual legs.

String (3)

req_journey_leg#_orig

Airport code for the origin leg of the trip designated by the pound (#) symbol in the field name. A maximum of 30 legs can be included in the request. This code is usually three digits long; for example: SFO = San Francisco. Do not use the colon (:) or the dash (-). For a complete list of airport codes, see IATA’s City Code Directory.

In your request, send either the complete_route field or the individual legs (journey_leg#_orig and journey_leg#_dest). If you send all the fields, the complete route takes precedence over the individual legs.

String (3)

req_journey_type

Type of travel, such as one way or round trip.

String (32)

req_jpo_installments

Total number of Japanese installment payments.

String (2)

req_jpo_payment_method

Japanese payment method.

String (1)

req_line_item_count

Total number of line items. Maximum number is 200.

String (2)

req_locale

Indicates the language used for the customer-facing content.

String (5)

req_merchant_defined_data#

Optional fields that you can use to store information. # can range from 1 to 100.

Merchant-defined data fields 1 to 4 are associated with the payment token and are used for subsequent token-based transactions. Merchant-defined data fields 5 to 100 are passed through to Decision Manager as part of the initial payment request and are not associated with the payment token.

Warning Merchant-defined data fields are not intended to and MUST NOT be used to capture personally identifying information. Accordingly, merchants are prohibited from capturing, obtaining, and/or transmitting any personally identifying information in or via the merchant-defined data fields and any Secure Acceptance field that is not specifically designed to capture personally identifying information. Personally identifying information includes, but is not limited to, card number, bank account number, social security number, driver's license number, state-issued identification number, passport number, card verification numbers (CVV, CVC2, CVV2, CID, CVN). In the event CyberSource discovers that a merchant is capturing and/or transmitting personally identifying information via the merchant-defined data fields, whether or not intentionally, CyberSource WILL immediately suspend the merchant's account, which will result in a rejection of any and all transaction requests submitted by the merchant after the point of suspension.

String (100)

req_merchant_descriptor

req_merchant_descriptor_alternate

req_merchant_descriptor_city

req_merchant_descriptor_contact

req_merchant_descriptor_country

req_merchant_descriptor_state

req_merchant_descriptor_postal_code

req_merchant_descriptor_street

For the descriptions, used-by information, data types, and lengths for these fields, see the “Merchant Descriptors” section in either Credit Card Services Using the SCMP API or Credit Card Services Using the Simple Order API.

req_merchant_secure_data1

req_merchant_secure_data2

req_merchant_secure_data3

Optional fields that you can use to store information. CyberSource encrypts the data before storing it in the database.

String (100)

req_merchant_secure_data4

Optional field that you can use to store information. CyberSource encrypts the data before storing it in the database.

String (2000)

req_override_backoffice_post_url

Overrides the backoffice post URL profile setting with your own URL.

URL (255)

req_override_custom_cancel_page

Overrides the custom cancel page profile setting with your own URL.

URL (255)

req_override_custom_receipt_page

Overrides the custom receipt profile setting with your own URL.

URL (255)

req_payment_method

Method of payment. Possible values:

■

card

■

echeck

■

paypal

String (30)

req_payment_token

Identifier for the payment details. The payment token retrieves the card data, billing information, and shipping information from the CyberSource database. When this field is included in the request, the card data and billing and shipping information are optional.

You must be currently using CyberSource Payment Tokenization services. Populate this field with the customer subscription ID.

String (26)

req_payment_token_comments

Optional comments about the customer subscription.

String (255)

req_payment_token_title

Name of the customer subscription.

String (60)

req_profile_id

Identifies the profile to use with each transaction.

String (36)

req_recipient_account_id

Identifier for the recipient’s account. Use the first six digits and last four digits of the recipient’s account number.

Numeric

String (10)

req_recipient_date_of_birth

Recipient’s date of birth.

Format: YYYYMMDD.

Date (b)

String (8)

req_recipient_postal_code

Partial postal code for the recipient’s address.

For example, if the postal code is NN5 7SG, the value for this field should be the first part of the postal code: NN5.

Alphanumeric

String (6)

req_recipient_surname

Recipient’s last name.

Alpha

String (6)

req_recurring_amount

Payment amount for each installment or recurring subscription payment.

String (15)

req_recurring_automatic_renew

Indicates whether to automatically renew the payment schedule for an installment subscription. Possible values:

■

true (default): Automatically renew.

■

false: Do not automatically renew.

Enumerated String

String (5)

req_recurring_frequency

Frequency of payments for an installment or recurring subscription.

String (20)

req_recurring_number_of_installments

Total number of payments set up for an installment subscription.

String (3)

req_recurring_start_date

First payment date for an installment or recurring subscription payment.

String (8)

req_reference_number

Unique merchant-generated order reference or tracking number for each transaction.

String (50)

req_returns_accepted

Indicates whether product returns are accepted. Possible values:

■

true

■

false

String (5)

req_sales_organization_id

Company ID assigned to an independent sales organization. Obtain this value from Mastercard.

CyberSource through VisaNet

The value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCR6

■

Position: 106-116

■

Field: Mastercard Independent Sales Organization ID

Nonnegative integer (11)

req_ship_to_address_city

City of shipping address.

String (50)

req_ship_to_address_country

The two-character ISO country code.

String (2)

req_ship_to_address_line1

First line of shipping address.

String (60)

req_ship_to_address_line2

Second line of shipping address.

String (60)

req_ship_to_address_postal_code

Postal code of shipping address.

String (10)

req_ship_to_address_state

The two-character ISO state and province code.

String (2)

req_ship_to_company_name

Name of the company receiving the product.

String (40)

req_ship_to_forename

First name of person receiving the product.

String (60)

req_ship_to_phone

Phone number for the shipping address.

String (15)

req_ship_to_surname

Second name of person receiving the product.

String (60)

req_shipping_method

Shipping method for the product. Possible values:

■

sameday: Courier or same-day service

■

oneday: Next day or overnight service

■

twoday: Two-day service

■

threeday: Three-day service

■

lowcost: Lowest-cost service

■

pickup: Store pick-up

■

other: Other shipping method

■

none: No shipping method because

String (10)

req_skip_bin_lookup

Indicates whether the BIN lookup service was skipped. See BIN Lookup.

Enumerated String

String (5)

req_skip_decision_manager

Indicates whether to skip Decision Manager. See Using Decision Manager. This field can contain one of the following values:

■

true

■

false

String (5)

req_submerchant_city

Sub-merchant’s city.

FDC Compass

This value must consist of uppercase characters.

American Express Direct: String (15)

FDC Compass: String (21)

FDC Nashville Global: String (11)

req_submerchant_country

Sub-merchant’s country. Use the two-character ISO Standard Country Codes.

FDC Compass

This value must consist of uppercase characters.

String (3)

req_submerchant_email

Sub-merchant’s email address.

CyberSource through VisaNet

With American Express, the value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCRB

■

Position: 25-64

■

Field: American Express Seller E-mail Address

American Express Direct: String (40)

CyberSource through VisaNet: String (40)

FDC Compass: String (40)

FDC Nashville Global: String (19)

req_submerchant_id

The ID you assigned to your sub-merchant.

CyberSource through VisaNet

With American Express, the value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCRB

■

Position: 65-84

■

Field: American Express Seller ID

With Mastercard, the value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCR6

■

Position: 117-131

■

Field: Mastercard Sub-Merchant ID

FDC Compass

This value must consist of uppercase characters.

American Express Direct: String (20)

CyberSource through VisaNet with American Express: String (20)

CyberSource through VisaNet with Mastercard:
String (15)

FDC Compass: String (20)

FDC Nashville Global: String (14)

req_submerchant_name

Sub-merchant’s business name.

FDC Compass

This value must consist of uppercase characters.

American Express Direct: String (37)

FDC Compass with American Express: String (19)

FDC Compass with Mastercard: String (37)

FDC Nashville Global: String (12)

req_submerchant_phone

Sub-merchant’s telephone number.

CyberSource through VisaNet

With American Express, the value for this field corresponds to the following data in the TC 33 capture file1:

■

Record: CP01 TCRB

■

Position: 5-24

■

Field: American Express Seller Telephone Number

FDC Compass

This value must consist of uppercase characters. Use one of these recommended formats:
NNN-NNN-NNNN
NNN-AAAAAAA

American Express Direct: String (20)

CyberSource through VisaNet: String (20)

FDC Compass: String (13)

FDC Nashville Global: String (10)

req_submerchant_postal_code

Partial postal code for the sub-merchant’s address.

FDC Compass

This value must consist of uppercase characters.

American Express Direct: String (9)

FDC Compass: String (15)

FDC Nashville Global: String (9)

req_submerchant_state

Sub-merchant’s state or province. Use the State, Province, and Territory Codes for the United States and Canada.

FDC Compass

This value must consist of uppercase characters.

String (2)

req_submerchant_street

First line of the sub-merchant’s street address.

FDC Compass

This value must consist of uppercase characters.

American Express Direct: String (30)

FDC Compass: String (38)

FDC Nashville Global: String (25)

req_tax_amount

Total tax to apply to the product.

String (15)

req_transaction_type

The type of transaction requested.

String (60)

req_transaction_uuid

Unique merchant-generated identifier.

This identifier must be unique for each transaction. This field is used to check for duplicate transaction attempts.

String (50)

required_fields

Indicates which of the request parameters were required but not provided.

Variable

service_fee_amount

The service fee amount for the order.

String (15)

service_fee_return_url

URL to POST the conditions_accepted field value to. See Enabling the Service Fee.

signature

The Base64 signature returned by the server.

String (44)

signed_date_time

The date and time of when the signature was generated by the server.

Format: YYYY-MM-DDThh:mm:ssZ

Example 2019-08-11T22:47:57Z equals August 11, 2019, at 22:47:57 (10:47:57 p.m.). The T separates the date and the time. The Z indicates UTC.

String (20)

signed_field_names

A comma-separated list of response data that was signed by the server. All fields within this list should be used to generate a signature that can then be compared to the response signature to verify the response.

Variable

transaction_id

The transaction identifier from the payment gateway.

String (26)

utf8

Indicates whether the unicode characters are encoded.

Possible value: ✓

String (3)

1 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource. CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchant’s acquirer, who uses this information to facilitate end-of-day clearing processing with payment card companies.

Reason Codes

The reason_code field contains additional data regarding the decision response of the transaction. Depending on the decision of a transaction request, the CyberSource default receipt page or your receipt page is displayed to the customer. Both you and your customer can also receive an email receipt. See Receiving Merchant Notifications.

Table 8

Reason Codes

Reason Code

Description

100

Successful transaction.

102

One or more fields in the request contain invalid data.

Possible action: see the reply field invalid_fields to ascertain which fields are invalid. Resend the request with the correct information.

104

The access_key and transaction_uuid fields for this authorization request match the access_key and transaction_uuid fields of another authorization request that you sent within the past 15 minutes.

Possible action: resend the request with a unique access_key field and transaction_uuid field.

110

Only a partial amount was approved.

150

General system failure.

Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status either directly in the Business Center or programmatically through the Single Transaction Query.

151

The request was received but a server timeout occurred. This error does not include timeouts between the client and the server.

Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status either directly in the Business Center or programmatically through the Single Transaction Query.

152

The request was received, but a service timeout occurred.

Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status either directly in the Business Center or programmatically through the Single Transaction Query.

200

The authorization request was approved by the issuing bank but declined by CyberSource because it did not pass the Address Verification System (AVS) check.

Possible action: you can capture the authorization, but consider reviewing the order for fraud.

201

The issuing bank has questions about the request. You do not receive an authorization code programmatically, but you might receive one verbally by calling the processor.

Possible action: call your processor to possibly receive a verbal authorization. For contact phone numbers, refer to your merchant bank information.

202

Expired card. You might also receive this value if the expiration date you provided does not match the date the issuing bank has on file.

Possible action: request a different card or other form of payment.

203

General decline of the card. No other information was provided by the issuing bank.

Possible action: request a different card or other form of payment.

204

Insufficient funds in the account.

Possible action: request a different card or other form of payment.

205

Stolen or lost card.

Possible action: review this transaction manually to ensure that you submitted the correct information.

207

Issuing bank unavailable.

Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status either directly in the Business Center or programmatically through the Single Transaction Query.

208

Inactive card or card not authorized for card-not-present transactions.

Possible action: request a different card or other form of payment.

210

The card has reached the credit limit.

Possible action: request a different card or other form of payment.

211

Invalid CVN.

Possible action: request a different card or other form of payment.

221

The customer matched an entry on the processor’s negative file.

Possible action: review the order and contact the payment processor.

222

Account frozen.

230

The authorization request was approved by the issuing bank but declined by CyberSource because it did not pass the CVN check.

Possible action: you can capture the authorization, but consider reviewing the order for the possibility of fraud.

231

Invalid account number.

Possible action: request a different card or other form of payment.

232

The card type is not accepted by the payment processor.

Possible action: contact your merchant bank to confirm that your account is set up to receive the card in question.

233

General decline by the processor.

Possible action: request a different card or other form of payment.

234

There is a problem with the information in your CyberSource account.

Possible action: do not resend the request. Contact CyberSource Customer Support to correct the information in your account.

236

Processor failure.

Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status either directly in the Business Center or programmatically through the Single Transaction Query.

240

The card type sent is invalid or does not correlate with the payment card number.

Possible action: confirm that the card type correlates with the payment card number specified in the request; then resend the request.

475

The cardholder is enrolled for payer authentication.

Possible action: authenticate cardholder before proceeding.

476

Payer authentication could not be authenticated.

520

The authorization request was approved by the issuing bank but declined by CyberSource based on your Decision Manager settings.

Possible action: review the authorization request.

Types of Notifications

Table 9

Types of Notifications

Decision

Description

Type of Notification

ACCEPT

Successful transaction.

Note See reason codes 100 and 110.

■

Custom receipt page

■

Customer receipt email

■

Merchant POST URL

■

Merchant receipt email

REVIEW

Authorization was declined; however, a capture might still be possible. Review payment details.

Note See reason codes 200, 201, 230, and 520.

■

Custom receipt page

■

Customer receipt email

■

Merchant POST URL

■

Merchant receipt email

DECLINE

Transaction was declined.

Note See reason codes 102, 200, 202, 203, 204, 205, 207, 208, 210, 211, 221, 222, 230, 231, 232, 233, 234, 236, 240, 475, and 476.

■

Custom receipt page 1

■

Merchant POST URL 1

■

Merchant receipt email 1

ERROR

Access denied, page not found, or internal server error.

Note See reason codes 102, 104, 150, 151, and 152.

■

Custom receipt page

■

Merchant POST URL

CANCEL

The customer did not accept the service fee conditions.

The customer canceled the transaction.

■

Custom receipt page

■

Custom cancel page

■

Merchant POST URL

1 If the retry limit is set to 0, the customer receives the decline message, Your order was declined. Please verify your information. before the merchant receives it. The decline message relates to either the processor declining the transaction or a payment processing error, or the customer entered their 3D Secure credentials incorrectly.