Marqeta

Overview

Marqeta provides comprehensive card issuing and processing infrastructure for the Virtual Card Agent. The integration uses Marqeta.js, a PCI-compliant JavaScript library that securely displays sensitive card data through iframes.

Integration Setup

1. Marqeta Account Configuration

Set up your Marqeta account:

1. Contact Marqeta sales team to enable Marqeta.js for your program
2. Complete the application and onboarding process
3. Obtain your API credentials and client access tokens
4. Configure webhook endpoints for transaction monitoring

2. Marqeta.js Setup

Marqeta.js is a PCI-compliant JavaScript library that securely displays card details. The library is automatically loaded based on your environment:

• Sandbox: https://widgets-sandbox.marqeta.com/marqetajs/2.0.0/marqeta.min.js
• Production: https://widgets.marqeta.com/marqetajs/2.0.0/marqeta.min.js

3. Client Access Token

Generate a client access token using the Marqeta API:

1
const clientAccessToken = await marqueta.users.auth.clientaccesstoken({
2
  user_token: userToken,
3
  card_token: cardToken
4
});

API Integration

Card Details Format

When using Marqeta cards with the Virtual Card Agent, use the marqetaJs type:

1
{
2
  "type": "marqetaJs",
3
  "firstName": "John",
4
  "lastName": "Doe",
5
  "postalCode": "12345",
6
  "country": "US",
7
  "cardType": "credit",
8
  "cardToken": "12345678-1234-1234-1234-123456789012",
9
  "clientAccessToken": "your_client_access_token_here",
10
  "sandbox": true,
11
  "achDetails": {
12
    "routingNumber": "123456789",
13
    "accountNumber": "987654321",
14
    "accountName": "John Doe"
15
  }
16
}

Required Parameters

• cardToken: The Marqeta card token for the virtual card
• clientAccessToken: The Marqeta client access token for Marqeta.js authentication
• sandbox: Optional boolean to determine environment (defaults to true based on organization settings)

Environment Detection

The system automatically determines whether to use sandbox or production based on your organization’s sandbox property. This ensures the correct Marqeta.js library URL is used.

Security Features

PCI Compliance

• Marqeta.js handles all sensitive card data display
• Card details are never exposed to your application
• All card information is rendered through secure iframes

Authentication

• Client access tokens provide secure authentication
• Tokens are scoped to specific cards and users
• Automatic token validation and refresh

Data Protection

• Card details are encrypted in transit
• No sensitive data is stored in your application
• All card operations are logged for audit purposes

Implementation Example

Frontend Integration

The Marqeta embedded card page automatically handles:

1. Loading the appropriate Marqeta.js library
2. Initializing with your client access token
3. Displaying card details in secure iframes
4. Error handling and loading states

Backend Processing

The Virtual Card Agent automatically:

1. Extracts card details from the Marqeta iframe
2. Validates card information
3. Processes payments through the payment gateway
4. Handles errors and retries

Best Practices

Security

• Always use client access tokens for authentication
• Implement proper error handling for token failures
• Monitor card usage and spending patterns
• Use sandbox environment for testing

Performance

• Cache client access tokens when possible
• Implement proper loading states
• Handle network failures gracefully
• Monitor Marqeta.js library loading times

Error Handling

• Implement fallback mechanisms for token failures
• Provide clear error messages to users
• Log all Marqeta.js initialization errors
• Monitor card extraction success rates

Troubleshooting

Common Issues

1. Marqeta.js not loading: Check your internet connection and Marqeta.js URL
2. Client access token invalid: Verify token generation and expiration
3. Card details not displaying: Check card token validity and permissions
4. Environment mismatch: Ensure sandbox/production settings match your Marqeta account

Debug Information

The system provides detailed logging for:

• Marqeta.js library loading
• Client access token validation
• Card detail extraction
• Error conditions and resolutions

Support

For Marqeta-specific issues:

• Check the Marqeta.js documentation
• Contact Marqeta support for API-related questions
• Review Mercoa logs for integration-specific issues