Fetch Application

Overview

Retrieve the details of a specific Application by its ID. View configuration settings, enabled features, and links to related resources.

Resource Access

User Permissions: Platform admin users only
Endpoint: GET /applications/\{application_id}

Arguments

Parameter	Type	Required	Description
application_id	string	Yes	The ID of the Application to retrieve

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password

Example Response

{
  "id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_at": "2024-11-14T22:25:06.54Z",
  "updated_at": "2024-11-14T22:26:29.53Z",
  "account_updater_enabled": false,
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "creating_transfer_from_report_enabled": false,
  "disbursements_ach_pull_enabled": true,
  "disbursements_ach_push_enabled": true,
  "disbursements_card_pull_enabled": true,
  "disbursements_card_push_enabled": true,
  "enabled": true,
  "fee_ready_to_settle_upon": "PROCESSOR_WINDOW",
  "instant_payouts_card_push_enabled": false,
  "name": "ACME Corp",
  "network_token_enabled": false,
  "owner": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "processing_enabled": true,
  "ready_to_settle_upon": "PROCESSOR_WINDOW",
  "settlement_enabled": true,
  "settlement_funding_identifier": "UNSET",
  "settlement_queue_mode": "UNSET",
  "tags": {
    "environment": "production",
    "region": "us-west"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "processors": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe/processors"
    },
    "merchants": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe/merchants"
    },
    "application_profile": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe/application_profile"
    }
  }
}

Response Fields

Field	Type	Description
id	string	Unique Application identifier (starts with "AP")
created_at	string	ISO 8601 timestamp when created
updated_at	string	ISO 8601 timestamp of last modification
name	string	Application name
owner	string	ID of the owner Identity
enabled	boolean	Whether Application is enabled
processing_enabled	boolean	Whether payment processing is enabled
settlement_enabled	boolean	Whether settlements are enabled
account_updater_enabled	boolean	Whether automatic card account updater is enabled
network_token_enabled	boolean	Whether network tokenization is enabled
card_cvv_required	boolean	Whether CVV is required for card transactions
card_expiration_date_required	boolean	Whether expiration date is required
instant_payouts_card_push_enabled	boolean	Whether instant payouts via card push are enabled
disbursements_ach_pull_enabled	boolean	Whether ACH pull disbursements are enabled
disbursements_ach_push_enabled	boolean	Whether ACH push disbursements are enabled
disbursements_card_pull_enabled	boolean	Whether card pull disbursements are enabled
disbursements_card_push_enabled	boolean	Whether card push disbursements are enabled
creating_transfer_from_report_enabled	boolean	Whether creating transfers from reports is enabled
ready_to_settle_upon	string	When transfers are ready to settle (PROCESSOR_WINDOW, etc.)
fee_ready_to_settle_upon	string	When fees are ready to settle
settlement_funding_identifier	string	Settlement funding identifier configuration
settlement_queue_mode	string	Settlement queue mode (UNSET, ENABLED, DISABLED)
tags	object	Key-value metadata
_links	object	HATEOAS links to related resources

Additional Information

Application: Platform configuration
- Top-level resource
- Contains all merchants
- Controls payment processing
- Manages settlement behavior
- Usually one per platform
Enabled Status: Application state
- true: Application is active
- false: Application disabled (rare)
- Controls overall access
- Contact support to modify
Processing Enabled: Payment capability
- true: Can process payments
- false: No payment processing
- Usually always enabled
- Critical for operations
Settlement Enabled: Payout capability
- true: Can create settlements
- false: No automated settlements
- Usually always enabled
- Required for merchant payouts
Account Updater: Card updates
- Automatic card information updates
- Reduces declined transactions
- Networks notify of changes
- Seamless customer experience
- Can be enabled/disabled
Network Tokens: Enhanced security
- Card networks tokenize cards
- Better authorization rates
- Enhanced fraud protection
- PCI scope reduction
- Can be enabled/disabled
CVV Requirements: Security settings
- card_cvv_required: Require CVV for cards
- card_expiration_date_required: Require expiration date
- Can be configured per application
- Balance security vs convenience
Disbursement Types: Payout methods
- ACH Pull: Pull from bank accounts
- ACH Push: Push to bank accounts
- Card Pull: Pull from cards
- Card Push: Push to cards
- Usually all enabled
Instant Payouts: Fast disbursements
- Enable card push for instant payouts
- Faster than ACH
- Higher fees
- Real-time merchant payouts
Settlement Timing: When settled
- PROCESSOR_WINDOW: Processor determines timing
- Controls when funds move
- Affects cash flow
- Usually processor-controlled
Links: Related resources
- Processors: Payment processor configs
- Merchants: All merchants under application
- Application Profile: Fee and risk settings
- Navigate between resources

Use Cases

Verify Application Configuration

// Check application settings before onboarding
async function verifyApplicationConfig(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  console.log('Application Configuration:');
  console.log(`Name: ${app.name}`);
  console.log(`ID: ${app.id}`);
  console.log(`Owner: ${app.owner}`);
  console.log('\nStatus:');
  console.log(`  Enabled: ${app.enabled}`);
  console.log(`  Processing: ${app.processing_enabled}`);
  console.log(`  Settlement: ${app.settlement_enabled}`);
  console.log('\nFeatures:');
  console.log(`  Account Updater: ${app.account_updater_enabled}`);
  console.log(`  Network Tokens: ${app.network_token_enabled}`);
  console.log(`  Instant Payouts: ${app.instant_payouts_card_push_enabled}`);
  console.log('\nDisbursement Types:');
  console.log(`  ACH Pull: ${app.disbursements_ach_pull_enabled}`);
  console.log(`  ACH Push: ${app.disbursements_ach_push_enabled}`);
  console.log(`  Card Pull: ${app.disbursements_card_pull_enabled}`);
  console.log(`  Card Push: ${app.disbursements_card_push_enabled}`);
  
  return app;
}

Check Application Health

// Verify application is healthy
async function checkApplicationHealth(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  const issues = [];
  
  if (!app.enabled) issues.push('Application is disabled');
  if (!app.processing_enabled) issues.push('Processing is disabled');
  if (!app.settlement_enabled) issues.push('Settlements are disabled');
  
  if (issues.length > 0) {
    console.error('⚠ Application Issues:');
    issues.forEach(issue => console.error(`  - ${issue}`));
    return false;
  } else {
    console.log('✓ Application is healthy');
    return true;
  }
}

Get Merchants for Application

// Fetch all merchants under application
async function getMerchants(applicationId) {
  const appResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await appResponse.json();
  
  // Follow link to merchants
  const merchantsResponse = await fetch(app._links.merchants.href, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password')
    }
  });
  
  const merchantsData = await merchantsResponse.json();
  const merchants = merchantsData._embedded.merchants;
  
  console.log(`${app.name} has ${merchants.length} merchants`);
  merchants.forEach(m => {
    console.log(`  - ${m.id}: ${m.business_name}`);
  });
  
  return merchants;
}

Check Feature Enablement

// Check if specific features are enabled
async function checkFeatures(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  const features = {
    accountUpdater: app.account_updater_enabled,
    networkTokens: app.network_token_enabled,
    instantPayouts: app.instant_payouts_card_push_enabled,
    cvvRequired: app.card_cvv_required,
    expirationRequired: app.card_expiration_date_required
  };
  
  console.log('Enabled Features:');
  Object.entries(features).forEach(([feature, enabled]) => {
    console.log(`  ${feature}: ${enabled ? '✓' : '✗'}`);
  });
  
  return features;
}

Export Application Details

// Export application configuration
async function exportApplicationConfig(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  const config = {
    'Application ID': app.id,
    'Name': app.name,
    'Owner': app.owner,
    'Enabled': app.enabled,
    'Processing Enabled': app.processing_enabled,
    'Settlement Enabled': app.settlement_enabled,
    'Account Updater': app.account_updater_enabled,
    'Network Tokens': app.network_token_enabled,
    'Instant Payouts': app.instant_payouts_card_push_enabled,
    'CVV Required': app.card_cvv_required,
    'Expiration Required': app.card_expiration_date_required,
    'Created': app.created_at,
    'Updated': app.updated_at,
    'Tags': JSON.stringify(app.tags)
  };
  
  console.log('Application Configuration:');
  Object.entries(config).forEach(([key, value]) => {
    console.log(`${key}: ${value}`);
  });
  
  return config;
}

Monitor Configuration Changes

// Check if application was recently updated
async function checkRecentUpdates(applicationId, hours = 24) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  const updated = new Date(app.updated_at);
  const created = new Date(app.created_at);
  const now = new Date();
  
  const hoursSinceUpdate = (now - updated) / (1000 * 60 * 60);
  
  if (hoursSinceUpdate < hours) {
    console.log(`⚠ Application updated ${hoursSinceUpdate.toFixed(1)} hours ago`);
    console.log(`Last update: ${app.updated_at}`);
    
    if (updated.getTime() === created.getTime()) {
      console.log('(Newly created application)');
    } else {
      console.log('(Configuration was modified)');
    }
    
    return true;
  }
  
  console.log(`No recent updates (last updated ${hoursSinceUpdate.toFixed(1)} hours ago)`);
  return false;
}

Get Application Profile

// Fetch fee and risk profile for application
async function getApplicationProfile(applicationId) {
  const appResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await appResponse.json();
  
  // Follow link to application profile
  const profileResponse = await fetch(app._links.application_profile.href, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password')
    }
  });
  
  const profile = await profileResponse.json();
  
  console.log('Application Profile:');
  console.log(`  Profile ID: ${profile.id}`);
  console.log(`  Fee Profile: ${profile.fee_profile}`);
  console.log(`  CP Fee Profile: ${profile.card_present_fee_profile || 'Not set'}`);
  console.log(`  Risk Profile: ${profile.risk_profile}`);
  
  return profile;
}

Best Practices

Cache Application Data: Reduce API calls

const appCache = new Map();
const CACHE_TTL = 30 * 60 * 1000; // 30 minutes

async function getCachedApplication(applicationId) {
  const cached = appCache.get(applicationId);
  
  if (cached && (Date.now() - cached.timestamp < CACHE_TTL)) {
    console.log('Returning cached application');
    return cached.data;
  }
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  appCache.set(applicationId, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

Use Links: Navigate related resources
- Follow _links to processors, merchants
- HATEOAS for API discovery
- Avoid hardcoding URLs
- More maintainable
Monitor Status: Track changes
- Check updated_at regularly
- Alert on configuration changes
- Track who modifies
- Audit logs

Store Application ID: Configuration

// Store in environment or config
const CONFIG = {
  applicationId: 'APc9vhYcPsRuTSpKD9KpMtPe',
  environment: 'production'
};

Validate Before Use: Ensure ready
- Check enabled: true
- Verify processing_enabled: true
- Confirm settlement_enabled: true
- Check required features enabled

Common Workflows

Pre-Flight Check Before Onboarding

// Verify application ready for merchant onboarding
async function preFlightCheck(applicationId) {
  console.log('=== Pre-Flight Check ===\n');
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  const checks = [];
  
  // Critical checks
  if (app.enabled) {
    checks.push('✓ Application enabled');
  } else {
    checks.push('✗ Application disabled');
  }
  
  if (app.processing_enabled) {
    checks.push('✓ Processing enabled');
  } else {
    checks.push('✗ Processing disabled');
  }
  
  if (app.settlement_enabled) {
    checks.push('✓ Settlement enabled');
  } else {
    checks.push('✗ Settlement disabled');
  }
  
  // Optional checks
  if (app.account_updater_enabled) {
    checks.push('✓ Account Updater enabled (recommended)');
  } else {
    checks.push('ℹ Account Updater disabled (optional)');
  }
  
  if (app.network_token_enabled) {
    checks.push('✓ Network Tokens enabled (recommended)');
  } else {
    checks.push('ℹ Network Tokens disabled (optional)');
  }
  
  checks.forEach(check => console.log(check));
  
  const hasErrors = checks.some(c => c.startsWith('✗'));
  
  if (hasErrors) {
    console.log('\n✗ Application not ready for onboarding');
    return false;
  }
  
  console.log('\n✓ Application ready for merchant onboarding');
  return true;
}

Compare Application Configurations

// Compare two applications (e.g., staging vs production)
async function compareApplications(appId1, appId2) {
  const [app1, app2] = await Promise.all([
    fetch(`https://api.ahrvo.network/payments/na/applications/${appId1}`, {
      headers: { 'Authorization': 'Basic ' + btoa('username:password') }
    }).then(r => r.json()),
    fetch(`https://api.ahrvo.network/payments/na/applications/${appId2}`, {
      headers: { 'Authorization': 'Basic ' + btoa('username:password') }
    }).then(r => r.json())
  ]);
  
  console.log('Application Comparison:\n');
  
  console.log(`App 1: ${app1.name} (${app1.id})`);
  console.log(`App 2: ${app2.name} (${app2.id})`);
  
  console.log('\nDifferences:');
  
  const fields = [
    'enabled',
    'processing_enabled',
    'settlement_enabled',
    'account_updater_enabled',
    'network_token_enabled',
    'instant_payouts_card_push_enabled',
    'card_cvv_required'
  ];
  
  fields.forEach(field => {
    if (app1[field] !== app2[field]) {
      console.log(`  ${field}: ${app1[field]} vs ${app2[field]}`);
    }
  });
  
  if (JSON.stringify(app1.tags) !== JSON.stringify(app2.tags)) {
    console.log(`  tags: Different`);
  }
}

Application Audit

// Comprehensive application audit
async function auditApplication(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const app = await response.json();
  
  console.log('=== Application Audit ===\n');
  
  console.log(`Name: ${app.name}`);
  console.log(`ID: ${app.id}`);
  console.log(`Owner: ${app.owner}`);
  console.log(`Created: ${app.created_at}`);
  console.log(`Updated: ${app.updated_at}`);
  
  const created = new Date(app.created_at);
  const updated = new Date(app.updated_at);
  const age = (Date.now() - created) / (1000 * 60 * 60 * 24);
  
  console.log(`\nAge: ${age.toFixed(1)} days`);
  
  if (created.getTime() !== updated.getTime()) {
    const daysSinceUpdate = (Date.now() - updated) / (1000 * 60 * 60 * 24);
    console.log(`Last modified: ${daysSinceUpdate.toFixed(1)} days ago`);
  } else {
    console.log('Never modified since creation');
  }
  
  console.log('\nConfiguration:');
  console.log(`  Status: ${app.enabled ? 'Enabled' : 'Disabled'}`);
  console.log(`  Processing: ${app.processing_enabled ? 'Enabled' : 'Disabled'}`);
  console.log(`  Settlement: ${app.settlement_enabled ? 'Enabled' : 'Disabled'}`);
  console.log(`  Account Updater: ${app.account_updater_enabled ? 'Yes' : 'No'}`);
  console.log(`  Network Tokens: ${app.network_token_enabled ? 'Yes' : 'No'}`);
  console.log(`  Instant Payouts: ${app.instant_payouts_card_push_enabled ? 'Yes' : 'No'}`);
  
  console.log('\nSecurity:');
  console.log(`  CVV Required: ${app.card_cvv_required ? 'Yes' : 'No'}`);
  console.log(`  Expiration Required: ${app.card_expiration_date_required ? 'Yes' : 'No'}`);
  
  console.log('\nTags:');
  if (Object.keys(app.tags).length > 0) {
    Object.entries(app.tags).forEach(([key, value]) => {
      console.log(`  ${key}: ${value}`);
    });
  } else {
    console.log('  No tags set');
  }
}

Security Considerations

API Access: Control carefully
- Only platform admins can fetch applications
- Contains configuration details
- Audit access logs
- Monitor for unauthorized access
Application ID: Not secret
- Can be stored in configuration
- Used in API calls
- No need to encrypt
- Public in URLs
Owner Information: Identity reference
- Links to business entity
- Contains PII
- Don't expose publicly
- Protect identity data
Configuration Changes: Track modifications
- Monitor updated_at
- Alert on unexpected changes
- Audit who modifies
- Review change logs

Error Responses

Application Not Found

{
  "status": 404,
  "message": "Application not found"
}

Invalid application ID
Application deleted (rare)
Wrong environment
Check ID is correct

Unauthorized

{
  "status": 401,
  "message": "Unauthorized"
}

Invalid API credentials
Check username/password
Verify authentication

Forbidden

{
  "status": 403,
  "message": "Forbidden"
}

Not platform admin
Insufficient permissions
Contact administrator

Troubleshooting

Application Not Found

Verify application ID correct
Check environment (staging vs production)
May have been deleted (rare)
Contact support

Wrong Configuration Shown

Check correct application ID
Verify environment
Clear cache
Check updated_at

Can't Access Linked Resources

Verify permissions
Check correct credentials
May need different API user
Follow _links URLs

POST /applications: Create new application
GET /applications: List all applications
PUT /applications/{id}: Update application configuration
GET /applications/{id}/merchants: List merchants
GET /applications/{id}/processors: List payment processors
GET /application_profiles: Get fee/risk profiles

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Response Fields​

Additional Information​

Use Cases​

Verify Application Configuration​

Check Application Health​

Get Merchants for Application​

Check Feature Enablement​

Export Application Details​

Monitor Configuration Changes​

Get Application Profile​

Best Practices​

Common Workflows​

Pre-Flight Check Before Onboarding​

Compare Application Configurations​

Application Audit​

Security Considerations​

Error Responses​

Application Not Found​

Unauthorized​

Forbidden​

Troubleshooting​

Application Not Found​

Wrong Configuration Shown​

Can't Access Linked Resources​

Related Endpoints​

Overview

Resource Access

Arguments

Example Request

Example Response

Response Fields

Additional Information

Use Cases

Verify Application Configuration

Check Application Health

Get Merchants for Application

Check Feature Enablement

Export Application Details

Monitor Configuration Changes

Get Application Profile

Best Practices

Common Workflows

Pre-Flight Check Before Onboarding

Compare Application Configurations

Application Audit

Security Considerations

Error Responses

Application Not Found

Unauthorized

Forbidden

Troubleshooting

Application Not Found

Wrong Configuration Shown

Can't Access Linked Resources

Related Endpoints