Fetch Authorization

Overview

Retrieve the details of a specific authorization. Use this endpoint to check authorization status, view verification results, and determine if the authorization has been captured or voided.

Resource Access

User Permissions: Merchant users with authorization permissions
Endpoint: GET /authorizations/\{authorization_id}

Path Parameters

Parameter	Type	Required	Description
authorization_id	string	Yes	ID of the authorization to retrieve

Example Request

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

Example Response

{
  "id": "AUgspz5X2AwSne5g78qNeYD1",
  "created_at": "2024-12-04T08:25:21.93Z",
  "updated_at": "2024-12-04T08:25:21.93Z",
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "amount": 100,
  "amount_requested": 100,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "expires_at": "2024-12-11T08:25:21.93Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": null,
  "is_void": false,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "messages": [],
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "security_code_verification": "MATCHED",
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "trace_id": "27aad359-b747-4159-9f01-bcaa77245d71",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/authorizations/AUgspz5X2AwSne5g78qNeYD1"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDjvxGeXBLKH1V9YnWm1CS4n"
    }
  }
}

Response Fields

Field	Type	Description
id	string	Unique authorization ID
created_at	string	Timestamp when created
updated_at	string	Timestamp when last updated
3ds_redirect_url	string	3D Secure redirect URL (if applicable)
additional_buyer_charges	object	Additional buyer charges (e.g., surcharges)
amount	integer	Authorized amount in cents
amount_requested	integer	Originally requested amount in cents
application	string	ID of the application
currency	string	Currency code
expires_at	string	Authorization expiration timestamp
failure_code	string	Failure code (if failed)
failure_message	string	Failure message (if failed)
idempotency_id	string	Idempotency ID (if provided)
is_void	boolean	Whether authorization has been voided
merchant	string	ID of the merchant
merchant_identity	string	ID of the merchant identity
messages	array	Processing messages
source	string	ID of the payment instrument
state	string	State (SUCCEEDED, FAILED, PENDING)
address_verification	string	AVS result
security_code_verification	string	CVV verification result
tags	object	Metadata tags
trace_id	string	Trace ID for tracking
transfer	string	ID of transfer (if captured)
void_state	string	Void attempt state

Authorization States

State	Description
SUCCEEDED	Authorization approved and funds reserved
FAILED	Authorization declined or failed
PENDING	Authorization pending approval

Void States

State	Description
UNATTEMPTED	No void attempt made
PENDING	Void request in progress
SUCCEEDED	Successfully voided
FAILED	Void attempt failed

Additional Information

Expiration: Check expires_at
- Authorizations typically expire in 7 days
- Must capture before expiration
- Expired authorizations cannot be captured
- Check before attempting capture
Capture Status: Check transfer field
- null: Not yet captured
- Has value: Authorization has been captured
- Captured authorizations create transfers
- Cannot capture twice
Void Status: Check is_void and void_state
- is_void: false: Not voided
- is_void: true: Successfully voided
- Check void_state for void attempt status
- Voided authorizations cannot be captured
Verification Results: AVS and CVV
- address_verification: Address match result
- security_code_verification: CVV match result
- Use for fraud assessment
- MATCHED values are best
Failure Information: For declined authorizations
- failure_code: Standardized failure code
- failure_message: Human-readable message
- Use to understand decline reason
- Guide customer to resolution
Idempotency: Check for duplicates
- idempotency_id shows if request was idempotent
- Same ID returns same authorization
- Helps prevent duplicate charges

Use Cases

Check Authorization Status

// Verify authorization state before capture
async function checkAuthorizationStatus(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  console.log('Authorization Status:');
  console.log(`  ID: ${authorization.id}`);
  console.log(`  State: ${authorization.state}`);
  console.log(`  Amount: $${authorization.amount / 100}`);
  console.log(`  Expires: ${authorization.expires_at}`);
  
  if (authorization.state === 'SUCCEEDED') {
    if (authorization.transfer) {
      console.log('  ✓ Already captured');
      console.log(`  Transfer ID: ${authorization.transfer}`);
    } else if (authorization.is_void) {
      console.log('  ✓ Voided');
    } else {
      const expiresAt = new Date(authorization.expires_at);
      const now = new Date();
      const daysRemaining = Math.ceil((expiresAt - now) / (1000 * 60 * 60 * 24));
      
      console.log(`  ✓ Ready to capture (${daysRemaining} days remaining)`);
    }
  } else {
    console.log(`  ✗ Authorization ${authorization.state.toLowerCase()}`);
  }
  
  return authorization;
}

Verify Fraud Checks

// Check AVS and CVV verification results
async function verifyFraudChecks(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  console.log('Fraud Verification Results:');
  console.log(`  AVS: ${authorization.address_verification}`);
  console.log(`  CVV: ${authorization.security_code_verification}`);
  
  const avsPass = authorization.address_verification === 'POSTAL_CODE_AND_STREET_MATCH';
  const cvvPass = authorization.security_code_verification === 'MATCHED';
  
  if (avsPass && cvvPass) {
    console.log('  ✓ All fraud checks passed');
    return { passed: true, risk: 'low' };
  } else if (avsPass || cvvPass) {
    console.log('  ⚠ Partial verification');
    return { passed: false, risk: 'medium' };
  } else {
    console.log('  ✗ Fraud checks failed');
    return { passed: false, risk: 'high' };
  }
}

Check Before Capture

// Pre-flight check before capturing authorization
async function preCapturCheck(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  console.log('=== Pre-Capture Checklist ===\n');
  
  const checks = {
    succeeded: authorization.state === 'SUCCEEDED',
    notCaptured: !authorization.transfer,
    notVoided: !authorization.is_void,
    notExpired: new Date(authorization.expires_at) > new Date()
  };
  
  console.log(`✓ State is SUCCEEDED: ${checks.succeeded ? 'Yes' : 'No'}`);
  console.log(`✓ Not yet captured: ${checks.notCaptured ? 'Yes' : 'No'}`);
  console.log(`✓ Not voided: ${checks.notVoided ? 'Yes' : 'No'}`);
  console.log(`✓ Not expired: ${checks.notExpired ? 'Yes' : 'No'}`);
  
  const canCapture = Object.values(checks).every(check => check === true);
  
  if (canCapture) {
    console.log('\n✓ Authorization ready to capture');
  } else {
    console.log('\n✗ Authorization cannot be captured');
  }
  
  return { authorization, canCapture };
}

Get Decline Reason

// Understand why authorization was declined
async function getDeclineReason(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  if (authorization.state !== 'FAILED') {
    console.log('Authorization was not declined');
    return null;
  }
  
  console.log('Authorization Declined:');
  console.log(`  Failure Code: ${authorization.failure_code}`);
  console.log(`  Failure Message: ${authorization.failure_message}`);
  
  // Provide guidance based on failure code
  const guidance = {
    'INSUFFICIENT_FUNDS': 'Customer needs to use different payment method',
    'INVALID_CARD': 'Card number is invalid or card is expired',
    'CARD_DECLINED': 'Issuer declined - customer should contact bank',
    'CVV_MISMATCH': 'CVV verification failed - verify correct CVV',
    'AVS_FAILURE': 'Address verification failed - verify billing address'
  };
  
  if (guidance[authorization.failure_code]) {
    console.log(`  Guidance: ${guidance[authorization.failure_code]}`);
  }
  
  return {
    code: authorization.failure_code,
    message: authorization.failure_message
  };
}

Monitor Authorization Age

// Check how long until authorization expires
async function checkAuthorizationAge(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  const created = new Date(authorization.created_at);
  const expires = new Date(authorization.expires_at);
  const now = new Date();
  
  const ageHours = Math.floor((now - created) / (1000 * 60 * 60));
  const remainingHours = Math.floor((expires - now) / (1000 * 60 * 60));
  
  console.log('Authorization Age:');
  console.log(`  Created: ${authorization.created_at}`);
  console.log(`  Age: ${ageHours} hours`);
  console.log(`  Expires: ${authorization.expires_at}`);
  console.log(`  Time Remaining: ${remainingHours} hours`);
  
  if (remainingHours < 24) {
    console.log('  ⚠ Warning: Expires within 24 hours!');
  }
  
  return {
    ageHours,
    remainingHours,
    expiresSoon: remainingHours < 24
  };
}

// Get transfer details if authorization was captured
async function getRelatedTransfer(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const authorization = await response.json();
  
  if (!authorization.transfer) {
    console.log('Authorization has not been captured yet');
    return null;
  }
  
  console.log('Authorization has been captured:');
  console.log(`  Transfer ID: ${authorization.transfer}`);
  
  // Fetch transfer details
  const transferResponse = await fetch(
    `https://api.ahrvo.network/payments/na/transfers/${authorization.transfer}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const transfer = await transferResponse.json();
  
  console.log(`  Transfer State: ${transfer.state}`);
  console.log(`  Transfer Amount: $${transfer.amount / 100}`);
  
  return transfer;
}

Best Practices

Cache Authorization Details: Reduce API calls

const authCache = new Map();

async function getCachedAuthorization(authorizationId) {
  if (authCache.has(authorizationId)) {
    return authCache.get(authorizationId);
  }
  
  const auth = await fetchAuthorization(authorizationId);
  authCache.set(authorizationId, auth);
  
  return auth;
}

Always Check State: Before operations
- Verify state is SUCCEEDED before capture
- Check not already captured (transfer field)
- Check not voided (is_void field)
- Check not expired (expires_at)
Use Trace ID: For debugging
- Include trace_id in support requests
- Log trace_id for troubleshooting
- Helps track through entire system
Monitor Expiration: Set alerts
- Check expires_at regularly
- Alert when approaching expiration
- Capture or void before expiration
Store Authorization ID: Reference later
- Save to database with order
- Use for capture operations
- Reference in customer service

Common Workflows

Authorization Health Check

// Comprehensive authorization health check
async function authorizationHealthCheck(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const auth = await response.json();
  
  console.log('=== Authorization Health Check ===\n');
  console.log(`ID: ${auth.id}`);
  console.log(`Amount: $${auth.amount / 100} ${auth.currency}`);
  
  // State check
  console.log(`\nState: ${auth.state}`);
  if (auth.state === 'FAILED') {
    console.log(`  Failure: ${auth.failure_code} - ${auth.failure_message}`);
  }
  
  // Capture/Void status
  console.log(`\nCapture Status:`);
  if (auth.transfer) {
    console.log(`  ✓ Captured (Transfer: ${auth.transfer})`);
  } else if (auth.is_void) {
    console.log(`  ✓ Voided`);
  } else {
    console.log(`  Pending capture`);
  }
  
  // Expiration
  const expiresAt = new Date(auth.expires_at);
  const now = new Date();
  const hoursRemaining = Math.floor((expiresAt - now) / (1000 * 60 * 60));
  
  console.log(`\nExpiration:`);
  console.log(`  Expires: ${auth.expires_at}`);
  console.log(`  Time Remaining: ${hoursRemaining} hours`);
  
  if (hoursRemaining < 24) {
    console.log(`  ⚠ WARNING: Expires soon!`);
  }
  
  // Verification
  console.log(`\nVerification:`);
  console.log(`  AVS: ${auth.address_verification}`);
  console.log(`  CVV: ${auth.security_code_verification}`);
  
  // Tags
  if (Object.keys(auth.tags).length > 0) {
    console.log(`\nTags:`, auth.tags);
  }
  
  return auth;
}

Compare Authorization vs Requested

// Compare authorized amount vs requested amount
async function compareAmounts(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const auth = await response.json();
  
  const requested = auth.amount_requested;
  const authorized = auth.amount;
  
  console.log('Amount Comparison:');
  console.log(`  Requested: $${requested / 100}`);
  console.log(`  Authorized: $${authorized / 100}`);
  
  if (authorized !== requested) {
    const difference = authorized - requested;
    console.log(`  ⚠ Difference: $${Math.abs(difference) / 100}`);
    console.log(`  Reason: Partial authorization by issuer`);
  } else {
    console.log(`  ✓ Full amount authorized`);
  }
  
  return { requested, authorized, difference: authorized - requested };
}

Export Authorization Details

// Export complete authorization details
async function exportAuthorizationDetails(authorizationId) {
  const response = await fetch(
    `https://api.ahrvo.network/payments/na/authorizations/${authorizationId}`,
    {
      headers: {
        'Authorization': 'Basic ' + btoa('username:password')
      }
    }
  );
  
  const auth = await response.json();
  
  const report = {
    basic: {
      id: auth.id,
      created: auth.created_at,
      updated: auth.updated_at,
      amount: auth.amount / 100,
      currency: auth.currency,
      state: auth.state
    },
    merchant: {
      merchant_id: auth.merchant,
      merchant_identity: auth.merchant_identity,
      application: auth.application
    },
    payment: {
      source: auth.source,
      avs_result: auth.address_verification,
      cvv_result: auth.security_code_verification
    },
    status: {
      captured: !!auth.transfer,
      transfer_id: auth.transfer,
      voided: auth.is_void,
      void_state: auth.void_state,
      expires_at: auth.expires_at
    },
    metadata: {
      tags: auth.tags,
      trace_id: auth.trace_id,
      idempotency_id: auth.idempotency_id
    }
  };
  
  console.log('✓ Authorization details exported');
  
  return report;
}

Security Considerations

Access Control: Verify permissions
- Merchants can only view their authorizations
- Platform can view all authorizations
- Check authorization ownership
PII Protection: Sensitive data
- Payment instrument IDs are sensitive
- Don't expose to unauthorized users
- Log access appropriately
Trace ID: Use for debugging
- Include in error reports
- Don't expose to end users
- Internal debugging only

Error Responses

Unauthorized

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

Forbidden

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

Not Found

{
  "status": 404,
  "message": "Not Found - Authorization does not exist"
}

Troubleshooting

Authorization Not Found

Verify authorization ID is correct
Check you have access to merchant
Authorization may belong to different merchant
Check environment (staging vs production)

Unexpected State

State may have changed since creation
Check if voided by another process
Check if captured by another process
Fetch again for current state

Missing Verification Results

AVS may not be available for all cards
CVV may not be checked if not provided
International cards may not support AVS
Check messages field for details

POST /authorizations: Create new authorization
GET /authorizations: List all authorizations
PUT /authorizations/{id}: Capture or void authorization
GET /transfers/{id}: Get transfer details if captured

Overview​

Resource Access​

Path Parameters​

Example Request​

Example Response​

Response Fields​

Authorization States​

Void States​

Additional Information​

Use Cases​

Check Authorization Status​

Verify Fraud Checks​

Check Before Capture​

Get Decline Reason​

Monitor Authorization Age​

Get Related Transfer​

Best Practices​

Common Workflows​

Authorization Health Check​

Compare Authorization vs Requested​

Export Authorization Details​

Security Considerations​

Error Responses​

Unauthorized​

Forbidden​

Not Found​

Troubleshooting​

Authorization Not Found​

Unexpected State​

Missing Verification Results​

Related Endpoints​