Update Application

Overview

Update an existing Application to modify configuration settings and enable/disable features. Configure account updater, network tokenization, settlement queue mode, and security requirements.

Resource Access

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

Arguments

Parameter	Type	Required	Description
application_id	string	Yes	The ID of the Application to update
account_updater_enabled	boolean	No	Enable/disable automatic card account updater
network_token_enabled	boolean	No	Enable/disable network tokenization
settlement_queue_mode	string	No	Settlement queue mode (UNSET, ENABLED, DISABLED)
instant_payouts_card_push_enabled	boolean	No	Enable/disable instant payouts via card push
card_cvv_required	boolean	No	Require CVV for card transactions
card_expiration_date_required	boolean	No	Require expiration date for card transactions
tags	object	No	Key-value metadata (up to 50 pairs)

Example Requests

Enable Account Updater

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "account_updater_enabled": true
  }'

Enable Network Tokenization

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "network_token_enabled": true
  }'

Configure Settlement Queue

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "settlement_queue_mode": "ENABLED"
  }'

Enable Instant Payouts

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "instant_payouts_card_push_enabled": true
  }'

Require CVV

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "card_cvv_required": true
  }'

Update Tags

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "production",
      "region": "us-west",
      "updated_by": "admin"
    }
  }'

Update Multiple Settings

curl -X PUT \
  'https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "account_updater_enabled": true,
    "network_token_enabled": true,
    "instant_payouts_card_push_enabled": true,
    "card_cvv_required": true,
    "tags": {
      "environment": "production",
      "features": "full"
    }
  }'

Example Response

{
  "id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_at": "2024-11-14T22:25:06.54Z",
  "updated_at": "2024-12-10T16:30:00.00Z",
  "account_updater_enabled": true,
  "card_cvv_required": true,
  "card_expiration_date_required": true,
  "enabled": true,
  "instant_payouts_card_push_enabled": true,
  "name": "ACME Corp",
  "network_token_enabled": true,
  "owner": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "processing_enabled": true,
  "settlement_enabled": true,
  "settlement_queue_mode": "ENABLED",
  "tags": {
    "environment": "production",
    "features": "full"
  },
  "_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"
    }
  }
}

Additional Information

Partial Updates: Only send what changes
- Send only fields to update
- Other fields remain unchanged
- More efficient
- Reduces errors
Account Updater: Automatic card updates
- When enabled:
  - Card networks notify of changes
  - Expiration dates updated automatically
  - New card numbers received
  - Reduces declined transactions
  - Seamless for customers
- Recommended: Enable for production
- Cost: May have additional fees
Network Tokenization: Enhanced security
- When enabled:
  - Cards tokenized by networks (Visa, Mastercard, Discover)
  - Better authorization rates
  - Enhanced fraud protection
  - PCI scope reduction
  - Improved customer experience
- Recommended: Enable for production
- Requirements: Processor support needed
Settlement Queue Mode: Queue control
- UNSET: Default behavior (processor controlled)
- ENABLED: Enable settlement queue
- DISABLED: Disable settlement queue
- Controls when settlements are created
- Affects merchant payout timing
Instant Payouts: Fast merchant payouts
- Enable card push for instant payouts
- Faster than ACH (real-time)
- Higher fees than ACH
- Good for gig economy platforms
- Merchant opt-in usually required
CVV Requirements: Security settings
- card_cvv_required: Require CVV for all card transactions
- Increases security
- Reduces fraud
- May impact conversion rates
- Balance security vs convenience
Expiration Date: Usually required
- card_expiration_date_required: Require expiration date
- Standard for card transactions
- Usually always true
- Rarely disabled
Tags Management: Metadata
- Replaces entire tags object (not merged)
- Must send all tags you want to keep
- Omitted tags are removed
- Up to 50 key-value pairs
- Use for organization
Read-Only Fields: Cannot update
- enabled: Contact support to modify
- processing_enabled: Contact support
- settlement_enabled: Contact support
- name: Set from entity on creation
- owner: Permanent association
Updated Timestamp: Changes on update
- updated_at reflects last modification
- created_at never changes
- Track configuration changes
- Audit trail

Use Cases

Enable Advanced Features for Production

// Enable recommended features for production launch
async function enableProductionFeatures(applicationId) {
  console.log('Enabling production features...');
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        account_updater_enabled: true,
        network_token_enabled: true,
        card_cvv_required: true,
        tags: {
          environment: 'production',
          features_enabled: new Date().toISOString()
        }
      })
    }
  );
  
  const updated = await response.json();
  
  console.log('✓ Production features enabled:');
  console.log(`  Account Updater: ${updated.account_updater_enabled}`);
  console.log(`  Network Tokens: ${updated.network_token_enabled}`);
  console.log(`  CVV Required: ${updated.card_cvv_required}`);
  
  return updated;
}

Enable Instant Payouts

// Enable instant payouts for gig economy platform
async function enableInstantPayouts(applicationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        instant_payouts_card_push_enabled: true
      })
    }
  );
  
  const updated = await response.json();
  
  if (updated.instant_payouts_card_push_enabled) {
    console.log('✓ Instant payouts enabled');
    console.log('Merchants can now receive instant payouts to debit cards');
  }
  
  return updated;
}

Update Security Settings

// Increase security by requiring CVV
async function increaseSecurity(applicationId) {
  console.log('Updating security settings...');
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        card_cvv_required: true,
        card_expiration_date_required: true,
        tags: {
          security_updated: new Date().toISOString(),
          cvv_required: 'true'
        }
      })
    }
  );
  
  const updated = await response.json();
  
  console.log('✓ Security settings updated');
  console.log(`  CVV Required: ${updated.card_cvv_required}`);
  console.log(`  Expiration Required: ${updated.card_expiration_date_required}`);
  console.log('Note: May impact conversion rates');
  
  return updated;
}

Add Organization Tags

// Add tags without losing existing ones
async function addTags(applicationId, newTags) {
  // Get current tags
  const currentResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const current = await currentResponse.json();
  
  // Merge with new tags
  const mergedTags = {
    ...current.tags,
    ...newTags
  };
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        tags: mergedTags
      })
    }
  );
  
  const updated = await response.json();
  
  console.log('✓ Tags updated');
  console.log('Current tags:', updated.tags);
  
  return updated;
}

// Usage
await addTags('APc9vhYcPsRuTSpKD9KpMtPe', {
  updated_by: 'admin',
  last_review: '2024-12-10'
});

Configure Settlement Queue

// Enable settlement queue for manual control
async function configureSettlementQueue(applicationId, mode) {
  console.log(`Setting settlement queue mode to ${mode}...`);
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        settlement_queue_mode: mode
      })
    }
  );
  
  const updated = await response.json();
  
  console.log(`✓ Settlement queue mode: ${updated.settlement_queue_mode}`);
  
  if (mode === 'ENABLED') {
    console.log('Settlements will queue for manual approval');
  } else if (mode === 'DISABLED') {
    console.log('Settlements will process automatically');
  }
  
  return updated;
}

Gradual Feature Rollout

// Gradually enable features with testing
async function gradualFeatureRollout(applicationId) {
  console.log('=== Gradual Feature Rollout ===\n');
  
  // Step 1: Enable Account Updater
  console.log('Step 1: Enabling Account Updater...');
  await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        account_updater_enabled: true
      })
    }
  );
  console.log('✓ Account Updater enabled');
  
  // Wait and monitor
  console.log('Monitoring for 24 hours...\n');
  await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate wait
  
  // Step 2: Enable Network Tokens
  console.log('Step 2: Enabling Network Tokens...');
  await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        network_token_enabled: true
      })
    }
  );
  console.log('✓ Network Tokens enabled');
  
  console.log('\nMonitoring for 7 days...\n');
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  // Step 3: Enable Instant Payouts
  console.log('Step 3: Enabling Instant Payouts...');
  const finalResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        instant_payouts_card_push_enabled: true,
        tags: {
          rollout_completed: new Date().toISOString()
        }
      })
    }
  );
  console.log('✓ Instant Payouts enabled');
  
  const final = await finalResponse.json();
  console.log('\n=== Rollout Complete ===');
  console.log('All features enabled successfully');
  
  return final;
}

Best Practices

Fetch Before Update: Verify current state

async function safeUpdate(applicationId, changes) {
  // Get current state
  const current = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  ).then(r => r.json());
  
  console.log('Current state:', current);
  console.log('Proposed changes:', changes);
  
  // Apply update
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(changes)
    }
  );
  
  return response.json();
}

Tags Management: Preserve existing tags

// Good - merge tags
const current = await fetchApplication(applicationId);
await updateApplication(applicationId, {
  tags: {
    ...current.tags,  // Keep existing
    new_tag: 'value'  // Add new
  }
});

// Bad - lose existing tags
await updateApplication(applicationId, {
  tags: {
    new_tag: 'value'  // All other tags lost!
  }
});

Test in Staging: Before production
- Enable features in staging first
- Monitor for issues
- Verify behavior
- Then update production
One Change at a Time: Easier troubleshooting
- Enable one feature
- Monitor impact
- Verify success
- Then enable next feature

Document Changes: Track modifications

async function documentedUpdate(applicationId, changes, reason) {
  const current = await fetchApplication(applicationId);
  
  const updatedTags = {
    ...current.tags,
    last_updated: new Date().toISOString(),
    update_reason: reason
  };
  
  await updateApplication(applicationId, {
    ...changes,
    tags: updatedTags
  });
}

Verify After Update: Confirm changes applied

async function verifyUpdate(applicationId, expectedChanges) {
  const updated = await fetchApplication(applicationId);
  
  Object.entries(expectedChanges).forEach(([key, value]) => {
    if (updated[key] !== value) {
      console.error(`✗ ${key} did not update correctly`);
    } else {
      console.log(`✓ ${key} updated successfully`);
    }
  });
}

Common Workflows

Production Readiness Checklist

// Prepare application for production launch
async function prepareForProduction(applicationId) {
  console.log('=== Production Readiness ===\n');
  
  // Enable recommended features
  console.log('Enabling recommended features...');
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        account_updater_enabled: true,
        network_token_enabled: true,
        card_cvv_required: true,
        card_expiration_date_required: true,
        tags: {
          environment: 'production',
          prepared_for_production: new Date().toISOString(),
          features: 'full'
        }
      })
    }
  );
  
  const updated = await response.json();
  
  console.log('✓ Configuration updated');
  console.log('\nProduction Checklist:');
  console.log(`  ✓ Account Updater: ${updated.account_updater_enabled}`);
  console.log(`  ✓ Network Tokens: ${updated.network_token_enabled}`);
  console.log(`  ✓ CVV Required: ${updated.card_cvv_required}`);
  console.log(`  ✓ Processing: ${updated.processing_enabled}`);
  console.log(`  ✓ Settlement: ${updated.settlement_enabled}`);
  
  console.log('\n✓ Application ready for production');
  
  return updated;
}

Disable Features for Maintenance

// Temporarily adjust settings for maintenance
async function maintenanceMode(applicationId, enable = false) {
  if (!enable) {
    console.log('Entering maintenance mode...');
    // Note: Can't disable processing_enabled via API
    // This would require contacting support
    console.log('⚠ Note: Cannot disable processing via API');
    console.log('Contact support if full maintenance mode needed');
  } else {
    console.log('Exiting maintenance mode...');
    console.log('Verifying all features enabled...');
    
    const response = await fetch(
      `https://api.ahrvo.network/payments/na/applications/${applicationId}`,
      {
        headers: {
          'Authorization': 'Basic ' + btoa('username:password')
        }
      }
    );
    
    const app = await response.json();
    
    if (app.processing_enabled && app.settlement_enabled) {
      console.log('✓ Application operational');
    } else {
      console.log('⚠ Some features still disabled');
    }
  }
}

Feature Comparison and Sync

// Sync features from staging to production
async function syncFeatures(stagingAppId, productionAppId) {
  console.log('Syncing features from staging to production...\n');
  
  // Get staging config
  const stagingResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${stagingAppId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('staging_user:staging_pass')
      }
    }
  );
  const staging = await stagingResponse.json();
  
  console.log('Staging features:');
  console.log(`  Account Updater: ${staging.account_updater_enabled}`);
  console.log(`  Network Tokens: ${staging.network_token_enabled}`);
  console.log(`  Instant Payouts: ${staging.instant_payouts_card_push_enabled}`);
  
  // Apply to production
  console.log('\nApplying to production...');
  const productionResponse = await fetch(
    `https://api.ahrvo.network/payments/na/applications/${productionAppId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic ' + btoa('prod_user:prod_pass'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        account_updater_enabled: staging.account_updater_enabled,
        network_token_enabled: staging.network_token_enabled,
        instant_payouts_card_push_enabled: staging.instant_payouts_card_push_enabled,
        card_cvv_required: staging.card_cvv_required
      })
    }
  );
  
  const production = await productionResponse.json();
  console.log('✓ Production features synced');
  
  return production;
}

Security Considerations

Impact Assessment: Major changes
- Updates affect ALL merchants
- Test thoroughly before applying
- Monitor after changes
- Have rollback plan
CVV Requirements: Security vs convenience
- Requiring CVV increases security
- May reduce conversion rates
- Test impact on sales
- Consider merchant feedback
Feature Enablement: Cost implications
- Account Updater may have fees
- Network Tokens may have fees
- Instant Payouts have higher fees
- Review pricing before enabling
Audit Trail: Track changes
- Use tags to document updates
- Log who made changes
- Monitor updated_at
- Review change history
Permissions: Restrict access
- Only platform admins can update
- Audit who has access
- Monitor update activity
- Review changes regularly

Error Responses

Application Not Found

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

Invalid application ID
Application deleted (rare)
Wrong environment

Bad Request

{
  "status": 400,
  "message": "Invalid request parameters",
  "details": "Invalid settlement_queue_mode value"
}

Invalid parameter value
Invalid settlement_queue_mode
Check request body

Forbidden

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

Not platform admin
Insufficient permissions
Contact administrator

Unprocessable Entity

{
  "status": 422,
  "message": "Update failed",
  "details": "Feature not supported by processor"
}

Feature not available
Processor doesn't support feature
Contact support

Troubleshooting

Update Not Applied

Check response for errors
Verify application ID correct
Fetch application to confirm
Check updated_at timestamp

Tags Disappeared

Tags are replaced, not merged
Must send all tags you want to keep
Fetch current tags first
Merge with new tags before updating

Feature Not Enabling

Check processor supports feature
Verify account eligibility
May require configuration
Contact support

Can't Change Processing/Settlement

These fields are read-only via API
Contact support to modify
Usually always enabled
Rarely need to change

POST /applications: Create new application
GET /applications: List all applications
GET /applications/{id}: Fetch application details
GET /application_profiles: List fee/risk profiles
GET /webhooks: Configure event notifications

Overview​

Resource Access​

Arguments​

Example Requests​

Enable Account Updater​

Enable Network Tokenization​

Configure Settlement Queue​

Enable Instant Payouts​

Require CVV​

Update Tags​

Update Multiple Settings​

Example Response​

Additional Information​

Use Cases​

Enable Advanced Features for Production​

Enable Instant Payouts​

Update Security Settings​

Add Organization Tags​

Configure Settlement Queue​

Gradual Feature Rollout​

Best Practices​

Common Workflows​

Production Readiness Checklist​

Disable Features for Maintenance​

Feature Comparison and Sync​

Security Considerations​

Error Responses​

Application Not Found​

Bad Request​

Forbidden​

Unprocessable Entity​

Troubleshooting​

Update Not Applied​

Tags Disappeared​

Feature Not Enabling​

Can't Change Processing/Settlement​

Related Endpoints​

Overview

Resource Access

Arguments

Example Requests

Enable Account Updater

Enable Network Tokenization

Configure Settlement Queue

Enable Instant Payouts

Require CVV

Update Tags

Update Multiple Settings

Example Response

Additional Information

Use Cases

Enable Advanced Features for Production

Enable Instant Payouts

Update Security Settings

Add Organization Tags

Configure Settlement Queue

Gradual Feature Rollout

Best Practices

Common Workflows

Production Readiness Checklist

Disable Features for Maintenance

Feature Comparison and Sync

Security Considerations

Error Responses

Application Not Found

Bad Request

Forbidden

Unprocessable Entity

Troubleshooting

Update Not Applied

Tags Disappeared

Feature Not Enabling

Can't Change Processing/Settlement

Related Endpoints