Card Transaction Fields

This section details the fields required to process a card transaction. Each field is described with its type, format, requirements, and any special notes.

Fields

1. Card Source (card_source)

• Type: string
• Description: This field indicates how the card data was captured at the point of sale.
• Required: Yes
• Format: Alphabetic
• Allowed Values:
  • MANUAL
  • PHONE
  • MAIL
  • INTERNET
• Note: PAYARC processes the transaction as 'card not present' if the field value is PHONE, MAIL, or INTERNET. For any other type of transaction, PAYARC processes the transaction as 'card present'.

2. Card Number (card_number)

• Type: integer
• Description: The 14-19 digit card number used for the transaction.
• Required: Yes
• Format: Numeric
• Min Length: 14 digits
• Max Length: 19 digits
• Examples:
  • VISA: 4012000098765439
  • MASTERCARD: 5146315000000055
  • AMEX: 371449635392376
  • DISCOVER: 6011000993026909
  • DISCOVER CUP: 6282000123842342
  • DINERS: 3055155515160018
  • JCB: 3530142019945859

3. Expiration Month (exp_month)

• Type: integer
• Description: The month value displayed on the card used for the transaction.
• Required: Yes
• Format: Numeric
• Min Value: 1
• Max Value: 12
• Example: 01 represents the month of January.

4. Expiration Year (exp_year)

• Type: integer
• Description: The YYYY value mentioned on the card used for the transaction.
• Required: Yes
• Format: Numeric
• Min Length: 2 digits
• Max Length: 4 digits
• Example: 2025

5. 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 can be set as 'Required' or 'Optional' at the account level by a PAYARC Admin. Email [email protected] to contact the Admin.
  • If this field is set as 'Required' and is not sent or is incorrect, the transaction may be declined based on the risk parameters set.
  • If this field is set as 'Optional' and is not sent or is incorrect, the transaction will be processed as CVV availability not provided.

6. Cardholder Name (card_holder_name)

• Type: string
• Description: Name of the cardholder as mentioned on the card used to carry out the transaction.
• Required: Optional
• Format: Alphabetic and Whitespace
• Min Length: 2 characters
• Max Length: 30 characters
• Example: John Smith

7. Address Line 1 (address_line1)

• Type: string
• Description: The cardholder's billing address for line 1.
• Required: Conditional
• Format: Alphanumeric
• Min Length: 1 character
• Max Length: 200 characters
• Example: 103 Mason Street
• Note: This field will be 'Required' if address information is requested by the merchant. Payfac Max Length: 30 characters

8. Address Line 2 (address_line2)

• Type: string
• Description: The cardholder's billing address for line 2.
• Required: Optional
• Format: Alphanumeric
• Min Length: 1 character
• Max Length: 200 characters
• Example: 2nd Floor
• Note: Payfac Max Length: 30 characters

9. City (city)

• Type: string
• Description: The cardholder's city name. Can be a City, District, Suburb, Town, or Village.
• Required: Conditional
• Format: Alphabetic and Whitespace
• Min Length: 1 character
• Max Length: 50 characters
• Example: New York
• Note: This field will be 'Required' if address information is requested by the merchant.

10. State (state)

• Type: string
• Description: The cardholder's state name. Can be State/County/Province/Region.
• Required: Conditional
• Format: Alphabetic and Whitespace
• Min Length: 1 characters
• Max Length: 50 characters
• Example: NY
• Note: This field will be 'Required' if address information is requested by the merchant.

11. ZIP Code (zip)

• Type: integer
• Description: The cardholder's billing ZIP code.
• Required: Conditional
• Format: Numeric
• Min Length: 2 digits
• Max Length: 10 digits
• Example: 10469
• Note: This field will be 'Required' if address information is requested by the merchant.

12. Country (country)

• Type: string
• Description: The cardholder's country name.
• Required: Conditional
• Format: Alphabetic
• Min Length: 1 character
• Max Length: 50 characters
• Example: US
• Note: This field will be 'Required' if address information is requested by the merchant.

13. Authorize Card (authorize_card)

• Type: integer
• Description: This field helps check card validity.
• Required: Optional
• Format: Boolean
• Default: 0
• Note:
  • 0 will not authorize the card while creating a Token.
  • 1 will authorize the customer's card for $0.00, which may result in additional fees. Failure to authorize the card may result in failed subscriptions.

Token Usage Behavior

Overview

When working with tokens in the API, it's important to understand the usage limitations and the specific actions that can be performed with each token.

Behavior Explanation

• Single-Use Token:
  • The token generated by the API is designed for single use only. Once it has been used, it cannot be reused for any other transaction or operation.
• Permitted Actions:
  • Create a New Transaction: The token can be used to initiate a new transaction. This typically involves charging the associated card for the specified amount.
  • Attach a New Card to an Existing Customer: The token can also be used to add a new card to an existing customer's account. This allows the card to be stored and used for future transactions.

Important Considerations

• Token Expiration: Ensure that the token is used promptly, as it may have an expiration time after which it becomes invalid.
• Error Handling: If you attempt to use the token more than once or after it has expired, the API will return an error indicating that the token is no longer valid.
• Security: Since the token is single-use, it enhances security by limiting the exposure of sensitive card data. Ensure that the token is securely transmitted and used only for the intended operation.