Create Application

Overview

Create a new Application to onboard your platform on Ahrvo Network. Applications serve as the top-level resource that contains configuration settings, merchants, and payment processing capabilities.

Resource Access

User Permissions: Platform admin users only
Endpoint: POST /applications

Arguments

Parameter	Type	Required	Description
entity	object	Yes	Business entity information
entity.business_type	string	Yes	Type of business entity (e.g., LIMITED_LIABILITY_COMPANY)
entity.business_name	string	Yes	Legal business name
entity.business_phone	string	Yes	Business phone number
entity.business_address	object	Yes	Business address details
entity.business_tax_id	string	Yes	Business Tax ID (EIN)
entity.first_name	string	Yes	Owner's first name
entity.last_name	string	Yes	Owner's last name
entity.dob	object	Yes	Owner's date of birth (year, month, day)
entity.personal_address	object	Yes	Owner's personal address
entity.phone	string	Yes	Owner's phone number
entity.tax_id	string	Yes	Owner's SSN/Tax ID
entity.email	string	Yes	Contact email address
entity.doing_business_as	string	No	DBA name
entity.default_statement_descriptor	string	No	Default statement descriptor
entity.max_transaction_amount	integer	No	Maximum transaction amount in cents
user	string	Yes	ID of the User creating the Application
account_updater_enabled	boolean	No	Enable automatic card account updater (default: false)
network_token_enabled	boolean	No	Enable network tokenization (default: false)

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/applications' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": {
      "business_type": "LIMITED_LIABILITY_COMPANY",
      "business_name": "ACME Corp",
      "business_phone": "+1 (408) 756-4497",
      "business_address": {
        "line1": "741 Douglass St",
        "line2": "Suite 100",
        "city": "San Mateo",
        "region": "CA",
        "postal_code": "94114",
        "country": "USA"
      },
      "business_tax_id": "123456789",
      "first_name": "John",
      "last_name": "Doe",
      "dob": {
        "year": 1978,
        "month": 5,
        "day": 27
      },
      "personal_address": {
        "line1": "741 Douglass St",
        "line2": "Apartment 7",
        "city": "San Mateo",
        "region": "CA",
        "postal_code": "94114",
        "country": "USA"
      },
      "phone": "4087564497",
      "tax_id": "123456789",
      "email": "john.doe@example.com",
      "doing_business_as": "ACME Services",
      "default_statement_descriptor": "ACME CORP",
      "max_transaction_amount": 1200000
    },
    "user": "US7uYoDEvUPuspdfxUsK96Xx",
    "account_updater_enabled": false,
    "network_token_enabled": false
  }'

Example Response

{
  "id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_at": "2024-11-14T22:25:06.54Z",
  "updated_at": "2024-11-14T22:25:06.54Z",
  "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": {},
  "_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 Application was created
updated_at	string	ISO 8601 timestamp of last modification
name	string	Application name (from business_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
ready_to_settle_upon	string	When transfers are ready to settle
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: Top-level resource
- Contains all merchants
- Platform configuration hub
- One per payment platform
- Manages payment processing settings
- Controls settlement behavior
Entity Information: Business details
- Legal entity information
- Owner/principal details
- Required for underwriting
- Must be accurate
- Used for compliance
Business Types: Supported values
- INDIVIDUAL_SOLE_PROPRIETORSHIP
- CORPORATION
- LIMITED_LIABILITY_COMPANY
- PARTNERSHIP
- ASSOCIATION_ESTATE_TRUST
- TAX_EXEMPT_ORGANIZATION
- INTERNATIONAL_ORGANIZATION
- GOVERNMENT_AGENCY
Account Updater: Automatic card updates
- When true: Cards automatically updated
- Reduces declined transactions
- Card networks notify of changes
- New expiration dates
- New card numbers
- Seamless for customers
Network Tokenization: Enhanced security
- When true: Cards tokenized by networks
- Visa, Mastercard, Discover tokenization
- Better authorization rates
- Enhanced security
- PCI scope reduction
User Requirement: Creator identity
- Must provide User ID
- User becomes Application owner
- User credentials for API access
- Permanent association
201 Created: Success response
- Returns full Application object
- Location header with Application URL
- Application ID for future operations
- Ready to onboard merchants
Default Settings: Initial configuration
- enabled: true
- processing_enabled: true
- settlement_enabled: true
- card_expiration_date_required: true
- All disbursement types enabled
- Can be updated after creation

Use Cases

Basic Application Creation

// Create platform application
async function createApplication(entityInfo, userId) {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/applications',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entity: entityInfo,
        user: userId
      })
    }
  );
  
  if (response.status === 201) {
    const application = await response.json();
    console.log(`✓ Application created: ${application.id}`);
    console.log(`Name: ${application.name}`);
    console.log(`Owner: ${application.owner}`);
    return application;
  } else {
    const error = await response.json();
    console.error('Failed to create application:', error);
    return null;
  }
}

Create with Account Updater

curl -X POST \
  'https://api.ahrvo.network/payments/na/applications' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": {
      "business_type": "LIMITED_LIABILITY_COMPANY",
      "business_name": "ACME Corp",
      "business_phone": "+1 (408) 756-4497",
      "business_address": {
        "line1": "741 Douglass St",
        "city": "San Mateo",
        "region": "CA",
        "postal_code": "94114",
        "country": "USA"
      },
      "business_tax_id": "123456789",
      "first_name": "John",
      "last_name": "Doe",
      "dob": {
        "year": 1978,
        "month": 5,
        "day": 27
      },
      "personal_address": {
        "line1": "741 Douglass St",
        "city": "San Mateo",
        "region": "CA",
        "postal_code": "94114",
        "country": "USA"
      },
      "phone": "4087564497",
      "tax_id": "123456789",
      "email": "john.doe@example.com"
    },
    "user": "US7uYoDEvUPuspdfxUsK96Xx",
    "account_updater_enabled": true
  }'

Enables automatic card updates
Reduces card decline rates
Card networks notify of changes
Seamless for customers

Create with Network Tokenization

curl -X POST \
  'https://api.ahrvo.network/payments/na/applications' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": {
      "business_type": "CORPORATION",
      "business_name": "Tech Solutions Inc",
      "business_phone": "+1 (415) 555-0100",
      "business_address": {
        "line1": "123 Market St",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "USA"
      },
      "business_tax_id": "987654321",
      "first_name": "Jane",
      "last_name": "Smith",
      "dob": {
        "year": 1985,
        "month": 3,
        "day": 15
      },
      "personal_address": {
        "line1": "456 Oak Ave",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94102",
        "country": "USA"
      },
      "phone": "4155550100",
      "tax_id": "987654321",
      "email": "jane.smith@techsolutions.com"
    },
    "user": "US7uYoDEvUPuspdfxUsK96Xx",
    "network_token_enabled": true
  }'

Enhanced security via network tokens
Better authorization rates
PCI scope reduction
Recommended for high-volume platforms

Platform Onboarding Workflow

// Complete platform onboarding
async function onboardPlatform(platformData) {
  console.log('=== Platform Onboarding ===\n');
  
  // Step 1: Create User for API access
  console.log('Step 1: Creating platform user...');
  const userResponse = await fetch(
    'https://api.ahrvo.network/payments/na/users',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        identity: platformData.identityId
      })
    }
  );
  const user = await userResponse.json();
  console.log(`✓ User created: ${user.id}`);
  
  // Step 2: Create Application
  console.log('\nStep 2: Creating application...');
  const appResponse = await fetch(
    'https://api.ahrvo.network/payments/na/applications',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa('username:password'),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entity: platformData.entity,
        user: user.id,
        account_updater_enabled: true,
        network_token_enabled: true
      })
    }
  );
  const application = await appResponse.json();
  console.log(`✓ Application created: ${application.id}`);
  
  // Step 3: Store credentials
  console.log('\nStep 3: Storing API credentials...');
  await storeCredentials({
    applicationId: application.id,
    userId: user.id,
    username: user.username,
    password: user.password // Only available on creation
  });
  console.log('✓ Credentials stored securely');
  
  console.log('\n=== Onboarding Complete ===');
  console.log(`Application ID: ${application.id}`);
  console.log(`Ready to onboard merchants`);
  
  return { application, user };
}

Validate Entity Data

// Validate entity information before creation
function validateEntity(entity) {
  const errors = [];
  
  // Required fields
  if (!entity.business_type) errors.push('Missing business_type');
  if (!entity.business_name) errors.push('Missing business_name');
  if (!entity.business_phone) errors.push('Missing business_phone');
  if (!entity.business_tax_id) errors.push('Missing business_tax_id');
  if (!entity.first_name) errors.push('Missing first_name');
  if (!entity.last_name) errors.push('Missing last_name');
  if (!entity.email) errors.push('Missing email');
  
  // Address validation
  if (!entity.business_address) {
    errors.push('Missing business_address');
  } else {
    if (!entity.business_address.line1) errors.push('Missing business address line1');
    if (!entity.business_address.city) errors.push('Missing business address city');
    if (!entity.business_address.region) errors.push('Missing business address region');
    if (!entity.business_address.postal_code) errors.push('Missing business address postal_code');
    if (!entity.business_address.country) errors.push('Missing business address country');
  }
  
  // DOB validation
  if (!entity.dob || !entity.dob.year || !entity.dob.month || !entity.dob.day) {
    errors.push('Missing or incomplete date of birth');
  }
  
  // Email format
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (entity.email && !emailRegex.test(entity.email)) {
    errors.push('Invalid email format');
  }
  
  if (errors.length > 0) {
    console.error('Validation errors:');
    errors.forEach(error => console.error(`  - ${error}`));
    return false;
  }
  
  console.log('✓ Entity data validated successfully');
  return true;
}

Best Practices

Accurate Information: Critical for compliance
- Verify all business details
- Double-check tax IDs
- Validate owner information
- Confirm contact details
- Accurate data prevents underwriting issues
Enable Advanced Features: Maximize capabilities
```
{
  "account_updater_enabled": true,
  "network_token_enabled": true
}
```
- Account Updater reduces declines
- Network Tokens improve authorization rates
- Both enhance customer experience
- Recommended for production
Store Credentials Securely: User credentials
- User password only shown once
- Store securely immediately
- Never log or expose
- Use environment variables
- Encrypt at rest
One Application Per Platform: Resource model
- Don't create multiple Applications
- One Application contains all merchants
- Use Application Profiles for different pricing
- Contact support for multi-application needs
Test in Staging: Validate before production
- Create test Application in staging
- Verify entity data accepted
- Test merchant onboarding flow
- Validate API integration
- Then create production Application

Document Application ID: Critical identifier

// Store Application ID in config
const config = {
  applicationId: 'APc9vhYcPsRuTSpKD9KpMtPe',
  environment: 'production',
  createdAt: new Date().toISOString()
};

Common Workflows

Complete Setup Flow

// Full platform setup from scratch
async function completePlatformSetup(platformInfo) {
  try {
    // 1. Validate entity data
    console.log('Validating entity data...');
    if (!validateEntity(platformInfo.entity)) {
      throw new Error('Entity validation failed');
    }
    
    // 2. Create Application
    console.log('Creating application...');
    const appResponse = await fetch(
      'https://api.ahrvo.network/payments/na/applications',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa('username:password'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          entity: platformInfo.entity,
          user: platformInfo.userId,
          account_updater_enabled: true,
          network_token_enabled: true
        })
      }
    );
    
    if (!appResponse.ok) {
      throw new Error('Application creation failed');
    }
    
    const application = await appResponse.json();
    console.log(`✓ Application created: ${application.id}`);
    
    // 3. Create Application Profile for fee/risk settings
    console.log('Creating application profile...');
    const profileResponse = await fetch(
      'https://api.ahrvo.network/payments/na/application_profiles',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa('username:password'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          application: application.id,
          fee_profile: platformInfo.feeProfileId,
          risk_profile: platformInfo.riskProfileId
        })
      }
    );
    const profile = await profileResponse.json();
    console.log(`✓ Application profile created: ${profile.id}`);
    
    // 4. Configure webhooks
    console.log('Configuring webhooks...');
    const webhookResponse = await fetch(
      'https://api.ahrvo.network/payments/na/webhooks',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa('username:password'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          url: platformInfo.webhookUrl,
          enabled: true,
          authentication: {
            type: 'BEARER',
            bearer: {
              token: platformInfo.webhookToken
            }
          }
        })
      }
    );
    const webhook = await webhookResponse.json();
    console.log(`✓ Webhook configured: ${webhook.id}`);
    
    console.log('\n=== Platform Setup Complete ===');
    console.log(`Application: ${application.id}`);
    console.log(`Profile: ${profile.id}`);
    console.log(`Webhook: ${webhook.id}`);
    console.log('Ready to onboard merchants!');
    
    return {
      application,
      profile,
      webhook
    };
    
  } catch (error) {
    console.error('Platform setup failed:', error.message);
    throw error;
  }
}

Multi-Environment Setup

// Create applications for different environments
async function setupEnvironments(platformData) {
  const environments = ['staging', 'production'];
  const results = {};
  
  for (const env of environments) {
    console.log(`\nSetting up ${env} environment...`);
    
    const serverUrl = env === 'production'
      ? 'https://api.ahrvo.network/payments/na'
      : 'http://gateway.ahrvo.network/payments/na';
    
    const response = await fetch(`${serverUrl}/applications`, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa(`${env}_user:${env}_pass`),
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entity: platformData.entity,
        user: platformData[`${env}UserId`],
        account_updater_enabled: env === 'production',
        network_token_enabled: env === 'production'
      })
    });
    
    const application = await response.json();
    results[env] = application;
    
    console.log(`✓ ${env} application: ${application.id}`);
  }
  
  return results;
}

Security Considerations

PII Protection: Sensitive data
- SSN/Tax IDs transmitted
- Use HTTPS only
- Don't log request bodies
- Secure credential storage
- Comply with data protection laws
API Credentials: Access control
- User credentials only shown once
- Store securely immediately
- Rotate periodically
- Use separate credentials per environment
- Monitor for unauthorized usage
Entity Verification: KYC/AML compliance
- Accurate business information required
- Owner details verified
- Tax IDs validated
- Address confirmation
- Compliance checks performed
One-Time Creation: Permanent resource
- Applications rarely deleted
- Plan configuration carefully
- Test thoroughly in staging
- Contact support for major changes

Error Responses

Bad Request

{
  "status": 400,
  "message": "Invalid request parameters",
  "details": "business_tax_id is required"
}

Missing required fields
Invalid field formats
Invalid business_type
Check request body

Unauthorized

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

Invalid API credentials
Check username/password
Verify authentication

Unprocessable Entity

{
  "status": 422,
  "message": "Entity validation failed",
  "details": "Invalid tax ID format"
}

Entity data validation failed
Invalid tax ID
Invalid email format
Invalid address
Check entity object

Troubleshooting

Missing Required Fields

Check all required entity fields provided
Verify nested objects complete (dob, addresses)
Ensure user ID is valid
Review example request

Invalid Tax ID

Business tax ID: 9 digits (EIN)
Personal tax ID: 9 digits (SSN)
No dashes or formatting
Numeric only

Invalid Business Type

Use exact enum values
Check supported business types
Case-sensitive
Underscores not spaces

User ID Invalid

User must exist before creating Application
Create User first
Use User ID from creation response
Check correct environment

GET /applications: List all applications
GET /applications/{id}: Fetch application details
PUT /applications/{id}: Update application configuration
POST /users: Create user for application
POST /application_profiles: Create profile for fee/risk settings

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Response Fields​

Additional Information​

Use Cases​

Basic Application Creation​

Create with Account Updater​

Create with Network Tokenization​

Platform Onboarding Workflow​

Validate Entity Data​

Best Practices​

Common Workflows​

Complete Setup Flow​

Multi-Environment Setup​

Security Considerations​

Error Responses​

Bad Request​

Unauthorized​

Unprocessable Entity​

Troubleshooting​

Missing Required Fields​

Invalid Tax ID​

Invalid Business Type​

User ID Invalid​

Related Endpoints​