Skip to main content

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​

ParameterTypeRequiredDescription
authorization_idstringYesID 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​

FieldTypeDescription
idstringUnique authorization ID
created_atstringTimestamp when created
updated_atstringTimestamp when last updated
3ds_redirect_urlstring3D Secure redirect URL (if applicable)
additional_buyer_chargesobjectAdditional buyer charges (e.g., surcharges)
amountintegerAuthorized amount in cents
amount_requestedintegerOriginally requested amount in cents
applicationstringID of the application
currencystringCurrency code
expires_atstringAuthorization expiration timestamp
failure_codestringFailure code (if failed)
failure_messagestringFailure message (if failed)
idempotency_idstringIdempotency ID (if provided)
is_voidbooleanWhether authorization has been voided
merchantstringID of the merchant
merchant_identitystringID of the merchant identity
messagesarrayProcessing messages
sourcestringID of the payment instrument
statestringState (SUCCEEDED, FAILED, PENDING)
address_verificationstringAVS result
security_code_verificationstringCVV verification result
tagsobjectMetadata tags
trace_idstringTrace ID for tracking
transferstringID of transfer (if captured)
void_statestringVoid attempt state

Authorization States​

StateDescription
SUCCEEDEDAuthorization approved and funds reserved
FAILEDAuthorization declined or failed
PENDINGAuthorization pending approval

Void States​

StateDescription
UNATTEMPTEDNo void attempt made
PENDINGVoid request in progress
SUCCEEDEDSuccessfully voided
FAILEDVoid 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