Skip to main content

Card Issuance API Overview

The Card Issuance API enables you to issue and manage virtual and physical payment cards programmatically. This comprehensive suite of endpoints allows you to create cards, manage budgets, control spending, process transactions, and implement 3D Secure authentication—all through a unified API.

Key Features​

  • Instant Card Issuance: Create virtual cards in real-time with immediate availability
  • Flexible Funding Models: Choose between budget-based or dedicated funds cards
  • Spending Controls: Set transaction limits, merchant restrictions, and velocity controls
  • 3D Secure Support: Implement secure authentication for online transactions
  • Real-Time Monitoring: Track authorizations and clearings as they occur
  • Multi-Currency: Support for international transactions with transparent FX
  • Budget Management: Create and manage multiple budget accounts with flexible top-ups

Authentication​

All Card Issuance API endpoints require dual authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

Obtain your access token and API key from your Ahrvo dashboard or contact your account manager.

API Categories​

The Card Issuance API is organized into four main categories:

1. 3D Secure (3DS)​

Implement secure authentication for card-not-present transactions. 3D Secure adds an additional layer of security by requiring cardholders to verify their identity during online purchases.

Available Endpoints:

Key Use Cases:

  • Secure online payments with cardholder verification
  • Reduce fraud on card-not-present transactions
  • Meet PSD2 Strong Customer Authentication (SCA) requirements
  • Manage cardholder authentication preferences

2. Budget​

Create and manage budget accounts that fund multiple cards. Budget accounts act as central funding sources, allowing you to control spending across card programs.

Available Endpoints:

Key Use Cases:

  • Departmental budget allocation
  • Multi-program card funding
  • Automated budget replenishment
  • Budget consolidation and rebalancing
  • Cost center accounting
  • Spending pool management

Budget Types:

  • Shared Budget: Multiple cards draw from same budget pool
  • Dedicated Budget: Single card with isolated funds
  • Parent-Child Budgets: Hierarchical budget structures

3. Card​

Issue, manage, and control payment cards. This is the core card management functionality including creation, funding, spending controls, and lifecycle management.

Available Endpoints:

Card Creation & Information:

Spending Management:

Card Funding (Dedicated Funds Cards):

Card Lifecycle:

Key Use Cases:

  • Employee expense cards
  • Contractor payment cards
  • Department spending cards
  • Campaign-specific cards
  • Subscription management cards
  • One-time use virtual cards
  • Travel and entertainment cards

Card Types:

  • Virtual Cards: Instant issuance for online/digital payments
  • Physical Cards: Shipped cards for in-person transactions
  • Budget-Based Cards: Funded from shared budget accounts
  • Dedicated Funds Cards: Self-contained card balances

4. Transaction​

Monitor and analyze card transactions in real-time. Track both authorization attempts and final cleared transactions for complete visibility into card activity.

Available Endpoints:

Authorization vs. Clearing:

AspectAuthorizationClearing
TimingImmediate (when card used)1-3 days after authorization
StatusApproved or DeclinedOnly successful transactions
AmountMay include holdsFinal settled amount
PurposeTransaction approvalActual fund movement
Use CaseFraud detection, monitoringReconciliation, accounting

Key Use Cases:

  • Real-time fraud detection
  • Transaction monitoring dashboards
  • Decline rate analysis
  • Financial reconciliation
  • Expense categorization
  • Cross-border fee tracking
  • Settlement timing analysis
  • Authorization-to-clearing matching

Common Workflows​

Workflow 1: Issue a Budget-Based Card​

1. Create Budget Account → 2. Top Up Budget → 3. Create Card → 4. Card Ready to Use

Steps:

  1. Create Budget Account - Set up funding source
  2. Top Up Budget Account - Add initial funds
  3. Create Card - Issue card linked to budget
  4. Control Card Spending - Set spending limits (optional)

Workflow 2: Issue a Dedicated Funds Card​

1. Create Card → 2. Top Up Card → 3. Card Ready to Use

Steps:

  1. Create Card - Issue dedicated funds card
  2. Top Up Dedicated Funds Card - Add funds directly to card
  3. Control Card Spending - Set spending limits (optional)

Workflow 3: Enable 3D Secure on a Card​

1. Create 3DS Contact → 2. Enroll Card → 3. Secure Payments Enabled

Steps:

  1. Create Cardholder 3DS Contact - Register cardholder details
  2. Enroll Card in 3DS - Enable 3DS authentication
  3. Query 3DS Enrollment Details - Verify enrollment

Workflow 4: Monitor and Reconcile Transactions​

1. Query Authorizations → 2. Analyze Patterns → 3. Query Clearings → 4. Reconcile

Steps:

  1. Query Authorization Logs - Monitor real-time activity
  2. Analyze decline rates and fraud patterns
  3. Query Clearing Logs - Get settled transactions
  4. Match authorizations to clearings for reconciliation

Workflow 5: Manage Card Lifecycle​

1. Issue Card → 2. Monitor Usage → 3. Adjust Controls → 4. Withdraw/Close

Steps:

  1. Create Card - Issue new card
  2. Query Card Details - Monitor card status
  3. Control Card Spending - Adjust limits as needed
  4. Withdraw Funds - Recover unused funds (if dedicated)

Card States and Lifecycle​

Card States​

StateDescriptionCan Transact?Actions Available
ActiveCard is operational✅ YesFreeze, update controls, transact
FrozenTemporarily suspended❌ NoUnfreeze, update details
ExpiredPast expiration date❌ NoReplace card
ClosedPermanently deactivated❌ NoNone (create new card)

State Transitions​

Created → Active → Frozen → Active
                 ↓
              Expired
                 ↓
              Closed

Rate Limits​

To ensure system stability and fair usage, the following rate limits apply:

Endpoint TypeRate Limit
Card Creation100 requests/minute
Card Queries1000 requests/minute
Budget Operations500 requests/minute
Transaction Queries1000 requests/minute
3DS Operations200 requests/minute

Exceeding rate limits will result in HTTP 429 (Too Many Requests) responses.

Error Handling​

All API endpoints return standardized error responses:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}

Common Error Codes​

CodeDescriptionResolution
INSUFFICIENT_BALANCEBudget or card lacks fundsTop up budget/card
INVALID_CARD_STATECard not in valid stateCheck card status, unfreeze if needed
LIMIT_EXCEEDEDTransaction exceeds spending limitIncrease limits or reduce amount
CARD_NOT_FOUNDCard ID doesn't existVerify card ID
BUDGET_NOT_FOUNDBudget ID doesn't existVerify budget ID
UNAUTHORIZEDInvalid credentialsCheck authentication tokens
DUPLICATE_REQUESTDuplicate idempotency keyUse unique key or check existing transaction

Best Practices​

Security​

  1. Secure Credentials: Store API keys and tokens securely using environment variables or secret management systems
  2. Enable 3D Secure: Implement 3DS for online transactions to reduce fraud
  3. Monitor Transactions: Set up real-time monitoring for suspicious activity
  4. Implement Limits: Use spending controls to minimize risk exposure
  5. Regular Audits: Review card activity and authorization logs regularly

Performance​

  1. Use Pagination: For large result sets, implement proper pagination
  2. Filter Queries: Use date ranges and filters to limit response sizes
  3. Batch Operations: Group similar operations when possible
  4. Cache Responses: Cache card details and product information
  5. Implement Retry Logic: Handle transient errors with exponential backoff

Financial Management​

  1. Budget Planning: Create separate budgets for different departments/programs
  2. Regular Reconciliation: Match authorizations to clearings daily
  3. Monitor Balances: Set up alerts for low budget balances
  4. Track Fees: Monitor cross-border and transaction fees
  5. Expense Categorization: Use MCC codes for automatic expense classification

Operational​

  1. Idempotency: Use unique idempotency keys for all operations
  2. Error Handling: Implement comprehensive error handling and logging
  3. Webhook Integration: Set up webhooks for real-time transaction notifications (if available)
  4. Documentation: Maintain internal documentation of card programs
  5. Testing: Test in staging environment before production deployment

Support and Resources​

Getting Help​

Additional Resources​

API Versioning​

The Card Issuance API uses URI versioning. The current version is v2:

/api/issuing/{category}/v2/{endpoint}

Breaking changes will result in a new version. Non-breaking changes will be added to the current version with backwards compatibility.

Quick Start​

1. Set Up Authentication​

export AHRVO_API_KEY="your-api-key"
export AHRVO_ACCESS_TOKEN="your-access-token"

2. Create Your First Card​

# Create a budget account
curl -X POST "https://api.ahrvo.network/card/issuance/api/issuing/budget/v2/account" \
  -H "Authorization: Bearer $AHRVO_ACCESS_TOKEN" \
  -H "x-api-key: $AHRVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "My First Budget",
    "currency": "USD"
  }'

# Top up the budget
curl -X POST "https://api.ahrvo.network/card/issuance/api/issuing/budget/v2/top-up" \
  -H "Authorization: Bearer $AHRVO_ACCESS_TOKEN" \
  -H "x-api-key: $AHRVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "budget_id": "budget_id_from_above",
    "amount": "1000.00",
    "currency": "USD"
  }'

# Create a card
curl -X POST "https://api.ahrvo.network/card/issuance/api/issuing/card/v2/apply" \
  -H "Authorization: Bearer $AHRVO_ACCESS_TOKEN" \
  -H "x-api-key: $AHRVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "budget_id": "budget_id_from_above",
    "card_type": "virtual",
    "cardholder_name": "John Doe"
  }'

3. Monitor Transactions​

# Query authorization logs
curl -X GET "https://api.ahrvo.network/card/issuance/api/issuing/transaction/v2/authorizations?card_id=your_card_id" \
  -H "Authorization: Bearer $AHRVO_ACCESS_TOKEN" \
  -H "x-api-key: $AHRVO_API_KEY"

Summary​

The Card Issuance API provides everything you need to build sophisticated card programs:

  • 26 Endpoints across 4 categories
  • 6 3DS Endpoints for secure authentication
  • 6 Budget Endpoints for funding management
  • 12 Card Endpoints for card lifecycle management
  • 2 Transaction Endpoints for monitoring and reconciliation

Each endpoint includes comprehensive documentation with multiple use cases, code examples in multiple languages, and best practices for implementation.

Ready to get started? Begin with Create Budget Account or Create Card!