Virtual Terminal Settings

Configure virtual terminal behavior for your merchant account.

Overview

Virtual Terminal Settings allow you to customize:

• 📋 Required fields - Control which fields are mandatory
• 🔒 CVV requirements - Enable/disable CVV validation
• 💳 Card brands - Accept specific card types
• 💰 Transaction types - Allowed transaction types
• 💵 Amount limits - Maximum transaction amounts
• 🌍 Currencies - Supported currencies
• 📝 Dynamic descriptors - Custom statement descriptors

Get VT Settings

Endpoint

GET /api/v1/merchants/:merchantId/vt-settings

curl https://dev.auxcore.net/api/v1/merchants/merchant_123/vt-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "requiredFields": ["billingAddress", "cvv", "email"],
    "cvvRequired": true,
    "cardBrandOptions": ["visa", "mastercard", "amex", "discover"],
    "transactionTypes": ["sale", "auth", "capture", "void", "refund"],
    "maxTicketAmount": 10000.00,
    "currencyTypes": ["USD"],
    "dynamicDescriptor": "ACME CORP*"
  }
}

Update VT Settings

Endpoint

PUT /api/v1/merchants/:merchantId/vt-settings

curl -X PUT https://dev.auxcore.net/api/v1/merchants/merchant_123/vt-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "requiredFields": ["billingAddress", "cvv", "email", "phone"],
    "cvvRequired": true,
    "cardBrandOptions": ["visa", "mastercard"],
    "maxTicketAmount": 5000.00
  }'

Response:

{
  "success": true,
  "data": {
    "requiredFields": ["billingAddress", "cvv", "email", "phone"],
    "cvvRequired": true,
    "cardBrandOptions": ["visa", "mastercard"],
    "transactionTypes": ["sale", "auth", "capture", "void", "refund"],
    "maxTicketAmount": 5000.00,
    "currencyTypes": ["USD"],
    "dynamicDescriptor": "ACME CORP*"
  },
  "message": "Virtual terminal settings updated successfully"
}

Configuration Options

Required Fields

Control which fields must be provided for transactions:

Example:

{
  "requiredFields": ["billingAddress", "cvv", "email"]
}

CVV Requirements

⚠️ Security Note: We strongly recommend requiring CVV for fraud prevention.

Card Brand Options

Specify which card brands to accept:

Example:

{
  "cardBrandOptions": ["visa", "mastercard", "amex", "discover"]
}

Transaction Types

Control which transaction types are allowed:

Example:

{
  "transactionTypes": ["sale", "auth", "void", "refund"]
}

Amount Limits

Set maximum transaction amounts:

{
  "maxTicketAmount": 10000.00
}

Transactions exceeding this amount will be declined.

Currency Types

Specify supported currencies:

{
  "currencyTypes": ["USD", "EUR", "GBP"]
}

Dynamic Descriptor

Customize how charges appear on customer statements:

{
  "dynamicDescriptor": "ACME CORP*"
}

Requirements:

• Max 25 characters
• Alphanumeric and spaces only
• Appears on customer's card statement

Use Cases

High-Security Merchant

{
  "requiredFields": ["billingAddress", "cvv", "email", "phone"],
  "cvvRequired": true,
  "cardBrandOptions": ["visa", "mastercard"],
  "maxTicketAmount": 1000.00
}

International Merchant

{
  "requiredFields": ["billingAddress", "email"],
  "cvvRequired": true,
  "cardBrandOptions": ["visa", "mastercard", "amex"],
  "currencyTypes": ["USD", "EUR", "GBP", "CAD"],
  "maxTicketAmount": 50000.00
}

Subscription Service

{
  "requiredFields": ["email"],
  "cvvRequired": true,
  "cardBrandOptions": ["visa", "mastercard"],
  "transactionTypes": ["sale", "refund"],
  "maxTicketAmount": 999.00
}

Validation Rules

When updating settings, the following rules apply:

Required Fields

• Must be an array
• Valid values only
• Cannot be empty

CVV Required

• Must be boolean
• Defaults to true if not specified

Card Brand Options

• Must include at least one brand
• Invalid brands are ignored

Transaction Types

• Must include at least sale
• Cannot restrict all types

Max Ticket Amount

• Must be positive number
• Maximum: 999,999.99

Currency Types

• Must include at least one currency
• Must be valid ISO 4217 codes

Dynamic Descriptor

• Max 25 characters
• Alphanumeric and spaces only
• Cannot contain special characters

Error Handling

Invalid Field

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid required field: invalidField",
    "field": "requiredFields"
  }
}

Invalid Amount

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "maxTicketAmount must be between 0.01 and 999999.99",
    "field": "maxTicketAmount"
  }
}

Invalid Descriptor

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dynamic descriptor must be 25 characters or less",
    "field": "dynamicDescriptor"
  }
}

Best Practices

✅ DO:

• Require CVV for fraud prevention
• Set reasonable limits based on your business
• Test changes in sandbox first
• Document settings for your team
• Review settings quarterly
• Notify customers of accepted payment methods

❌ DON'T:

• Don't disable CVV unless absolutely necessary
• Don't set limits too high - increases fraud risk
• Don't restrict too many fields - reduces conversion
• Don't change frequently - confuses customers
• Don't use unclear descriptors - causes chargebacks

Testing

Test your VT settings in sandbox:

# Get current settings
curl https://dev.auxcore.net/api/v1/merchants/merchant_123/vt-settings

# Update settings
curl -X PUT https://dev.auxcore.net/api/v1/merchants/merchant_123/vt-settings \
  -d '{"maxTicketAmount": 100.00}'

# Test with transaction
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{"amount": 150.00, ...}'
# Should be declined due to amount limit

Next Steps

• Process transactions →
• Configure AVS filters →
• Set up merchant branding →

Need help? Contact support@auxvault.com