Fetch Application Profile

Overview

Retrieve the details of a specific Application Profile by its ID. View fee profile associations, risk profile settings, and metadata tags.

Resource Access

User Permissions: Admin users only
Endpoint: GET /application_profiles/\{application_profile_id}

Arguments

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

Example Request

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

Example Response

{
  "id": "PPqCt5m7AFobHUQsKxqkCEyT",
  "created_at": "2024-11-14T22:25:06.78Z",
  "updated_at": "2024-11-14T22:25:06.78Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "card_present_fee_profile": "CP4Y2GMB34qTtQ0eKSNnR5Qg",
  "fee_profile": "FP3X1FMA23pSsP9dJRMmQ4Pf",
  "risk_profile": "RP3X1FMA23pSsP9dJRMmQ4Pf",
  "tags": {
    "environment": "production",
    "region": "us-west",
    "merchant_type": "retail"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/application_profiles/PPqCt5m7AFobHUQsKxqkCEyT"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "risk_profile": {
      "href": "https://api.ahrvo.network/payments/na/risk_profiles/RP3X1FMA23pSsP9dJRMmQ4Pf"
    },
    "fee_profile": {
      "href": "https://api.ahrvo.network/payments/na/fee_profiles/FP3X1FMA23pSsP9dJRMmQ4Pf"
    },
    "card_present_fee_profile": {
      "href": "https://api.ahrvo.network/payments/na/fee_profiles/CP4Y2GMB34qTtQ0eKSNnR5Qg"
    }
  }
}

Response Fields

Field	Type	Description
id	string	Unique Application Profile identifier (starts with "PP")
created_at	string	ISO 8601 timestamp when profile was created
updated_at	string	ISO 8601 timestamp of last modification
application	string	ID of the associated Application
fee_profile	string	ID of the card-not-present (CNP) fee profile
card_present_fee_profile	string	ID of the card-present (CP) fee profile (optional)
risk_profile	string	ID of the risk profile
tags	object	Key-value metadata pairs
_links	object	HATEOAS links to related resources

Additional Information

Application Profile: Configuration layer
- Links Application to fee and risk settings
- Determines merchant pricing structure
- Controls risk management rules
- Used during merchant onboarding
- Merchants inherit profile settings
Fee Profiles: Pricing configuration
- fee_profile: Card-not-present transactions (CNP)
  - Online payments
  - Mobile payments
  - Phone orders
  - Virtual terminal
- card_present_fee_profile: Card-present transactions (CP)
  - In-person card swipes
  - Chip card reads
  - Contactless payments
  - POS terminal transactions
- Can have different pricing for CNP vs CP
- CP fee profile is optional
- Determines merchant's rate structure
Risk Profile: Risk management
- Transaction limits (daily, monthly)
- Velocity rules (transactions per hour/day)
- Review thresholds
- Fraud detection settings
- Required for all profiles
- Controls automated risk checks
Tags: Custom metadata
- Organize profiles by environment
- Track merchant types
- Regional settings
- Up to 50 key-value pairs
- Max 40 characters for keys
- Max 500 characters for values
Links: Related resources
- Navigate to Application
- Access fee profile details
- View risk profile settings
- HATEOAS for API discovery
Timestamps: Audit trail
- created_at: Never changes
- updated_at: Last modification
- ISO 8601 format
- UTC timezone
- Track configuration changes

Use Cases

Verify Profile Configuration

// Check profile settings before onboarding merchant
async function verifyProfileConfig(profileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  console.log('Profile Configuration:');
  console.log(`ID: ${profile.id}`);
  console.log(`Application: ${profile.application}`);
  console.log(`CNP Fee Profile: ${profile.fee_profile}`);
  console.log(`CP Fee Profile: ${profile.card_present_fee_profile || 'Not configured'}`);
  console.log(`Risk Profile: ${profile.risk_profile}`);
  console.log(`Tags:`, profile.tags);
  
  // Validate required settings
  const issues = [];
  if (!profile.fee_profile) issues.push('Missing CNP fee profile');
  if (!profile.risk_profile) issues.push('Missing risk profile');
  if (!profile.application) issues.push('Missing application');
  
  if (issues.length > 0) {
    console.error('Configuration issues:', issues);
    return false;
  }
  
  console.log('✓ Profile properly configured');
  return true;
}

Get Fee Profile Details

// Follow links to get fee profile information
async function getFeeProfileDetails(profileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  // Fetch CNP fee profile
  const cnpResponse = await fetch(profile._links.fee_profile.href, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password')
    }
  });
  const cnpFeeProfile = await cnpResponse.json();
  
  console.log('Card-Not-Present Pricing:');
  console.log(cnpFeeProfile);
  
  // Fetch CP fee profile if exists
  if (profile.card_present_fee_profile) {
    const cpResponse = await fetch(profile._links.card_present_fee_profile.href, {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    });
    const cpFeeProfile = await cpResponse.json();
    
    console.log('\nCard-Present Pricing:');
    console.log(cpFeeProfile);
  }
  
  return { cnpFeeProfile, cpFeeProfile };
}

Check Profile Updates

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

Compare Profile to Another

// Compare two profiles
async function compareProfiles(profileId1, profileId2) {
  const [profile1, profile2] = await Promise.all([
    fetch(`https://api.ahrvo.network/payments/na/application_profiles/${profileId1}`, {
      headers: { 'Authorization': 'Basic ' + btoa('username:password') }
    }).then(r => r.json()),
    fetch(`https://api.ahrvo.network/payments/na/application_profiles/${profileId2}`, {
      headers: { 'Authorization': 'Basic ' + btoa('username:password') }
    }).then(r => r.json())
  ]);
  
  console.log('Profile Comparison:\n');
  
  console.log(`Profile 1: ${profile1.id}`);
  console.log(`  CNP Fee: ${profile1.fee_profile}`);
  console.log(`  CP Fee: ${profile1.card_present_fee_profile || 'None'}`);
  console.log(`  Risk: ${profile1.risk_profile}`);
  
  console.log(`\nProfile 2: ${profile2.id}`);
  console.log(`  CNP Fee: ${profile2.fee_profile}`);
  console.log(`  CP Fee: ${profile2.card_present_fee_profile || 'None'}`);
  console.log(`  Risk: ${profile2.risk_profile}`);
  
  // Highlight differences
  console.log('\nDifferences:');
  if (profile1.fee_profile !== profile2.fee_profile) {
    console.log('  ⚠ Different CNP fee profiles');
  }
  if (profile1.card_present_fee_profile !== profile2.card_present_fee_profile) {
    console.log('  ⚠ Different CP fee profiles');
  }
  if (profile1.risk_profile !== profile2.risk_profile) {
    console.log('  ⚠ Different risk profiles');
  }
  if (JSON.stringify(profile1.tags) !== JSON.stringify(profile2.tags)) {
    console.log('  ⚠ Different tags');
  }
}

Get Profile for Merchant Onboarding

// Fetch profile to use for new merchant
async function getOnboardingProfile(merchantType, region) {
  // First, find all profiles
  const listResponse = await fetch(
    'https://api.ahrvo.network/payments/na/application_profiles?limit=100',
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const listData = await listResponse.json();
  
  // Find profile matching tags
  const matchingProfile = listData._embedded.application_profiles.find(p => 
    p.tags.merchant_type === merchantType &&
    p.tags.region === region &&
    p.tags.environment === 'production'
  );
  
  if (!matchingProfile) {
    console.error(`No profile found for ${merchantType} in ${region}`);
    return null;
  }
  
  // Fetch full profile details
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${matchingProfile.id}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  console.log(`Using profile: ${profile.id}`);
  console.log(`CNP Fee Profile: ${profile.fee_profile}`);
  console.log(`CP Fee Profile: ${profile.card_present_fee_profile || 'Not configured'}`);
  console.log(`Risk Profile: ${profile.risk_profile}`);
  
  return profile;
}

// Usage
const profile = await getOnboardingProfile('retail', 'us-west');

Export Profile Configuration

// Export profile details for documentation
async function exportProfileConfig(profileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  const config = {
    'Profile ID': profile.id,
    'Application': profile.application,
    'CNP Fee Profile': profile.fee_profile,
    'CP Fee Profile': profile.card_present_fee_profile || 'Not configured',
    'Risk Profile': profile.risk_profile,
    'Created': profile.created_at,
    'Last Updated': profile.updated_at,
    'Tags': JSON.stringify(profile.tags, null, 2)
  };
  
  console.log('Application Profile Configuration:');
  Object.entries(config).forEach(([key, value]) => {
    console.log(`${key}: ${value}`);
  });
  
  return config;
}

Validate Profile Before Update

// Check current state before updating
async function validateBeforeUpdate(profileId, proposedChanges) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const current = await response.json();
  
  console.log('Current Configuration:');
  console.log(`  Fee Profile: ${current.fee_profile}`);
  console.log(`  CP Fee Profile: ${current.card_present_fee_profile || 'None'}`);
  console.log(`  Risk Profile: ${current.risk_profile}`);
  console.log(`  Tags:`, current.tags);
  
  console.log('\nProposed Changes:');
  console.log(JSON.stringify(proposedChanges, null, 2));
  
  // Validate changes
  if (proposedChanges.fee_profile === null) {
    console.warn('⚠ Warning: Removing CNP fee profile');
  }
  
  if (proposedChanges.risk_profile === null) {
    console.error('✗ Error: Cannot remove risk profile (required)');
    return false;
  }
  
  console.log('✓ Changes are valid');
  return true;
}

Best Practices

Check Before Update: Verify current state
- Fetch profile before modifying
- See what will change
- Avoid unintended updates
- Compare old vs new

Cache Profile Data: Reduce API calls

const profileCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

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

Use Links: Navigate related resources
- Follow _links to fee/risk profiles
- HATEOAS pattern
- Discover related resources
- Avoid hardcoding URLs
Monitor Changes: Track modifications
- Check updated_at regularly
- Alert on unexpected changes
- Audit who made changes
- Track configuration drift
Document Purpose: Add tags
- Tag with environment
- Include merchant type
- Add region information
- Note special configurations

Common Workflows

Pre-Onboarding Check

// Verify profile ready for merchant onboarding
async function preOnboardingCheck(profileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  console.log('Pre-Onboarding Profile Check:\n');
  
  const checks = [];
  
  // Required fields
  if (profile.application) {
    checks.push('✓ Application linked');
  } else {
    checks.push('✗ Missing application');
  }
  
  if (profile.fee_profile) {
    checks.push('✓ CNP fee profile configured');
  } else {
    checks.push('⚠ Missing CNP fee profile');
  }
  
  if (profile.risk_profile) {
    checks.push('✓ Risk profile configured');
  } else {
    checks.push('✗ Missing risk profile (required)');
  }
  
  // Optional but recommended
  if (profile.card_present_fee_profile) {
    checks.push('✓ CP fee profile configured');
  } else {
    checks.push('ℹ CP fee profile not configured (optional)');
  }
  
  if (Object.keys(profile.tags).length > 0) {
    checks.push('✓ Tags configured for organization');
  } else {
    checks.push('ℹ No tags set (optional)');
  }
  
  checks.forEach(check => console.log(check));
  
  const hasErrors = checks.some(c => c.startsWith('✗'));
  
  if (hasErrors) {
    console.log('\n✗ Profile not ready for onboarding');
    return false;
  }
  
  console.log('\n✓ Profile ready for merchant onboarding');
  return true;
}

Clone Profile Configuration

// Get config to create similar profile
async function cloneProfileConfig(sourceProfileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${sourceProfileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const source = await response.json();
  
  // Extract configuration (excluding read-only fields)
  const config = {
    fee_profile: source.fee_profile,
    card_present_fee_profile: source.card_present_fee_profile,
    risk_profile: source.risk_profile,
    tags: { ...source.tags }
  };
  
  console.log('Configuration to clone:');
  console.log(JSON.stringify(config, null, 2));
  console.log('\nUse this config to create a new profile with similar settings');
  
  return config;
}

Audit Profile Changes

// Check profile change history
async function auditProfileChanges(profileId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/application_profiles/${profileId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const profile = await response.json();
  
  const created = new Date(profile.created_at);
  const updated = new Date(profile.updated_at);
  
  console.log('Profile Audit:');
  console.log(`ID: ${profile.id}`);
  console.log(`Created: ${profile.created_at}`);
  console.log(`Last Updated: ${profile.updated_at}`);
  
  if (created.getTime() === updated.getTime()) {
    console.log('Status: Never modified since creation');
  } else {
    const daysSinceUpdate = (Date.now() - updated) / (1000 * 60 * 60 * 24);
    console.log(`Status: Modified ${daysSinceUpdate.toFixed(1)} days ago`);
  }
  
  console.log('\nCurrent Configuration:');
  console.log(`  Application: ${profile.application}`);
  console.log(`  CNP Fee: ${profile.fee_profile}`);
  console.log(`  CP Fee: ${profile.card_present_fee_profile || 'None'}`);
  console.log(`  Risk: ${profile.risk_profile}`);
  console.log(`  Tags:`, profile.tags);
}

Security Considerations

API Access: Control carefully
- Only admin users can fetch profiles
- Contains pricing configuration
- Links to fee/risk profiles
- Audit access logs
Profile Configuration: Protect settings
- Fee profiles determine merchant pricing
- Risk profiles control transaction limits
- Changes affect all merchants using profile
- Review changes carefully
Tags: Avoid sensitive data
- Don't store PII in tags
- Use for organization only
- Visible to all admins
- Not encrypted
Audit Trail: Track changes
- Monitor updated_at timestamp
- Alert on unexpected modifications
- Log who fetches profiles
- Investigate suspicious access

Error Responses

Profile Not Found

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

Invalid profile ID
Profile was deleted
Wrong environment/account
Check ID is correct

Unauthorized

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

Invalid API credentials
Check username/password
Verify authentication

Forbidden

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

Not admin user
Insufficient permissions
Contact administrator

Troubleshooting

Profile Not Found

Verify profile ID correct
Check environment (staging vs production)
May have been deleted
Check different Application

Missing Fee Profiles

Fee profiles may not be configured
Check fee_profile field (can be null)
Check card_present_fee_profile (optional)
Update profile to add fee profiles

Can't Access Linked Resources

Verify you have access to fee/risk profiles
Check permissions
May need different credentials
Use _links URLs

Old Data Returned

Clear cache
Check updated_at timestamp
May be using cached response
Fetch again

GET /application_profiles: List all profiles
PUT /application_profiles/{id}: Update profile
GET /applications: List applications
GET /fee_profiles: List fee profiles
GET /risk_profiles: List risk profiles

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Response Fields​

Additional Information​

Use Cases​

Verify Profile Configuration​

Get Fee Profile Details​

Check Profile Updates​

Compare Profile to Another​

Get Profile for Merchant Onboarding​

Export Profile Configuration​

Validate Profile Before Update​

Best Practices​

Common Workflows​

Pre-Onboarding Check​

Clone Profile Configuration​

Audit Profile Changes​

Security Considerations​

Error Responses​

Profile Not Found​

Unauthorized​

Forbidden​

Troubleshooting​

Profile Not Found​

Missing Fee Profiles​

Can't Access Linked Resources​

Old Data Returned​

Related Endpoints​

Overview

Resource Access

Arguments

Example Request

Example Response

Response Fields

Additional Information

Use Cases

Verify Profile Configuration

Get Fee Profile Details

Check Profile Updates

Compare Profile to Another

Get Profile for Merchant Onboarding

Export Profile Configuration

Validate Profile Before Update

Best Practices

Common Workflows

Pre-Onboarding Check

Clone Profile Configuration

Audit Profile Changes

Security Considerations

Error Responses

Profile Not Found

Unauthorized

Forbidden

Troubleshooting

Profile Not Found

Missing Fee Profiles

Can't Access Linked Resources

Old Data Returned

Related Endpoints