Velocity Developer Resources
API Docs
Base Transaction Data Elements
The following Base Transaction data elements are required in all transactions (unless noted otherwise), regardless of transaction class.
Note: While the Base Transaction data elements are required, your application cannot send a transaction containing only Base Transaction data elements. Service class-specific transaction data is required to successfully process any Bankcard, Electronic Checking, and/or Stored Value transactions.
Refer to Bankcard Transaction Data Elements for all Bankcard-specific data elements.
Refer to Electronic Checking Data Elements for all Electronic Checking-specific data elements.
Refer to Stored Value Data Elements for all Stored Value Account-specific data elements.
Activation
Contains information for activating an account. Required.
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addendum. Optional. | Object |
Addendum
The Addendum object is used to pass optional service-specific information. It is not necessary to pass this object unless specifically directed to do so by your Implementation Support Specialist. Optional.
| Parameter | Description | Data Type |
| Unmanaged | Unmanaged addenda. Optional. | Object |
AddressInfo
Contains address information for either the merchant or customer. Optional.
| Parameter | Description | Data Type |
| City | City. Required. | String |
| CountryCode | Country Code. Required. | Enum |
| PostalCode | Postal or ZIP Code. Required. | String |
| StateProvince | State or Province. Optional. | String |
| Street1 | Street Address Line 1. Required. | String |
| Street2 | Street Address Line 2. Optional. | String |
Adjust
Contains information for adjusting the amount of a transaction. Required.
Important! The following class provides differenceData support across all Service Classes (BCP, ECK and SVA).
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| Amount | Positive or negative amount by which to change the original authorization amount. Required. | Decimal |
| TipAmount | Positive amount added to the total as a tip. Optional. | Decimal |
| TransactionId | Transaction Id of the authorization to adjust. Required. | String |
AlternativeMerchantData
Specifies alternative merchant data that appears on accountholder statements. Subject to Issuer discretion. Optional.
| Parameter | Description | Data Type |
| Address | Specifies alternative merchant address information. Optional. | Object |
| CustomerServiceInternet | Specifies an alternative customer service web URL or Email address. Conditional, required for Ecommerce transactions. | String |
| CustomerServicePhone | Specifies an alternative customer service phone number. Conditional, required for MOTO transactions. | String |
| Description | Specifies a description of the product or service purchased that is recognizable to the account holder. Optional. | String |
| MerchantId | Specifies an alternative merchant location Id or vendor code. Optional. | String |
| Name | Specifies an alternative merchant name or DBA name. Required. | String |
| SIC | Specifies the Standard Industry Code or Merchant Category Code that identifies the alternative merchant industry classification. Optional. | String |
BillPayServiceData
Specifies the bill payment service name and address for PINless Debit bill payment. Conditional, required if different from merchant name and address.
| Parameter | Description | Data Type |
| CompanyAddress | Address of the bill payment service. Required. | Object |
| CompanyName | Name of the bill payment service. Required. | String |
Capture
Contains information for capturing a transaction for settlement. Required.
Important! The following class provides support across all service classes (BCP, ECK and SVA).
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| TransactionId | Transaction Id of the authorization to capture. Required. | String |
CustomerInfo
Contains information about the customer. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction.
| Parameter | Description | Data Type |
| Address | Parameterized address. Optional. | Object |
| BusinessName | Company name. Optional. | String |
| Email address. Optional. | String | |
| Fax | Primary fax number. Optional. | String |
| Name | Parameterized full name. Optional. | Object |
| Phone | Primary telephone number. Optional. | String |
DriversLicense
Contains driver’s license information for the customer. Optional.
| Parameter | Description | Data Type |
| Number | Driver’s license number. Required. | String |
| State | State or Province of issue of customer’s drivers license. Required. | Enum |
| Track1 | Track 1 data read off of the driver’s license magnetic stripe. Should not include the sentinels and LRC. Optional. | String |
| Track2 | Track 2 data read off of the driver’s license magnetic stripe. Should not include the sentinels and LRC. Optional. | String |
Manage
Contains information for updating an account. Required.
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addendum. Optional. | Object |
| TransactionId | Transaction Identifier corresponding to the transaction to update. Required. | String |
NameInfo
Contains information about the customer name. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction.
| Parameter | Description | Data Type |
| First | First name. Required. | String |
| Last | Last name. Required. | String |
| Middle | Middle name or initial. Optional. | String |
| Suffix | Suffix. Optional. | String |
| Title | Title. Optional. | String |
PayeeData
Specifies the payee information for PINless Debit bill payment. Conditional, required if transaction is PINless Debit.
| Parameter | Description | Data Type |
| AccountNumber | Customer account number with company receiving payment. Required. | String |
| CompanyName | Name of the company receiving payment. Required. | String |
| Phone | Phone number of the company receiving payment. Required. | String |
PersonalInfo
Contains a customer’s sensitive personal information. Optional.
| Parameter | Description | Data Type |
| Company | Company name. Optional. | String |
| DateOfBirth | The customer’s date of birth. Optional. | DateTime |
| DriversLicense | The customer’s driver’s license information. Optional. | Object |
| EmployeeIdNumber | Employee identification number, which can be used an an alternate form of identification. Optional. | String |
| Gender | The customer’s gender. Optional. | String |
| GovernmentIdNumber | Government issued identification number, which can be used an an alternate form of identification. Optional. | String |
| MilitaryIdNumber | Military issued identification number, which can be used an an alternate form of identification. Optional. | String |
| SocialSecurityNumber | The customer’s social security number. Optional. | String |
| TaxId | The customer’s federal tax identification number. Optional. | String |
PINlessDebitData
Collection of transaction details related to PINless Debit cards. Conditional, optional when processing a recurring or installment MOTO or Ecommerce transaction with a PIN Debit card without entering a PIN.
| Parameter | Description | Data Type |
| BillPayServiceData | Specifies the bill payment service name and address for PINless Debit bill payment. Conditional, required if different from merchant name and address. | Object |
| PayeeData | Specifies the payee information for PINless Debit bill payment. Required. | Object |
RBSData
If submitted, on approval the customer and payment information will be inserted into the RBS system.
| Parameter | Description | Data Type |
| CreateRBSEntry | Indicates that this customer should be added to RBS. Optional. | Boolean |
| CustomerId | The Identifier to assign to the newly created customer. Optional. | String |
| PaymentId | The Identifier to assign to the newly created payment method. Optional. | String |
RBSResponse
Result of the attempt to insert a customer and payment method into the RBS. Conditional.
| Parameter | Description | Data Type |
| Message | Text indicateing success or failure. Expected. | String |
| CustomerId | The Identifier assigned to the newly created customer. Expected. | String |
| PaymentId | The Identifier assigned to the newly created payment method. Expected. | String |
Response
Contains detailed transaction response data always returned to the client application. Expected.
For Bankcard transactions, the data elements contained in Response includes values for both BankcardTransactionResponse as well as BankcardTransactionResponsePro. For Bankcard Capture transactions, the data elements contained in Response are returned in BankcardCaptureResponse.
Note: If the application does not support Level2, Level3, and/or Managed Billing, only the values included as part of BankcardTransactionResponse need to be referenced.
For Electronic Checking transactions, the data elements contained in Response are returned in ElectronicCheckingTransactionResponse. For Electronic Checking Capture transactions, the data elements contained in Response are returned in ElectronicCheckingCaptureResponse.
For Stored Value Account transactions, the data elements contained in Response are returned in StoredValueTransactionResponse. For Stored Value Account Capture transactions, the data elements contained in Response are returned in StoredValueCaptureResponse.
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| CaptureState | Indicates the state of the transaction as it relates to capture. Required. | Enum |
| OriginatorTransactionId | Transaction identifier assigned by Commerce Web Services before sending the transaction to the service provider. May be useful for identifying the transaction when contacting the service offline. This will always be returned to the client application. Required. | String |
| Reference | Specifies user or customer reference data echoed from the request. Optional. | String |
| RBSResponse | Result of an attempt to add the customer to RBS. Conditional. | Object |
| ServiceTransactionDateTime | The local date and time of the transaction as calculated by the service. Expected, although amount of detail varies between services. | Object |
| ServiceTransactionId | Transaction identifier assigned by the service provider. May be useful for identifying the transaction when contacting the service provider offline. Expected. | String |
| Status | Shows whether transaction was a success or failure. Required. | Enum |
| StatusCode | Status code returned from the service. This is required in the PTLS Schema for all CWS transactions. Required. | String |
| StatusMessage | Verbose message describing the status of the transaction.Optional. | String |
| TransactionId | Transaction Id that may be used for subsequent CWS transactions. Expected. | String |
| TransactionState | Indicates the current state of a transaction. Required. | Enum |
Return
Contains information required when funds for a captured transaction need to be returned to the cardholder account. Required.
Important!! The following class provides differenceData support across all service classes (BCP, ECK and SVA).
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| TransactionDateTime | The local date and time of the transaction as calculated by the merchant and printed on the customer receipt. This field should contain a timezone offset representing the timezone in which the transaction is taking place. Optional, but highly recommended. | String |
| TransactionId | Transaction Id of the authorization to return. Required. | String |
ServiceTransactionDateTime
The local date and time of the transaction as calculated by the service provider. If present in the response, this same data element and value must be provided when settling a subsequent authorization completion. Optional.
| Parameter | Description | Data Type |
| Date | Date. Optional. | String |
| Time | Time. Optional. | String |
| TimeZone | Timezone. Optional. | String |
SummaryData
Summary information for credit and debit totals. Expected.
| Parameter | Description | Data Type |
| CashBackTotals | Totals for cash back transactions. Expected. | Object |
| CreditReturnTotals | Totals for returned credit transactions. Expected. | Object |
| CreditTotals | Totals for credit transactions. Expected. | Object |
| DebitReturnTotals | Totals for returned debit transactions. Expected. | Object |
| DebitTotals | Totals for debit transactions. Expected. | Object |
| NetTotals | Net totals for the batch. Expected. | Object |
| VoidTotals | Totals for voided transactions. Expected. | Object |
SummaryTotals
Contains net amount and total item count. Expected.
| Parameter | Description | Data Type |
| Count | Total item count. Optional. | Integer |
| NetAmount | Net amount. Optional. | Decimal |
Transaction
Contains information which may be required to send a transaction to a service provider. Required.
Contains information which may be required to send a transaction to a service provider. Required.
Note:For Bankcard transactions, you must send in BankcardTransaction as well. For Electronic Checking transactions, you must send in ElectronicCheckingTransaction, and for Stored Value transactions, you must send in StoredValueTransaction.
The following Transaction Processing operation signatures accept Transaction as a parameter:
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| CustomerData | Details about the customer. Optional | Object |
| RBSData | Options for controlling adding the customer and payment to RBS. Will not affect the result of the transaction. Optional. | Object |
| ReportingData | Additional data to be printed on reports. Optional. | Object |
| TenderData | Details about the tender used for the transaction. Required. | Object |
| TransactionData | Details about the transaction. Required. | Object |
TransactionCustomerData
Contains information about the customer. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction.
| Parameter | Description | Data Type |
| BillingData | Customer billing data. Optional. | Object |
| CustomerId | Reference number used by the merchant to identify the customer. Optional. | String |
| CustomerTaxId | Customer’s federal or VAT identification number. Optional. | String |
| ShippingData | Customer shipping data. Optional. | Object |
TransactionData
Base class object which contains information for a specific transaction. Required.
| Parameter | Description | Data Type |
| Amount | Authorization amount of the transaction. Required. | Decimal |
| CampaignId | Specifies the identifier associated with a campaign-enabled Commerce Playlist, such as Multi-Party Payments (MPP). Optional. | String |
| CurrencyCode | Transaction currency code as defined by the International Standards Organization (ISO). Required. | Enum |
| IgnoreDuplicateCheck | If true, no dupcheck will occure. If false, use the merchant setting to decide if dupcheck should occure. | Boolean |
| Reference | Specifies user or customer reference data that is used for tracking or reporting purposes that may be echoed back in the response. Optional. | String |
| TransactionDateTime | The local date and time of the transaction as calculated by the merchant and printed on the customer receipt. This field should contain a timezone offset representing the timezone in which the transaction is taking place. Optional, but highly recommended. | String |
TransactionReportingData
Contains additional transaction data to be printed on reports. Conditional, allowed by some service providers. If this value is set on the transaction and not allowed by the service provider, the data will not be present on the transaction.
| Parameter | Description | Data Type |
| Comment | Comment about the transaction. Optional. | String |
| Description | Transaction description. Optional. | String |
| Reference | Merchant or customer reference field that is used for tracking or reporting purposes. Optional. | String |
TransactionTenderData
Base class object which contains information about the tender used for a specific transaction. Required.
Note: For Bankcard transactions, you must send in BankcardTenderData. For Electronic Checking transactions, you must send in ElectronicCheckingTenderData, and for Stored Value transactions, you must send in StoredValueTenderData.
| Parameter | Description | Data Type |
| EncryptionKeyId | Specifies the identifier for the encryption key used for card data encryption, such as the key serial number for DUK/PT encryption. Conditional, required if SecurePaymentAccountData is used. | String |
| PaymentAccountDataToken | Token specified by offsite cardholder data storage service providers to retrieve stored payment account data. May be used in place of detailed tender data. Optional.
Note:For more information about support for PaymentAccountDataToken, refer to Tokenization. |
String |
| SecurePaymentAccountData | Data collected from a magnetic stripe and protected by an encrypting card reader. Track 2 data must be provided. Conditional, at least one of CardData, PaymentAccountDataToken, or SecurePaymentAccountData must be provided. | String |
| SwipeStatus | Specifies the status of the card swipe as returned by the card reader. Optional. | String |
Undo
Contains information for undoing (voiding) a transaction. Required.
Important!!The following class provides differenceData support across all service classes (BCP, ECK and SVA).
| Parameter | Description | Data Type |
| Addendum | Managed and unmanaged addenda. Optional. | Object |
| TransactionId | Transaction Id of the authorization to void. Required. | String |
Unmanaged
Can be used to pass service-specific information such as username/password or session token credentials. Optional. Please consult your integration specialist before attempting to use this field.
| Parameter | Description | Data Type |
| Any | One or more XML strings. Required. | String |
Updated: June 2, 2017
Need Help?
SUBMIT A DEVELOPER SUPPORT REQUEST
Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341
Support
Sales
