Field

Description

Used By: Required (R)
or Optional (O)

Data Type & Length

billTo_postalCode

Postal code for the billing address. The postal code must consist of 5 to 9 digits.

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

This field is supported only on ValueLink.

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

String (11)

card_accountNumber

Gift card account number.

Activation (R if track data is not included in the request.)

Balance Inquiry (R if track data is not included in the request.)

Redemption (R if track data is not included in the request.)

Refund (R if track data is not included in the request.)

Reload (R if track data is not included in the request.)

String with numbers only (19)

card_cardType

Card type associated with the gift card. Value:

n001: Visa

n058: ValueLink

Activation (R)

Balance Inquiry (R)

Redemption (R)

Refund (R)

Reload (R)

String (3)

customerID

Your identifier for the customer.

This field is supported only on ValueLink.

Activation (O)

Refund (O)

Reload (O)

String (16)

giftCard_additionalAccountNumber

For bulk activation transactions, this field is used to submit the second embossed number on the card. This field is required if the first card number in the package was manually entered. This field is optional if the first card number was supplied by the swiped track data.

Activation (R for bulk activations if track data is not included in the request.)

Integer (16)

giftCard_balanceCurrency

Your local currency. For possible values, see ISO Standard Currency Codes.

Balance Inquiry (R)

String(3)

giftCard_escheatable

Flag that indicates that the gift card is escheatable and any funds that are used after five years become unclaimed property that cannot be recognized as revenue. Possible values:

ntrue: Escheatable card.

nfalse (default): Non-escheatable card.

Activation (O)

Refund (O)

Reload (O)

String (5)

giftCard_extendedAccountNumber

The PIN on the back of the gift card.

This field is supported only on ValueLink.

Activation (R if defined in the promotion level; otherwise, optional)

Balance Inquiry (R if defined in the promotion level; otherwise, optional)

Redemption (R if defined in the promotion level; otherwise, optional)

Refund (R if defined in the promotion level; otherwise, optional)

Reload (R if defined in the promotion level; otherwise, optional)

Integer (8)

giftCard_groupID

Value that you create that enables you to identify a group of transactions.

Bulk Activations

This field is returned on the response record and is not a client determined field.

This field is supported only for retail transactions.

This field is supported only on ValueLink.

Activation (O)

Redemption (O)

Refund (O)

Reload (O)

Integer (6)

giftCard_merchantfundedAmount

Amount of the balance that you are funding.

Activation (O)

Reload (O)

String (12)

giftCard_originalRequestID

Request ID for the original transaction that you want to reverse or void.

This field is supported only on ValueLink.

Void (R)

Integer (25)

giftCard_physicalCard

Flag that indicates a physical gift card is being activated. Possible values:

ntrue: Physical card.

nfalse (default): Virtual card.

Activation (O)

String (5)

giftCard_promoCode

Promotion code associated with the gift card activation.

Activation (O)

Integer (8)

giftCard_redemptionType

Type of redemption.

Possible values:

nCASHOUT

nREDEMPTION

nREDEMPTION_PARTIAL_ALLOWED (default)

For details on types of redemption, see Table 1 , Gift Card Services .

This field is supported only on ValueLink.

Redemption (R)

String (26)

giftCard_returnExtendedAccountNumber

Flag that requests the PIN/security code data be returned in the activation response field giftCard_extendedAccountNumber. Possible values:

ntrue: Return the PIN/security code.

nfalse (default): Do not return the PIN/security code.

Activation (O)

String (5)

giftCard_transactionPostingDate

Date that appears on your ValueLink merchant report.

Date for one of these days in your time zone:

nDay before the transaction was sent

nDay on which the transaction was sent

nDay after the transaction was sent

When this field is not included in the request, ValueLink sets the value for this field to the date on which the transaction was sent using your cut-off time. You determine the cut-off time during your onboarding with ValueLink.

Format: YYYYMMDD

This field is supported only on ValueLink.

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

Void (O)

String (8)

giftCardActivationService_commerceIndicator

Type of transaction. Possible values:

ninternet (default): E-commerce order placed using a website.

nretail: Card-present transaction.

Activation (R)

String (20)

giftCardActivationService_reconciliationID 

Reference number for the transaction. See Getting Started with Cybersource Advanced for the Simple Order API for information about order tracking and reconciliation.

Activation (O)

FDC Nashville Global: String (12)

ValueLink: String (17)

giftCardActivationService_run

Whether to include the gift card activation service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Activation (R)

String (5)

giftCardBalanceInquiryService_commerceIndicator

Type of transaction. Possible values:

ninternet (default): E-commerce order placed using a website.

nretail: Card-present transaction.

Balance Inquiry (R)

String (20)

giftCardBalanceInquiryService_reconciliationID

Reference number for the transaction. See Getting Started with Cybersource Advanced for the Simple Order API for information about order tracking and reconciliation.

Balance Inquiry (O)

FDC Nashville Global: String (12)

ValueLink: String (17)

giftCardBalanceInquiryService_run

Whether to include the gift card balance inquiry service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Balance Inquiry (R)

String (5)

giftCardRedemptionService_commerceIndicator

Type of transaction. Possible values:

ninternet (default): E-commerce order placed using a website.

nretail: Card-present transaction.

Redemption (R)

String (20)

giftCardRedemptionService_reconciliationID

Reference number for the transaction. See Getting Started with Cybersource Advanced for the Simple Order API for information about order tracking and reconciliation.

This field is supported only on ValueLink.

Redemption (O)

String (17)

giftCardRedemptionService_run

Whether to include the gift card redemption service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Redemption (R)

String (5)

giftCardRefundService_commerceIndicator

Type of transaction. Possible values:

ninternet (default): E-commerce order placed using a website.

nretail: Card-present transaction.

Refund (R)

String (20)

giftCardRefundService_reconciliationID

Reference number for the transaction. See Getting Started with Cybersource Advanced for the Simple Order API for information about order tracking and reconciliation.

This field is supported only on ValueLink.

Refund (O)

String (17)

giftCardRefundService_run

Whether to include the gift card refund service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Refund (R)

String (5)

giftCardReloadService_commerceIndicator

Type of transaction. Possible values:

ninternet (default): E-commerce order placed using a website.

nretail: Card-present transaction.

Reload (R)

String (20)

giftCardReloadService_reconciliationID

Reference number for the transaction. See Getting Started with Cybersource Advanced for the Simple Order API for information about order tracking and reconciliation.

This field is supported only on ValueLink.

Reload (O)

String (17)

giftCardReloadService_run

Whether to include the gift card reload service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Reload (R)

String (5)

giftCardReversalService_run

Whether to include the gift card reversal service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Reversal (R)

String (5)

giftCardVoidService_run

Whether to include the gift card void service in your request. Possible values:

ntrue: Include the service in your request.

nfalse (default): Do not include the service in your request.

Void (R)

String (5)

invoiceHeader_clerkID

Your identifier for a clerk.

This field is supported only on ValueLink.

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

String (8)

invoiceHeader_merchantDescriptorCountry

Country in which your business is located. Use the two-character ISO Standard Country Codes.

This value might be displayed on the cardholder’s statement.

This field is supported only on ValueLink.

Activation (O)

Redemption (O)

Refund (O)

Reload (O)

String (2)

merchantDefinedData_ mddField_1 and merchantDefinedData_ mddField_2

Fields that you can use to store information.

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. Personally identifying information includes, but is not limited to, address, payment card number, social security number, driverstate-issued identification number, passport number, and 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 merchantaccount, which will result in a rejection of any and all transaction requests submitted by the merchant after the point of suspension.

This field is supported only on ValueLink.

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

Void (O)

String (20)

merchantID

Your Cybersource merchant ID. Use the same merchant ID for evaluation, testing, and production.

Required for all Cybersource services.

String (30)

merchantReferenceCode

Merchant-generated transaction number or tracking number. Cybersource recommends that you send a unique value for each transaction so that you can perform meaningful searches for the transaction. For information about tracking orders and transactions, see Getting Started with Cybersource Advanced for the Simple Order API.

Required for all Cybersource services.

String (50)

merchantTransactionIdentifier

Identifier that you assign to the transaction.

This field is supported only on ValueLink.

Activation (R)

Redemption (R)

Refund (O)

Reload (O)

Reversal (R)

Void (R)

String (30)

pos_terminalID

Identifier for the terminal at your retail location.

FDC Nashville Global

To have your account configured to support this field, contact Cybersource Customer Support. This value must be a value that FDC Nashville Global issued to you.

ValueLink

You can define this value, but consult ValueLink for requirements.

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

String (4)

pos_trackData

Card’s track 1 and 2 data. This value consists of one of the following:

nTrack 1 data

nTrack 2 data

nData for both tracks 1 and 2

Example  %B4111111111111111^SMITH/JOHN      ^1612101976110000868000000?;4111111111111111=16121019761186800000?

Activation (R if card account number is not included)

Balance Inquiry (R if card account number is not included)

Redemption (R if card account number is not included)

Refund (R if card account number is not included)

Reload (R if card account number is not included)

String (19)

purchaseTotals_currency

Currency for the card that is being activated. For possible values see ISO Standard Currency Codes.

Activation (R)

Redemption (R)

Refund (R)

Reload (R)

String (5)

purchaseTotals_grandTotalAmount

Grand total for the transaction. This value cannot be negative. You can include a decimal point (.), but you cannot include any other special characters. Cybersource truncates the amount to the correct number of decimal places.

Activation (R for non-denominated cards, O for denominated cards)

Redemption (R when giftCard_redemptionType is REDEMPTION or REDEMPTION_ PARTIAL_ ALLOWED)

Refund (R)

Reload (R)

String (15)

transactionLocalDateTime

Local date and time at your physical location. Include both the date and time in this field or leave it blank.

Format: YYYYMMDDhhmmss
where:

nYYYY = year

nMM = month

nDD = day

nhh = hour

nmm = minutes

nss = seconds

Activation (O)

Balance Inquiry (O)

Redemption (O)

Refund (O)

Reload (O)

Void (O)

String (14)