List Authorizations

Overview

Retrieve a list of all authorizations with optional filtering and pagination. Use this endpoint to view authorization history, monitor transaction status, and search for specific authorizations.

Resource Access

• User Permissions: Merchant users with authorization permissions
• Endpoint: GET /authorizations

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of items to return (default: 10)
after_cursor	string	No	Return items created after this cursor
before_cursor	string	No	Return items created before this cursor
state	string	No	Filter by state (SUCCEEDED, FAILED, PENDING)
merchant	string	No	Filter by merchant ID
source	string	No	Filter by payment instrument ID

Example Requests

List All Authorizations

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

Filter by State

curl -X GET \
  'https://api.ahrvo.network/payments/na/authorizations?state=SUCCEEDED' \
  -u username:password

Filter by Merchant

curl -X GET \
  'https://api.ahrvo.network/payments/na/authorizations?merchant=MU7noQ1wdgdAeAfymw2rfBMq' \
  -u username:password

Pagination

curl -X GET \
  'https://api.ahrvo.network/payments/na/authorizations?limit=50&after_cursor=AUgspz5X2AwSne5g78qNeYD1' \
  -u username:password

Multiple Filters

curl -X GET \
  'https://api.ahrvo.network/payments/na/authorizations?merchant=MU7noQ1wdgdAeAfymw2rfBMq&state=SUCCEEDED&limit=100' \
  -u username:password

Example Response

{
  "_embedded": {
    "authorizations": [
      {
        "id": "AUgspz5X2AwSne5g78qNeYD1",
        "created_at": "2024-12-04T08:25:21.93Z",
        "updated_at": "2024-12-04T08:25:21.93Z",
        "amount": 100,
        "currency": "USD",
        "state": "SUCCEEDED",
        "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
        "source": "PIkxmtueemLD6dN9ZoWGHT44",
        "expires_at": "2024-12-11T08:25:21.93Z",
        "tags": {},
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/authorizations/AUgspz5X2AwSne5g78qNeYD1"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/authorizations"
    },
    "next": {
      "href": "https://api.ahrvo.network/payments/na/authorizations?after_cursor=AUgspz5X2AwSne5g78qNeYD1"
    }
  },
  "page": {
    "limit": 100,
    "next_cursor": "AUgspz5X2AwSne5g78qNeYD1"
  }
}

Response Fields

Field	Type	Description
_embedded.authorizations	array	Array of authorization objects
_links	object	Navigation links
page	object	Pagination information

Authorization Object Fields

Field	Type	Description
id	string	Unique authorization ID
created_at	string	Timestamp when created
updated_at	string	Timestamp when last updated
amount	integer	Authorized amount in cents
currency	string	Currency code
state	string	State (SUCCEEDED, FAILED, PENDING)
merchant	string	ID of the merchant
source	string	ID of the payment instrument
expires_at	string	Authorization expiration timestamp
tags	object	Metadata tags

Additional Information

• Pagination: Use cursor-based pagination

  • Default limit is 10
  • Maximum limit is typically 100
  • Use next_cursor for next page
  • More efficient than offset pagination

• Filtering: Combine multiple filters

  • Filter by state to see approved/declined
  • Filter by merchant for specific merchant
  • Filter by source for specific card
  • Filters are AND-ed together

• State Values: Authorization lifecycle

  • SUCCEEDED: Authorization approved
  • FAILED: Authorization declined
  • PENDING: Authorization in progress

• Performance: Optimize queries

  • Use filters to reduce result set
  • Request only needed page size
  • Cache results when appropriate

Use Cases

List Recent Authorizations

// Get the most recent authorizations
async function getRecentAuthorizations(limit = 20) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations?limit=${limit}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  console.log(`Found ${data._embedded.authorizations.length} authorizations\n`);
  
  data._embedded.authorizations.forEach(auth => {
    console.log(`${auth.id}:`);
    console.log(`  Amount: $${auth.amount / 100}`);
    console.log(`  State: ${auth.state}`);
    console.log(`  Created: ${auth.created_at}`);
    console.log(`  Expires: ${auth.expires_at}`);
  });
  
  return data._embedded.authorizations;
}

Find Successful Authorizations

// Filter authorizations by state
async function getSuccessfulAuthorizations() {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/authorizations?state=SUCCEEDED&limit=100',
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  console.log(`Found ${data._embedded.authorizations.length} successful authorizations`);
  
  // Calculate total authorized amount
  const total = data._embedded.authorizations.reduce(
    (sum, auth) => sum + auth.amount,
    0
  );
  
  console.log(`Total authorized: $${total / 100}`);
  
  return data._embedded.authorizations;
}

Get Authorizations for Merchant

// Get all authorizations for specific merchant
async function getMerchantAuthorizations(merchantId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations?merchant=${merchantId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  console.log(`Authorizations for merchant ${merchantId}:`);
  console.log(`  Total: ${data._embedded.authorizations.length}`);
  
  // Group by state
  const byState = data._embedded.authorizations.reduce((acc, auth) => {
    acc[auth.state] = (acc[auth.state] || 0) + 1;
    return acc;
  }, {});
  
  console.log('  By state:', byState);
  
  return data._embedded.authorizations;
}

Paginate All Authorizations

// Iterate through all pages of authorizations
async function getAllAuthorizations() {
  const allAuthorizations = [];
  let cursor = null;
  
  do {
    const url = cursor
      ? `https://api.ahrvo.network/payments/na/authorizations?limit=100&after_cursor=${cursor}`
      : 'https://api.ahrvo.network/payments/na/authorizations?limit=100';
    
    const response = await fetch(url, {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    });
    
    const data = await response.json();
    
    allAuthorizations.push(...data._embedded.authorizations);
    
    cursor = data.page.next_cursor;
    
    console.log(`Retrieved ${allAuthorizations.length} authorizations...`);
    
  } while (cursor);
  
  console.log(`✓ Retrieved all ${allAuthorizations.length} authorizations`);
  
  return allAuthorizations;
}

Find Expiring Authorizations

// Find authorizations expiring soon (need capture)
async function findExpiringAuthorizations() {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/authorizations?state=SUCCEEDED&limit=100',
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  const now = new Date();
  const tomorrow = new Date(now.getTime() + 24 * 60 * 60 * 1000);
  
  const expiringSoon = data._embedded.authorizations.filter(auth => {
    const expiresAt = new Date(auth.expires_at);
    return expiresAt <= tomorrow && expiresAt > now;
  });
  
  console.log(`⚠ ${expiringSoon.length} authorizations expiring within 24 hours:`);
  
  expiringSoon.forEach(auth => {
    console.log(`  ${auth.id}: Expires ${auth.expires_at}`);
  });
  
  return expiringSoon;
}

Authorization Analytics

// Generate analytics report from authorizations
async function authorizationAnalytics(merchantId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations?merchant=${merchantId}&limit=1000`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  const authorizations = data._embedded.authorizations;
  
  // Calculate metrics
  const total = authorizations.length;
  const succeeded = authorizations.filter(a => a.state === 'SUCCEEDED').length;
  const failed = authorizations.filter(a => a.state === 'FAILED').length;
  const pending = authorizations.filter(a => a.state === 'PENDING').length;
  
  const successRate = total > 0 ? (succeeded / total * 100).toFixed(2) : 0;
  
  const totalAmount = authorizations
    .filter(a => a.state === 'SUCCEEDED')
    .reduce((sum, a) => sum + a.amount, 0);
  
  const avgAmount = succeeded > 0 ? totalAmount / succeeded : 0;
  
  console.log('=== Authorization Analytics ===\n');
  console.log(`Total Authorizations: ${total}`);
  console.log(`  Succeeded: ${succeeded} (${successRate}%)`);
  console.log(`  Failed: ${failed}`);
  console.log(`  Pending: ${pending}`);
  console.log(`\nTotal Authorized: $${totalAmount / 100}`);
  console.log(`Average Authorization: $${avgAmount / 100}`);
  
  return {
    total,
    succeeded,
    failed,
    pending,
    successRate,
    totalAmount,
    avgAmount
  };
}

Best Practices

• Use Filters: Reduce result set

  // Good - filter for what you need
  const url = '/authorizations?state=SUCCEEDED&merchant=' + merchantId;
  
  // Bad - get everything then filter
  const all = await fetchAll();
  const filtered = all.filter(a => a.state === 'SUCCEEDED');

• Paginate Efficiently: Don't request too much

  • Use reasonable page sizes (50-100)
  • Only fetch pages you need
  • Cache results when possible

• Handle Empty Results: Check array length

  if (data._embedded.authorizations.length === 0) {
    console.log('No authorizations found');
  }

• Monitor Expiration: Find expiring holds

  • Check expires_at regularly
  • Alert when close to expiration
  • Capture or void before expiration

• Track States: Monitor success rates

  • Calculate approval rates
  • Identify decline patterns
  • Alert on unusual activity

Common Workflows

Daily Authorization Report

// Generate daily authorization summary
async function dailyAuthorizationReport(merchantId) {
  const today = new Date();
  today.setHours(0, 0, 0, 0);
  
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations?merchant=${merchantId}&limit=1000`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  // Filter for today
  const todaysAuthorizations = data._embedded.authorizations.filter(auth => {
    const created = new Date(auth.created_at);
    return created >= today;
  });
  
  console.log('=== Daily Authorization Report ===');
  console.log(`Date: ${today.toDateString()}\n`);
  
  const succeeded = todaysAuthorizations.filter(a => a.state === 'SUCCEEDED');
  const failed = todaysAuthorizations.filter(a => a.state === 'FAILED');
  
  console.log(`Total Authorizations: ${todaysAuthorizations.length}`);
  console.log(`  Approved: ${succeeded.length}`);
  console.log(`  Declined: ${failed.length}`);
  console.log(`  Approval Rate: ${((succeeded.length / todaysAuthorizations.length) * 100).toFixed(2)}%`);
  
  const totalAuthorized = succeeded.reduce((sum, a) => sum + a.amount, 0);
  console.log(`\nTotal Authorized: $${totalAuthorized / 100}`);
  
  return {
    date: today,
    total: todaysAuthorizations.length,
    succeeded: succeeded.length,
    failed: failed.length,
    totalAmount: totalAuthorized
  };
}

Find Uncaptured Authorizations

// Find authorizations that haven't been captured
async function findUncapturedAuthorizations() {
  const response = await fetch(
    'https://api.ahrvo.network/payments/na/authorizations?state=SUCCEEDED&limit=100',
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  // Fetch details for each to check transfer field
  const uncaptured = [];
  
  for (const auth of data._embedded.authorizations) {
    const detailResponse = await fetch(
      `https://api.ahrvo.network/payments/na/authorizations/${auth.id}`,
      {
        headers: {
          'Authorization': 'Basic ' + btoa('username:password')
        }
      }
    );
    
    const detail = await detailResponse.json();
    
    if (!detail.transfer && !detail.is_void) {
      uncaptured.push(detail);
    }
  }
  
  console.log(`Found ${uncaptured.length} uncaptured authorizations:`);
  
  uncaptured.forEach(auth => {
    const daysUntilExpiry = Math.ceil(
      (new Date(auth.expires_at) - new Date()) / (1000 * 60 * 60 * 24)
    );
    
    console.log(`  ${auth.id}: $${auth.amount / 100} - expires in ${daysUntilExpiry} days`);
  });
  
  return uncaptured;
}

Export to CSV

// Export authorizations to CSV
async function exportAuthorizationsToCSV(merchantId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations?merchant=${merchantId}&limit=1000`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const data = await response.json();
  
  // Create CSV header
  let csv = 'ID,Created,Amount,Currency,State,Merchant,Source,Expires\n';
  
  // Add rows
  data._embedded.authorizations.forEach(auth => {
    csv += `${auth.id},${auth.created_at},${auth.amount / 100},${auth.currency},${auth.state},${auth.merchant},${auth.source},${auth.expires_at}\n`;
  });
  
  console.log('✓ CSV export ready');
  console.log(`Exported ${data._embedded.authorizations.length} authorizations`);
  
  return csv;
}

Security Considerations

• Access Control: Restrict access

  • Merchants see only their authorizations
  • Platform sees all authorizations
  • Verify permissions

• PII Protection: Sensitive data

  • Payment instrument IDs may be sensitive
  • Don't expose to unauthorized users
  • Log access to authorization data

• Rate Limiting: Prevent abuse

  • Don't poll too frequently
  • Use webhooks for notifications
  • Cache when appropriate

Error Responses

Unauthorized

{
  "status": 401,
  "message": "Unauthorized - Invalid credentials"
}

Forbidden

{
  "status": 403,
  "message": "Forbidden - Insufficient permissions"
}

Troubleshooting

No Results Returned

• Check filter parameters are valid
• Verify merchant ID correct
• Check state enum value
• Try without filters first

Pagination Not Working

• Verify cursor value is valid
• Check cursor hasn't expired
• Use cursor from previous response
• Start from beginning if issues

Missing Authorizations

• Check date range
• Verify merchant filter
• Authorizations may be in different state
• Check if voided or captured

Related Endpoints

• POST /authorizations: Create new authorization
• GET /authorizations/{id}: Fetch authorization details
• PUT /authorizations/{id}: Capture or void authorization