Multiple Order Upsell Processing

Overview

This guide explains how to process upsells through the Vrio API using the customer_card_id parameter. This approach allows you to process additional orders using previously stored payment information, creating seamless upsell experiences for customers.

Core Concept: customer_card_id

The customer_card_id is a unique identifier returned in the response from any successfully processed order. This ID represents the stored payment information that can be reused for processing upsells with supported payment methods (Credit Cards, Apple Pay, Google Pay, PayPal, and Payment Tokens).

Key Benefits

Seamless Upselling: Process additional orders without requiring customers to re-enter payment information
Enhanced Security: Eliminates the need to store sensitive payment data on your systems

How customer_card_id Works

1. Initial Order Processing

When an order is successfully processed through the Vrio API, the response includes a customer_card_id within the order object:

{
  "success": true,
  "response_code": 100,
  "transaction_id": 6501056,
  "customer_id": 470177,
  "order_id": 1114897,
  "merchant_id": 6,
  "order": {
    "order_id": 1114897,
    "customer_card_id": 980231,
    "customer_id": 470177
  }
}

2. Payment Information Storage

The Vrio platform automatically handles the secure storage of payment information:

Credit Cards: Card details are tokenized and stored with merchant-specific tokens
Digital Wallets: Wallet tokens are securely stored and associated with the customer and merchant

Processing Upsells with customer_card_id

API Endpoint

Use the standard order processing endpoint with the customer_card_id parameter:

POST https://api.vrio.app/orders

Required Parameters for Upsells

Essential Fields

customer_card_id: The ID from the previous successful order
merchant_id: Critical - Must match the merchant from the original order for most payment methods

Why merchant_id Matters by Payment Method

Credit Cards (payment_method_id = 1):

Recommended: Use the same merchant_id as the original transaction
Reason: Vrio does not store CVV information for security compliance
Risk: Different merchants may trigger CVV verification requirements, potentially causing declines
Alternative: You can pass card_cvv along with the customer_card_id to process with a different merchant using full card data

Digital Wallets & Tokens (PayPal, Apple Pay, Google Pay, Stripe Tokens):

Required: Must use the same merchant_id as the original transaction
Reason: Tokenization occurs at the merchant level, tokens are not transferable between merchants

Complete Upsell Request Example

curl -X POST "https://api.vrio.app/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "connection_id": 1,
    "campaign_id": 18,
    "offers": "[{\"offer_id\":92, \"order_offer_quantity\": 1, \"order_offer_price\": 29.99, \"order_offer_upsell\": true, \"parent_offer_id\": 176, \"parent_order_id\": 1114897}]",
    "customer_card_id": "980231",
    "customer_id": 470177,
    "merchant_id": 6,
    "action": "process",
    "email": "[email protected]",
    "bill_fname": "John",
    "bill_lname": "Doe",
    "bill_phone": "+1234567890",
    "bill_address1": "123 Main St",
    "bill_city": "Anytown",
    "bill_state": "NY",
    "bill_zipcode": "12345",
    "bill_country": "US",
    "ship_fname": "John",
    "ship_lname": "Doe",
    "ship_address1": "123 Main St",
    "ship_city": "Anytown",
    "ship_state": "NY",
    "ship_zipcode": "12345",
    "ship_country": "US"
  }'

Response Handling

Successful Upsell

{
  "success": true,
  "response_code": 100,
  "transaction_id": 6501057,
  "customer_id": 470177,
  "order_id": 1114898,
  "order": {
    "order_id": 1114898,
    "customer_card_id": 980231,
    "customer_id": 470177
  }
}

Failed Upsell

{
  "success": false,
  "response_code": 201,
  "error_message": "Payment method declined",
  "order_id": "67891"
}

Technical Implementation Details

Payment Method Compatibility

The customer_card_id is supported with the following payment methods:

Credit Cards: Tokenized card data
PayPal: PayPal agreement tokens
Apple Pay: Apple Pay tokens
Google Pay: Google Pay tokens
Payment Token: Stripe and other gateway payment tokens

Note: Bank Transfer and other payment methods are not supported for customer_card_id upsell processing.

Card Storage Process

When processing the initial order, Vrio:

Validates Payment Information: Ensures the payment method is valid and authorized
Creates Customer Card Record: Stores payment data securely
Associates with Customer: Links the payment method to the customer record
Returns customer_card_id: Provides the unique identifier for future use

Security Considerations

PCI Compliance

Secure Storage: Vrio is PCI compliant and securely stores payment information
Tokenization: Payment methods are also tokenized at the gateway level for additional security
Encrypted Storage: Sensitive data is encrypted using industry-standard methods

CVV Handling

Never Stored: CVV codes are never stored for security compliance
Merchant Consistency: Using the same merchant reduces CVV-related decline issues
Gateway Dependency: Some gateways may require CVV for cross-merchant transactions
Cross-Merchant Option: You can pass card_cvv along with the customer_card_id to process with a different merchant using full card data

Error Handling and Troubleshooting

Common Issues

Invalid customer_card_id

{
  "success": false,
  "error_message": "Invalid customer card ID"
}

Solution: Verify the customer_card_id exists and belongs to the correct customer.

Merchant Mismatch (Credit Cards)

{
  "success": false, 
  "error_message": "Payment method declined - CVV required"
}

Solution: For credit card payments, use the same merchant_id as the original transaction to avoid CVV verification issues. Alternatively, you can pass card_cvv along with the customer_card_id to process with a different merchant.

Expired Payment Method

{
  "success": false,
  "error_message": "Payment method expired"
}

Solution: Request updated payment information from the customer.

Best Practices

Store Payment Method Type: Save both merchant_id and payment method type from successful transactions
Merchant Strategy:
- Credit Cards: Use the same merchant_id to avoid CVV issues
- Digital Wallets & Tokens: Must use the same merchant_id due to merchant-level tokenization
Validate Before Processing: Check that the customer_card_id is still valid
Handle Declines Gracefully: Provide fallback options for failed upsells
Monitor Success Rates: Track upsell conversion rates by payment method and merchant combination
Test Thoroughly: Verify upsell processing across different payment methods and merchant configurations

This approach enables seamless upsell processing while maintaining the highest levels of security and compliance standards required for payment processing.