DP API: Transaction Variables

DP API: Transaction Variables

Sale/Authorization/Credit/Validate/Offline

Variable NameDescription
type*The type of transaction to be processed.
Values: ‘sale’, ‘auth’, ‘credit’, ‘validate’, or ‘offline’
username*Username assigned to merchant account.
Also requires ‘password’. Using the ‘security_key’ variable in the same request will result in an error
password*Password for the specified username.
Also requires ‘username’. Using the ‘security_key’ variable in the same request will result in an error
security_key*API Security Key assigned to a merchant account.
Using the ‘username’ or ‘password’ variables in the same request will result in an error
ccnumber**Credit card number.
ccexp**Credit card expiration date.
Format: MMYY
cvvThe card security code. While this is not required, it is strongly recommended.
checkname***The name on the customer’s ACH account.
checkaba***The customer’s bank routing number.
checkaccount***The customer’s bank account number.
account_holder_typeThe type of ACH account the customer has.
Values: ‘business’ or ‘personal’
account_typeThe ACH account entity of the customer.
Values: ‘checking’ or ‘savings’
sec_codeThe Standard Entry Class code of the ACH transaction.
Values: ‘PPD’, ‘WEB’, ‘TEL’, or ‘CCD’
amountTotal amount to be charged. For validate, the amount must be omitted or set to 0.00.
Format: x.xx
surchargeSurcharge amount.
Format: x.xx
currencyThe transaction currency. Format: ISO 4217
payment***The type of payment.
Default: ‘creditcard’
Values: ‘creditcard’ or ‘check’
processor_idIf using Multiple MIDs, route to this processor (processor_id is obtained under Settings->Transaction Routing in the Control Panel).
authorization_code‡Specify authorization code. For use with “offline” action only.
dup_secondsSets the time in seconds for duplicate transaction checking on supported processors. Set to 0 to disable duplicate checking.
descriptorSet payment descriptor on supported processors.
descriptor_phoneSet payment descriptor phone on supported processors.
descriptor_addressSet payment descriptor address on supported processors.
descriptor_citySet payment descriptor city on supported processors.
descriptor_stateSet payment descriptor state on supported processors.
descriptor_postalSet payment descriptor postal code on supported processors.
descriptor_countrySet payment descriptor country on supported processors.
descriptor_mccSet payment descriptor mcc on supported processors.
descriptor_merchant_idSet payment descriptor merchant id on supported processors.
descriptor_urlSet payment descriptor url on supported processors.
billing_methodShould be set to ‘recurring’ to mark payment as a recurring transaction or ‘installment’ to mark payment as an installment transaction.
Values: ‘recurring’, ‘installment’
billing_numberSpecify installment billing number, on supported processors. For use when “billing_method” is set to installment.
Values: 0-99
billing_totalSpecify installment billing total on supported processors. For use when “billing_method” is set to installment.
order_templateOrder template ID.
order_descriptionOrder description.
Legacy variable includes: orderdescription
orderidOrder Id
ipaddressIP address of cardholder, this field is recommended.
Format: xxx.xxx.xxx.xxx
tax****Total tax amount.
shipping****Total shipping amount
ponumber****Original purchase order
first_nameCardholder’s first name.
Legacy variable includes: firstname
last_nameCardholder’s last name
Legacy variable includes: lastname
companyCardholder’s company
address1Card billing address
address2Card billing address, line 2
cityCard billing city
stateCard billing state.
Format: CC
zipCard billing zip code
countryCard billing country.
Country codes are as shown in ISO 3166. Format: CC
phoneBilling phone number
faxBilling fax number
emailBilling email address
social_security_numberCustomer’s social security number, checked against bad check writers database if check verification is enabled.
drivers_license_numberDriver’s license number.
drivers_license_dobDriver’s license date of birth.
drivers_license_stateThe state that issued the customer’s driver’s license.
shipping_firstnameShipping first name
shipping_lastnameShipping last name
shipping_companyShipping company
shipping_address1Shipping address
shipping_address2Shipping address, line 2
shipping_cityShipping city
shipping_stateShipping state
Format: CC
shipping_zipShipping zip code
shipping_countryShipping country
Country codes are as shown in ISO 3166. Format: CC
shipping_emailShipping email address
merchant_defined_field_#You can pass custom information in up to 20 fields.
Format: merchant_defined_field_1=Value
customer_receiptIf set to true, when the customer is charged, they will be sent a transaction receipt.
Values: ‘true’ or ‘false’
signature_imageCardholder signature image. For use with “sale” and “auth” actions only.
Format: base64 encoded raw PNG image. (16kiB maximum)
cardholder_auth‡‡Set 3D Secure condition.
Values: ‘verified’ or ‘attempted’
eci‡‡E-commerce indicator.
Values: ‘0’, ‘1’, ‘2’, ‘5’, ‘6’, or ‘7’
cavv‡‡Cardholder authentication verification value.
Format: base64 encoded
xid‡‡Cardholder authentication transaction id.
Format: base64 encoded
source_transaction_idSpecifies a payment gateway transaction id in order to associate payment information with a Subscription or Customer Vault record. Must be set with a ‘recurring’ or ‘customer_vault’ action.
  
Recurring specific fields
recurringRecurring action to be processed.
Values: add_subscription
plan_idCreate a subscription tied to a Plan ID if the sale/auth transaction is successful.
plan_paymentsThe number of payments before the recurring plan is complete.
Note: Use ‘0’ for ‘until canceled’
plan_amountThe plan amount to be charged each billing cycle.
Format: x.xx
day_frequencyHow often, in days, to charge the customer. Cannot be set with ‘month_frequency’ or ‘day_of_month’.
month_frequencyHow often, in months, to charge the customer. Cannot be set with ‘day_frequency’. Must be set with ‘day_of_month’.
Values: 1 through 24
day_of_monthThe day that the customer will be charged. Cannot be set with ‘day_frequency’. Must be set with ‘month_frequency’.
Values: 1 through 31 – for months without 29, 30, or 31 days, the charge will be on the last day
start_dateThe first day that the customer will be charged.
Format: YYYYMMDD
Customer Vault specific fields
customer_vaultAssociate payment information with a Customer Vault record if the transaction is successful.
Values: ‘add_customer’ or ‘update_customer’
customer_vault_idSpecifies a customer vault id. If not set, the payment gateway will randomly generate a customer vault id.
Stored Credentials (CIT/MIT)
initiated_byWho initiated the transaction.
Values: ‘customer’ or ‘merchant’
initial_transaction_idOriginal payment gateway transaction id.
stored_credential_indicatorThe indicator of the stored credential.
Values: ‘stored’ or ‘used’
Use ‘stored’ when processing the initial transaction in which you are storing a customer’s payment details (customer credentials) in the Customer Vault or other third-party payment storage system.
Use ‘used’ when processing a subsequent or follow-up transaction using the customer payment details (customer credentials) you have already stored to the Customer Vault or third-party payment storage method.
Level III specific order fields
shippingFreight or shipping amount included in the transaction amount
Default: ‘0.00’
Format: x.xx
taxThe sales tax, included in the transaction amount, associated with the purchase. Setting tax equal to ‘-1’ indicates an order that is exempt from sales tax.
Default: ‘0.00’
Format: x.xx
ponumber†Purchase order number supplied by cardholder
orderid†Identifier assigned by the merchant. This defaults to gateway transaction id.
shipping_country†Shipping country (e.g. US)
Format: CC
shipping_postal†Postal/ZIP code of the address where purchased goods will be delivered. This field can be identical to the ‘ship_from_postal’ if the customer is present and takes immediate possession of the goods.
ship_from_postal†Postal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code.
summary_commodity_code†4 character international description code of the overall goods or services being supplied. The acquirer or processor will provide a list of current codes.
duty_amountAmount included in the transaction amount associated with the import of purchased goods.
Default: ‘0.00’
Format: x.xx
discount_amountAmount included in the transaction amount of any discount applied to complete order by the merchant.
Default: ‘0.00’
Format: x.xx
national_tax_amountThe national tax amount included in the transaction amount.
Default: ‘0.00’
Format: x.xx
alternate_tax_amountSecond tax amount included in the transaction amount in countries where more than one type of tax can be applied to the purchases.
Default: ‘0.00’
Format: x.xx
alternate_tax_idTax identification number of the merchant that reported the alternate tax amount.
vat_tax_amountContains the amount of any value added taxes which can be associated with the purchased item.
Default: ‘0.00’
Format: x.xx
vat_tax_rateContains the tax rate used to calculate the sales tax amount appearing. Can contain up to 2 decimal places, e.g. 1% = 1.00.
Default: ‘0.00’
Format: x.xx
vat_invoice_reference_numberInvoice number that is associated with the VAT invoice.
customer_vat_registrationValue added tax registration number supplied by the cardholder.
merchant_vat_registrationGovernment assigned tax identification number of the merchant for whom the goods or services were purchased from.
order_datePurchase order date, defaults to the date of the transaction.
Format: YYMMDD
Level III specific line item detail fields
item_product_code_#†Merchant defined description code of the item being purchased.
item_description_#†Description of the item(s) being supplied.
item_commodity_code_#†International description code of the individual good or service being supplied. The acquirer or processor will provide a list of current codes.
item_unit_of_measure_#†Code for units of measurement as used in international trade.
Default: ‘EACH’
item_unit_cost_#†Unit cost of item purchased, may contain up to 4 decimal places.
item_quantity_#†Quantity of the item(s) being purchased.
Default: ‘1’
item_total_amount_#†Purchase amount associated with the item. Defaults to: ‘item_unit_cost_#’ x ‘item_quantity_#’ rounded to the nearest penny.
item_tax_amount_#†Amount of tax on specific item, amount should not be included in ‘total_amount_#’.
Default: ‘0.00’
item_tax_rate_#†Percentage representing the value-added tax applied.
Default: ‘0.00’
item_discount_amount_#Discount amount which can have been applied by the merchant on the sale of the specific item. Amount should not be included in ‘total_amount_#’.
item_discount_rate_#Discount rate for the line item. 1% = 1.00.
Default: ‘0.00’
item_tax_type_#Type of value-added taxes that are being used.
item_alternate_tax_id_#Tax identification number of the merchant that reported the alternate tax amount.
*Always required
**Required for credit card transactions
***Required for ACH transactions
****Required for Level 2 transactions
†Required for Level 3 transactions
‡Required for offline transactions
‡‡Required for 3D Secure transactions

Notes:

  • Level II fields are required for Level II processing.
  • Level II and Level III fields are required for Level III processing.
  • You can pass only credit card or e-check transaction variables in a request, not both in the same request.
  • Certain banks may require some optional fields.

Capture

Variable NameDescription
type*Type of transaction.
Values: ‘capture’
username*Username assigned to merchant account.
Also requires ‘password’. Using the ‘security_key’ variable in the same request will result in an error
password*Password for the specified username.
Also requires ‘username’. Using the ‘security_key’ variable in the same request will result in an error
security_key*API Security Key assigned to a merchant account.
Using the ‘username’ or ‘password’ variables in the same request will result in an error
transactionid*Original payment gateway transaction id
amount*Total amount to be settled. This amount must be equal to or less than the original authorized amount.
Format: x.xx
tracking_numberShipping tracking number
shipping_carrierShipping carrier.
Values: ‘ups’, ‘fedex’, ‘dhl’, or ‘usps’
orderidOrder id.
signature_imageCardholder signature image.
Format: base64 encoded raw PNG image. (16kiB maximum)
*Always required

Void

Variable NameDescription
type*Type of transaction.
Values: ‘void’
username*Username assigned to merchant account.
Also requires ‘password’. Using the ‘security_key’ variable in the same request will result in an error
password*Password for the specified username.
Also requires ‘username’. Using the ‘security_key’ variable in the same request will result in an error
security_key*API Security Key assigned to a merchant account.
Using the ‘username’ or ‘password’ variables in the same request will result in an error
transactionid*Original payment gateway transaction id
void_reason**Reason the EMV transaction is being voided.
Values: ‘fraud’, ‘user_cancel’, ‘icc_rejected’, ‘icc_card_removed’, ‘icc_no_confirmation’, or ‘pos_timeout’
payment***The type of payment.
Default: ‘creditcard’
Values: ‘creditcard’ or ‘check’
*Always required
**Conditionally required for EMV transactions
***Required for ACH transactions

Refund

Variable NameDescription
type*Type of transaction.
Values: ‘refund’
username*Username assigned to merchant account.
Also requires ‘password’. Using the ‘security_key’ variable in the same request will result in an error
password*Password for the specified username.
Also requires ‘username’. Using the ‘security_key’ variable in the same request will result in an error
security_key*API Security Key assigned to a merchant account.
Using the ‘username’ or ‘password’ variables in the same request will result in an error
transactionid*Original payment gateway transaction id
amountTotal amount to be refunded. This amount may be equal to or less than the settled amount. Setting the amount to 0.00 will refund the entire amount.
Format: x.xx
payment**The type of payment.
Default: ‘creditcard’
Values: ‘creditcard’ or ‘check’
*Always required
**Required for ACH transactions

Update

Variable NameDescription
type*Type of transactions.
Values: ‘update’
username*Username assigned to merchant account.
Also requires ‘password’. Using the ‘security_key’ variable in the same request will result in an error
password*Password for the specified username.
Also requires ‘username’. Using the ‘security_key’ variable in the same request will result in an error
security_key*API Security Key assigned to a merchant account.
Using the ‘username’ or ‘password’ variables in the same request will result in an error
transactionid*Original payment gateway transaction id
payment**The type of payment.
Default: ‘creditcard’
Values: ‘creditcard’ or ‘check’
tracking_numberShipping tracking number
shippingTotal shipping amount.
Format: x.xx
shipping_postalPostal/ZIP code of the address where purchased goods will be delivered. This field can be identical to the ‘ship_from_postal’ if the customer is present and takes immediate possession of the goods.
ship_from_postalPostal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code.
shipping_countryShipping Country Code.
shipping_carrierShipping carrier.
Values: ‘ups’, ‘fedex’, ‘dhl’, or ‘usps’
shipping_dateShipping date.
Format: YYYYMMDD
order_descriptionOrder Description.
Legacy variable includes: orderdescription
order_dateOrder date.
Format: YYYYMMDD
customer_receiptIf set to true, when the customer is charged, they will be sent a transaction receipt.
Values: ‘true’ or ‘false’
signature_imageCardholder signature image.
Format: base64 encoded raw PNG image. (16kiB maximum)
ponumberCardholder’s purchase order number.
summary_commodity_code4 character international description code of the overall goods or services being supplied. The acquirer or processor will provide a list of current codes.
duty_amountAmount included in the transaction amount associated with the import of purchased goods.
Format: x.xx
discount_amountAmount included in the transaction amount of any discount applied to complete order by the merchant.
Format: x.xx
taxTax amount.
Format: x.xx
national_tax_amountThe national tax amount included in the transaction amount.
Format: x.xx
alternate_tax_amountSecond tax amount included in the transaction amount in countries where more than one type of tax can be applied to the purchases.
Format: x.xx
alternate_tax_idTax identification number of the merchant that reported the alternate tax amount.
vat_tax_amountContains the amount of any value added taxes which can be associated with the purchased item.
vat_tax_rateContains the tax rate used to calculate the sales tax amount appearing. Can contain up to 2 decimal places, e.g. 1% = 1.00.
vat_invoice_reference_numberInvoice number that is associated with the VAT invoice.
customer_vat_registrationValue added tax registration number supplied by the cardholder.
merchant_vat_registrationGovernment assigned tax identification number of the merchant for whom the goods or services were purchased from.
merchant_defined_field_#Merchant Defined Fields.
Format: merchant_defined_field_1=Value
*Always required
**Required for ACH transactions