Cardholder Information Fields

This section details the fields that are used to capture the cardholder's information when processing a transaction. Each field is optional but can be crucial for verifying and processing payments correctly.

Fields

1. Expiration Month (`exp_month`)

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

2. Expiration Year (`exp_year`)

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

3. Cardholder Name (`name`)

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

4. Address Line 1 (`address_line1`)

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

5. 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

6. City (`city`)

Type: string
Description: The cardholder's city name. This can be a City, District, Suburb, Town, or Village.
Required: Optional
Format: Alphabetic and Whitespace
Min Length: 2 characters
Max Length: 50 characters
Example: New York

7. State Code (`state_code`)

Type: string
Description: The cardholder's state name. Can be State/County/Province/Region.
Required: Optional
Format: Alphabetic and Whitespace
Min Length: 2 characters
Max Length: 2 characters
Example: NY

8. ZIP Code (`zip`)

Type: integer
Description: The cardholder's billing ZIP code.
Required: Optional
Format: Numeric and Hyphen
Max Length: 10 characters
Example: 10469 or 10469-2345
Note: To group numbers, use a hyphen symbol. No other symbols or characters are allowed.

9. Country Code (`country_code`)

Type: string
Description: The cardholder's country name.
Required: Optional
Format: Alphabetic
Min Length: 2 characters
Max Length: 50 characters
Example: US

Partial Card Update Behavior

Overview

When updating a card's details, it is not necessary to re-enter all the card information. You can selectively update specific fields, such as the expiration date or billing address, without needing to provide the full card details again.

Behavior Explanation

Selective Updates:
- If you need to update only a few fields, such as the expiration date (exp_month and exp_year) or the billing address (address_line1, city, state_code, zip, etc.), you can do so without re-entering the full card number or other existing details.
Preserving Existing Data:
- The fields that are not provided in the update request will remain unchanged, preserving the existing card details.
Example Scenario:
- Current Card Details:
  - Card Number: **** **** **** 1234
  - Expiration Date: 03/2023
  - Billing Address: 103 Mason Street, New York, NY 10469
- Update Request:
  - Only update the expiration date to 03/2025.
- Result:
  - The card number and billing address remain the same, while only the expiration date is updated to 03/2025.

Important Considerations

Security:
- Sensitive card details such as the card number and CVV are not required for simple updates like changing the expiration date or address, reducing the risk of exposure to sensitive data.
API Requests:
- Ensure that only the fields needing updates are included in the API request. This minimizes the data being sent and processed, improving security and efficiency.