Skip to main content
Vindicia Knowledge Center

The Transaction Object

The Transaction Object

The Transaction object provides information about the failed transactions that are conveyed to Vindicia Retain for recovery. This information is passed to Retain via the billTransactions method.

When reporting a transaction to Vindicia for ChargeGuard, be sure to include the latest or final status information from the transaction object, such as whether the payment processor has approved the transaction and the reason code returned. The reason code values vary, depending on the payment method.

When Vindicia downloads chargebacks from your payment processor for ChargeGuard, it matches them to existing transactions. If you have not yet reported the transaction with which the chargeback is associated, Vindicia Subscribe creates a stub Transaction object in its database using the transaction information in the chargeback that was downloaded. Vindicia Retain then fills the stub when the corresponding transaction is reported.

Transaction Data Members

The table below describes the Transaction object data members.

Note These data members are both input for the billTransactions call, and are returned with the fetchBillingResults call.

When invoking billTransactions to report failed transactions to Retain, populate the Transaction object with the most current information available.

When Retain returns a processed Transaction object, it includes updated data member values. For example: billTransactions is called with a Transaction object with status = Failed. After Retain completes processing, it returns a Transaction object with the following status values: Status = Captured, Failed or RefundedfetchBillingResults returns the final status of Retain processing. Note that the fields authCode, avsCode, and timeStamp contain responses from the payment processor.

The Transaction Object data members:

 

Data Member

Data Type

Description

accountHolderName

string

255 or fewer characters, this is the name of the account holder.

affiliateId

string

Your unique identifier for the partner or affiliate who directed this transaction to you. To implement affiliate tracking, enter this attribute when reporting transactions to Vindicia Retain.

affiliateSubId

string

Your ID for the partner or sub-affiliate who directed this transaction to you. To implement sub-affiliate tracking, enter this attribute when reporting transactions to Vindicia Retain.

amount

decimal

Required. The amount of the transaction; must be a positive number.

authCode

string

Required when calling billTransactions: response code returned by the payment processor for the failed transaction.
When provided by fetchBillingResults, the authCode of the payment processor. 

avsCode

string

The AVS code returned by the payment processor for this transaction. To receive this code, enable AVS with the payment processor.

The AVS response code returned by your payment processor. When reporting a transaction, if you receive the AVS code as a string along with its authorization code (ie Y:2341234234 or Y-2341234234), simply copy it into this field. If you receive the AVS code separate from its authorization code, concatenate them with a colon as a separator, as shown in the previous example.

billingAddressCity

string

The city of the customer address.

billingAddressCountry

string

The customer address country, listed as the ISO-3166-1 two-letter code (for example, US, GB, or FR).

billingAddressCounty

string

The county of the customer address.

billingAddressDistrict

string

The state, province, or district of the customer address.

billingAddressLine1

string

Customer address, first line.

billingAddressLine2

string

Customer address, second line.

billingAddressLine3

string

Customer address, third line.

billingAddressPostalCode

string

Customer address postal code (This field accepts 9-digit input.)

billingFrequency

enum

The billing frequency: hourly, daily, weekly, monthly, quarterly, or annually.

billingStatementIdentifier

string

String to display on customer billing statement when the transaction is captured.

The format and value of this string depends on your payment processor.

(This string can be used to override the default set by your payment processor. Work with Vindicia Client Services if you want to use this field.)

creditCardAccount

string

The credit card account number to use to charge this transaction.

When calling the  reportTransactions method, you need only provide a masked account that provides the 6 digit Bank  Identifying Number (BIN), and the last 4 digits (4111111111111111 would be sent as 411111xxxxxx1111). When providing a masked account enter the SHA1 hash in the creditCardAccountHash
 field.

If you use tokenization and your processor is Worldpay (formerly, Vantive or Litle) or Authorize.net, this field must contain the BIN, which is the first 6 digits of the card number. 

If you use tokenization and your processor is neither of the above, your Capture Rate may improve if you provide this value. This is recommended. 

creditCardAccountHash boolean

A SHA1 hash of the full account number. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this can be left blank and the hash will be calculated. 

For reference the HA1 hash of 4111111111111111 is 68bfb396f35af3876fc509665b3dc23a0930aab1

If you use tokenization with your processor this field is optional.

creditCardAccountUpdated boolean

Returned by Vindicia Retain, this data member indicates whether the Credit Card was updated.

If Vindicia was able to retrieve an updated credit card through Account Updater, this field will be set to true, and the new account information will be returned in the
creditCardAccount and 
creditCardExpirationDate 
fields.

To enable this feature, work with Vindicia Client Services, and provide a valid PGP public key. You must also have completed an Attestation of Compliance (AOC) as a declaration of the results of the service provider's assessment with the Payment Card Industry Data Security Standards (PCI DSS).

creditCardExpirationDate

string

Required when using a credit card, that is, when not using tokenization. The CreditCard expiration date in YYYYMM format, where YYYY is the four-digit year and MM is the two-digit month. For example, the string for July 2007 is 200707.

No validation is performed to check if the expiration date is in the future.

Optional when using tokenization.

currency

string

Required. The ISO 4217 currency code (see www.xe.com/iso4217.htm) for the transaction.

customerId

string

Required. A unique identifier for the customer associated with this transaction.

cvnCode

string

The CVN response code returned by your payment processor.

When reporting a transaction, if you receive the CVN code as a string along with its authorization code (M:2341234234 or M-2341234234), simply copy it into this field.

If you receive the CVN code separate from its authorization code, concatenate them with a colon as a separator, as shown in the previous example.

divisionNumber

string

Required. The division or group number your payment processor associates with this transaction. Chase Paymentech refers to this number as the Division ID; Litle calls it the Report Group; MeS calls it the Profile ID.

WorldPay Report GroupA WorldPay transaction can also have a report group associated with it. This value must be conveyed in a name-value pair; see nameValues above. A WorldPay report group is not a division number.

merchantTransactionId

string

Required. A unique identifier for this Transaction.

nameValues

NameValuePair[]

An array of name-value pairs, used to hold attribute values that are not otherwise contained in this object. Can be used to store custom data for your own internal tracking purposes.

See The NameValuePair Object.

paymentMethodId

string

Required. Your ID associated with the Payment Method for the transaction.

Note: when this value is a token, the length (number of characters) must be within a range acceptable to your payment processor. Worldpay, for example, limits this value to 25 characters. 

paymentMethodIsTokenized

boolean

Flag to indicate that payment method is tokenized. The paymentMethodId contains the token value. When paymentMethodIsTokenized is true, the creditCardAccount and creditCardExpirationDate fields are optional; otherwise they are required.

previousBillingCount

int

The number of times the customer has been successfully billed.

previousBillingDate

dateTime

The date of the last successful billing associated with the subscription.

selectTransactionId

string

Returned by Vindicia Vindicia Retain; this is the unique ID, assigned by Retain, used when billing the transaction after receiving a billTransactions call.

status

TransactionStatusType

Required. Defines the Transaction status upon reporting to Vindicia.This is a 255 byte string. For a list of possible values, see TransactionStatusType Values. Typically this value is Failed

subscriptionId

string

Required. Unique identifier of the subscription associated with this transaction.

subscriptionStartDate

dateTime

A timestamp indicating the date of the first successful billing associated with the subscription. If unspecified, the value defaults to today and the current time.

timestamp

dateTime

Required. A timestamp specifying the date and time this transaction occurred. Be sure to include this attribute in reported transactions. If you do not, timestamp defaults to the current time.

Example: '2019-08-21T09:12:34-04:00' is 21 August 2019, 9:12:34 AM in the US/Eastern timezone.

Note that when omitted, the time zone defaults to US/Pacific, that is, '2019-08-21T09:12:34' becomes US/Pacific, or '2019-08-21T09:12:34-07:00'. The -07:00 is the offset from UTC, for US/Pacific on this date. Note also that since the offset from UTC varies by locale-specific seasonal offsets, (US daylight savings or EU summer time, among other others) this value should not be hard coded but set programmatically when the time stamp is defined.

VID

string

The Vindicia Globally Unique Identifier (GUID) for this object. This field is created by Vindicia and is provided to serve as a unique ID for every transaction. The merchantTransactionId is generally used instead of the VID to identify a transaction.

Do not specify this value when creating a new Transaction object. Vindicia Retain populates this field and returns it in fetchBillingResults calls.

TransactionStatusType Values

Defines the transaction status upon reporting to Vindicia.

 

Data Members

Data Type

Description

BillingNotAttempted

string

The transaction was not processed by Vindicia Retain.

Cancelled

string

Status returned when transaction submitted to Vindicia Retain is refunded before Retain processing has started. 

Captured

string

Status indicating the payment processor has charged the customer payment method.

Captured status means the payment processor has agreed to pay and money will be transferred. 

Failed

string

The transaction did not authorize or capture successfully.

Refunded

string

Transaction has been refunded.

This status is returned both when refundTransaction is called, and when Vindicia Subscribe proactively refunds a transaction to avoid a chargeback.

TransactionValidationResponse Values

Defines the status returned when transactions are submitted to Vindicia Retain.

Note The TransactionValidationResponse array returns only transactions with errors; transactions processed without errors have no status values returned. (An empty array means there were no errors.) Use this array to take actions on the failures. Transactions with errors are not processed by Retain. Correct all errors and resubmit the transactions to Retain for processing.

TransactionValidationResponse values are summarized in the table below.

Data Members

Data Type

Description

code

int

Numeric code indicating the type of issue that was encountered. For more information, see Vindicia Retain Return Codes.

description

string

Description of the issue encountered.

The description is not saved by Vindicia Retain, and has no size limit. The meaningful data is usually located within the first 512 bytes.

merchantTransactionId

string

Your unique ID for the submitted transaction.

For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top