Transaction Fields and Behaviors

This section provides a detailed explanation of the fields required to process a transaction and the behaviors associated with these fields. Each field includes a description, format, and specific notes for proper usage.

Fields

1. Amount (amount)

• Type: integer
• Description: A positive integer in cents representing how much to charge.
• Required: Yes
• Format: Numeric (in cents)
• Min Length: 1 digit
• Max Length: 8 digits
• Examples:
  • 9 would be $0.09
  • 99999999 would be $999,999.99
• Note: The minimum amount is $0.50 USD when testing in the test environment.

2. Currency (currency)

• Type: string
• Description: Three-letter ISO currency code, in lowercase.
• Required: Yes
• Format: Alphabetic
• Allowed Values:
  • usd

3. Customer ID (customer_id)

• Type: string
• Description: The unique identifier for a customer. A transaction is associated with a customer when a customer ID is included in the sale request.
• Required: Conditional
• Format: Alphanumeric
• Note: customer_id is accepted when none of the following values are present in the request: token_id, card_number.

4. Card ID (card_id)

• Type: string
• Description: The unique identifier for a card.
• Required: Conditional
• Format: Alphanumeric

5. Statement Description (statement_description)

• Type: string
• Description: An arbitrary string to be displayed on your customer’s credit card statement.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 5 characters
• Max Length: 25 characters
• Example: A1 Company

6. Token ID (token_id)

• Type: string
• Description: An ID that represents a credit card or a debit card. This is obtained by using the 'Create a Token' API.
• Required: Conditional
• Format: Alphanumeric
• Note: token_id is accepted when none of the following are present in the request: customer_id, card_number.

7. Capture (capture)

• Type: integer
• Description: Option to capture charge immediately or pre-authorize and capture at a later date.
• Required: Optional
• Format: Boolean
• Default: 1
• Note:
  • 1 represents that the charge has to be captured immediately.
  • 0 represents the charge issues an authorization (or pre-authorization) and will need to be captured later. Uncaptured charges expire in seven days.

8. Card Level (card_level)

• Type: string
• Description: Indicates the extent of information to be provided for a transaction.
• Required: Optional
• Format: Alphabetic
• Default: LEVEL1
• Allowed Values:
  • LEVEL2
  • LEVEL3
• Note: If card_level is not specified, then PAYARC will process the transaction as LEVEL1.

9. Sales Tax (sales_tax)

• Type: integer
• Description: Sales tax amount. The sales tax amount represents a value in cents.
• Required: Optional
• Format: Numeric
• Min Length: 0 digits
• Max Length: 12 digits
• Examples:
  • 9 would be $0.09
  • 999999999999 would be $9,999,999,999.99
• Note: Applicable for LEVEL2 or LEVEL3 transactions. If the transaction is tax-exempt, then enter 0 for the value.

10. Terminal ID (terminal_id)

• Type: string
• Description: The terminal ID from which the transaction was made.
• Required: Optional
• Format: Alphanumeric

11. Tip Amount (tip_amount)

• Type: integer
• Description: The tip amount of the transaction.
• Required: Optional
• Format: Numeric
• Min Length: 1 digit
• Examples:
  • 9 would be $0.09
  • 999999999999 would be $9,999,999,999.99

12. Purchase Order (purchase_order)

• Type: string
• Description: The value used by the customer to identify an order. Issued by the buyer to the seller.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 25 characters
• Note: Applicable for LEVEL2 or LEVEL3 transactions.

13. Order Date (order_date)

• Type: string
• Description: The date the order was processed.
• Required: Optional
• Format: Date in YYYY-MM-DD format
• Example: 2021-01-31
• Note: Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

14. Customer Reference ID (customer_ref_id)

• Type: string
• Description: The reference identifier supplied by the commercial cardholder.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 17 characters
• Note: Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

15. Ship To ZIP (ship_to_zip)

• Type: integer
• Description: The postal code for the address to which the goods are being shipped.
• Required: Optional
• Format: Alphanumeric
• Min Length: 0 digits
• Max Length: 10 digits
• Note: Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

16. AMEX Descriptor (amex_descriptor)

• Type: string
• Description: The value of the Transaction Advice Addendum field that displays descriptive information about a transaction on a customer's AMEX card statement.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 5 characters
• Max Length: 40 characters
• Note: Applicable for LEVEL2 transactions for AMEX only.

17. Supplier Reference Number (supplier_reference_number)

• Type: string
• Description: This field contains a reference number that is used by AMEX to obtain supporting information on a transaction from a supplier. The number can be any combination of characters and numbers defined by the merchant.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 9 characters
• Note: Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

18. Tax Amount (tax_amount)

• Type: integer
• Description: The tax amount.
• Required: Optional
• Format: Numeric
• Min Length: 1 digit
• Max Length: 14 digits
• Examples:
  • 99 would be $0.99
  • 999999999999 would be $9,999,999,999.99
• Note: Applicable for all LEVEL3 transactions. If tax amount is $0.00, enter 0 as the value.

19. Tax Category (tax_category)

• Type: string
• Description: The type of tax. Formerly established through Tax Category messages.
• Required: Optional
• Format: Alphabetic
• Allowed Values:
  • SERVICE
  • DUTY
  • VAT
  • ALTERNATE
  • NATIONAL
  • TAX_EXEMPT

20. Customer VAT Number (customer_vat_number)

• Type: string
• Description: Government-assigned tax identification number of the merchant. Indicates the customer's government-assigned tax identification number or the identification number assigned to their purchasing company by the tax authorities.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 13 characters
• Note: Applicable for LEVEL3 transactions.

21. Summary Commodity Code (summary_commodity_code)

• Type: string
• Description: The international description code of the overall goods or services being supplied.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 4 characters
• Note: Applicable for LEVEL3 transactions. Merchants can request an updated listing of the currently defined codes.

22. Shipping Charges (shipping_charges)

• Type: integer
• Description: The dollar amount for shipping or freight charges applied to a product or transaction.
• Required: Optional
• Format: Numeric
• Min Length: 0 digits
• Max Length: 4 digits
• Examples:
  • 9 would be `$0.09'
  • '9999' would be '$99.99'
  • Note: Applicable for LEVEL3 transactions. If shipping costs are '$0.00' enter '0' as the value.

23. Duty Charges (duty_charges)

• Type: integer
• Description: Indicates the total charges for any import or export duties included in the order.
• Required: Optional
• Format: Numeric
• Min Length: 1 digit
• Max Length: 12 digits
• Examples:
  • 9 would be $0.09
  • 999999999999 would be $9,999,999,999.99
• Note: Applicable for LEVEL3 transactions.

24. Ship From ZIP (ship_from_zip)

• Type: integer
• Description: The postal code for the address from which the goods were shipped.
• Required: Optional
• Format: Alphanumeric
• Min Length: 0 digits
• Max Length: 10 digits
• Note: Applicable for LEVEL3 transactions.

25. Destination Country Code (destination_country_code)

• Type: string
• Description: The destination country code indicator.
• Required: Optional
• Format: Alphanumeric
• Min Length: 1 character
• Max Length: 4 characters
• Note: Applicable for LEVEL3 transactions.

26. Tax Type (tax_type)

• Type: string
• Description: The type of tax.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 50 characters
• Examples:
  • VAT
  • NATIONAL
  • Service Tax
• Note: Applicable for LEVEL3 transactions.

27. VAT Invoice (vat_invoice)

• Type: string
• Description: The Value Added Tax (VAT) invoice number associated with the transaction.
• Required: Optional
• Format: Alphanumeric and Whitespace
• Min Length: 0 characters
• Max Length: 15 characters
• Note: Applicable for LEVEL3 transactions.

28. Tax Rate (tax_rate)

• Type: integer
• Description: The type of tax rate.
• Required: Optional
• Format: Numeric
• Min Length: 0 digits
• Max Length: 12 digits
• Note: This field is used if tax_category is not used. The default sales tax rate in percentage must be between 0.1% - 22%. Applicable for LEVEL3 transactions.

29. Email (email)

• Type: string
• Description: The cardholder’s email address.
• Required: Optional
• Format: Alphanumeric and Special Characters
• Min Length: 5 characters
• Max Length: 40 characters
• Example: [email protected]

30. CVV (cvv)

• Type: integer
• Description: The three or four-digit security code on the card.
• Required: Conditional
• Format: Numeric
• Min Length: 3 digits
• Max Length: 4 digits
• Note: This field is required when customer_id is passed and the card is not authorized/verified. Refer to the Create a Token API to authorize a card.

31. Phone Number (phone_number)

• Type: integer
• Description: The cardholder’s phone number.
• Required: Optional
• Format: Numeric
• Min Length: 2 digits
• Max Length: 11 digits
• Example: 8772036624

32. Surcharge (surcharge)

• Type: integer
• Description: A positive number representing the surcharge percentage to be added for the charge.
• Required: Optional
• Format: Numeric
• Min Length: 0 digits
• Max Length: 4 digits

33. AVS Parameters (avs_parameters)

• Type: integer
• Description: AVS transaction parameters that provide post-authorization instructions.
• Required: Optional
• Format: Numeric
• Min Value: 1
• Max Value: 6
• Allowed Values:
  • 1 = If AVS ZIP matches but AVS Street Fails, then void transaction.
  • 2 = If AVS ZIP matches but AVS Street Fails, then do nothing.
  • 3 = If AVS ZIP fails but AVS Street matches, then void transaction.
  • 4 = If AVS ZIP fails but AVS Street matches, then do nothing.
  • 5 = If AVS ZIP fails and AVS Street fails, then void transaction.
  • 6 = If AVS ZIP fails and AVS Street fails, then do nothing.

34. BIN Location Parameters (bin_location_parameters)

• Type: integer
• Description: BIN location transaction parameters that provide post-authorization instructions.
• Required: Optional
• Format: Numeric
• Min Value: 1
• Max Value: 2
• Allowed Values:
  • 1 = If BIN is not equal to USA, then void.
  • 2 = If BIN is not equal to USA and Canada, then void.

35. BIN Card Type Parameters (bin_card_type_parameters)

• Type: integer
• Description: BIN card type transaction parameters that provide post-authorization instructions.
• Required: Optional
• Format: Numeric
• Min Value: 1
• Max Value: 4
• Allowed Values:
  • 1 = If BIN is a credit card then void.
  • 2 = If BIN is a debit card then void.
  • 3 = If BIN is a prepaid card then void.
  • 4 = If BIN is a prepaid and/or debit card then void.

36. Metadata (metadata)

• Type: string
• Description: Metadata is useful for storing additional, structured information on an object. For example, you could store your user’s full name and corresponding unique identifier from your system on a Charge object. You can specify up to 50 keys, with key names up to 20 characters long and values up to 100 characters long. Both keys and values should be strings, and the JSON format should resemble a hash.
• Required: Conditional
• Format: JSON
• Max Key Number: 50
• Max Key Length: 20 characters
• Max Value Length: 100 characters
• Example: {"FullCustomerName" : "John Smith", "CustomerID" : "1234567890"}

37. Do Not Send Email to Customer (do_not_send_email_to_customer)

• Type: string
• Description: To prevent sending an email to the customer for a transaction. By default, the system will send an email.
• Required: Optional
• Format: Yes/No

38. Do Not Send SMS to Customer (do_not_send_sms_to_customer)

• Type: string
• Description: To prevent sending an SMS to the customer. To prevent sending an SMS, the value must be yes. If not present, an SMS will be sent.
• Required: Optional
• Format: Yes/No

39. Card Number (card_number)

• Type: Numeric
• Description: The 14-19 digit card number used for the transaction. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

40. Card Expiration Month (exp_month)

• Type: Integer
• Description: The month value displayed on the card used for the transaction. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

41. Card Expiration Year (exp_year)

• Type: Integer
• Description: The YYYY value mentioned on the card used for the transaction. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

42. Cardholder Name (card_holder_name)

• Type: String
• Description: Name of the cardholder as mentioned on the card used to carry out a transaction. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

43. Address Line 1 (address_line1)

• Type: String
• Description: The cardholder's billing address for line 1. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Min Length: 1 character
• Max Length: 200 characters
• Required: Optional
• Note: Payfac Max Length: 30 characters

44. Address Line 2 (address_line2)

• Type: String
• Description: The cardholder's billing address for line 2. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Min Length: 1 character
• Max Length: 200 characters
• Required: Optional
• Note: Payfac Max Length: 30 characters

45. City (city)

• Type: String
• Description: The cardholder's city name. Can be a City/District/Suburb/Town/Village. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Max Length: 30 characters
• Required: Optional

46. State (state)

• Type: String
• Description: The cardholder's state name. Can be State/County/Province/Region. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Min Length: 1 character
• Max Length: 50 characters
• Required: Optional

47. Zipcode (zip)

• Type: Integer
• Description: The cardholder's billing ZIP code. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

48. Country (country)

• Type: Integer
• Description: The cardholder's country name. The field is accepted when none of the following are present in the request. customer_id, token_id.
• Required: Optional

LEVEL 2 and LEVEL 3 Card Data

Overview

LEVEL 2 Card Data

LEVEL 2 card data provides more information than the standard LEVEL 1 transaction and can be particularly beneficial for commercial, corporate, purchasing, business, or government cards. Transactions processed with LEVEL 2 card data may qualify for lower Visa and Mastercard interchange rates compared to similar transactions submitted without this enhanced data.

LEVEL 3 Card Data

LEVEL 3 card data includes the most detailed level of transaction information. It provides the highest level of transaction detail, allowing merchants to monitor and track specific transaction details for commercial, corporate, purchasing, business, or government cards. Similar to LEVEL 2, transactions with LEVEL 3 card data may qualify for lower Visa and Mastercard interchange rates, offering potential cost savings for merchants.

Error Codes Associated with 'New Charge' Creation

When creating a new charge, you may encounter the following error codes. Each status is associated with a specific error message:

---