Visa AR Manager

Error Codes

Visa AR Manager APIs use a comprehensive error reporting system that combines HTTP status codes with detailed business logic error information. The APIs follow a consistent error reporting pattern across all endpoints, providing multiple levels of error information to help you understand and resolve issues quickly.

• Error Response Structure– All API responses include consistent error information:

• HTTP Status Code: Standard HTTP response codes indicating request outcome.

  • Response Body Status: Business logic status information in the response payload.
  • Reason Code: Specific error identifier for detailed error classification.
  • Reason Description: Human-readable explanation of the error condition.

• Error Categories– The API uses two primary error reporting layers:

• Protocol Level: HTTP status codes for transport and authentication issues.

  • Business Logic Level: Application-specific errors returned in response bodies.
  • Validation Level: Request format and data validation errors.
  • Processing Level: Payment and operational errors.

• Error Handling Strategy– Implement comprehensive error handling that addresses:

• HTTP Level Errors: Network, authentication, and protocol-level issues.

  • Business Logic Errors: Application-specific errors returned in response bodies.
  • Transient Errors: Temporary conditions that may resolve with retry.
  • Permanent Errors: Conditions requiring intervention or correction.

• Error Response Processing– When processing API responses:

• Always check the HTTP status code first.

  • Parse the response body for detailed error information.
  • Use reason codes for programmatic error handling.
  • Use reason descriptions for user-friendly error messages.

HTTP Status Codes

Visa AR Manager APIs use standard HTTP status codes to indicate the outcome of API requests at the protocol level. The API uses a limited set of HTTP status codes, focusing on the most relevant codes for payment operations. Each status code provides specific information about the request outcome and guides appropriate response handling.

Success Status Codes

Important: The Visa AR Manager APIs return HTTP 200 for all processed requests, including business logic errors.

For HTTP 200 responses:

• Always parse the response body for detailed status information.
• Check the status field for business operation outcome.
• Use reason_code and reason_desc for error details.
• Do not assume success based solely on HTTP 200 status.

Client Error Status Codes

For client error responses:

• Do not retry without correcting the underlying issue.
• Validate request parameters and authentication credentials.
• Check API documentation for correct request format.
• Log errors for debugging and monitoring.

Server Error Status Codes

For server error responses:

• Implement retry logic with exponential backoff.
• Set maximum retry limits to prevent infinite loops.
• Monitor server error rates for operational insights.
• Consider circuit breaker patterns for resilience.

Business Logic Errors

Business logic errors in the Visa AR Manager APIs are returned within the response body, even when the HTTP status code is 200. These errors provide detailed information about payment outcomes, configuration issues, and operational conditions that require attention.

All business logic errors follow a consistent structure across endpoints, providing status information, reason codes, and descriptive messages to help you understand and resolve issues.

Error Response Structure

Business logic errors are embedded in the response body with the following structure:

Common Status Values

Both onboarding and payment APIs use these response structure and status codes:

Individual Payment Status Values

Each virtual card transaction within a request can have one of these status values:

Payment Errors

Common business logic errors for payment operations:

Status Inquiry Errors

Common business logic errors for status inquiry operations:

Supplier Onboarding Errors

Common business logic errors specific to onboarding operations:

Onboarding validation errors include a details array with field-level information:

• field: Name of the field that failed validation
• reason: Descriptive message explaining the validation failure

Error Handling Best Practices

• Programmatic Handling– Use reason codes for automated error handling:

• Implement switch/case logic based on reason codes.

  • Map reason codes to appropriate business actions.
  • Avoid parsing reason descriptions for logic decisions.
  • Maintain error code mappings for different API versions.

• User Communication– Use reason descriptions for user-facing messages:

• Display reason descriptions to provide context to users.

  • Enhance descriptions with application-specific guidance.
  • Translate descriptions for international applications.
  • Log both codes and descriptions for debugging.

• Retry Logic– Implement appropriate retry strategies:

• Retry transient errors with exponential backoff.

  • Do not retry permanent validation errors.
  • Use different retry strategies for different error categories.
  • Set maximum retry limits to prevent infinite loops.

Common Error Scenarios

These are the frequently encountered error conditions, their typical causes, and recommended resolution approaches. These scenarios are based on common integration patterns and operational experience with the Visa AR Manager APIs.

When encountering errors, always examine both HTTP status codes and response body details to understand the complete error context. Implement comprehensive logging to capture error details for debugging and monitoring purposes.

Payment Failures

Where payment requests fail or payments are declined, preventing successful completion of virtual card transactions. These failures can occur at various stages of the payment workflow and require careful diagnosis.

Common Causes:

• Incomplete or invalid customer information.
• Invalid payment instrument details.
• Payment declined by payment processor.

Resolution Approach:

• Validate all required customer, payment, and invoice data.
• Check payment instrument validity and format.
• Review payment processor decline reasons.

Status Inquiry Problems

Status inquiry requests return no data or unexpected results, preventing proper monitoring of payment transaction status and onboarding provisioning progress. These issues can impact reconciliation and operational visibility.

Common Causes:

• Invalid or non-existent request IDs.
• Timing issues with asynchronous processing.
• Pagination parameters out of range.
• Access restrictions on payment information.
• Incorrect request ID format for onboarding status monitoring (must be integer int64 format).
• Query parameter format issues for relationship information (type enum, email format for supplierId).

Resolution Approach:

• Verify request IDs from payment processing responses.
• Allow sufficient time for asynchronous processing.
• Check pagination parameters and total counts.
• Ensure client has access to requested payment data.
• For onboarding status monitoring, use integer (int64) request_id format returned from supplier onboarding responses.
• For relationship queries, validate type parameter uses enum values (ALL, SUPPLIER, CUSTOMER) and supplierId uses proper email format.

Onboarding Failures

Onboarding requests fail due to validation errors or process issues, preventing successful supplier registration or customer creation. These failures require specific attention to onboarding data requirements and workflow sequencing.

Common Causes:

• Missing required supplier information (company_name, mcc, supp_time_zone, address, business_contact).
• Invalid email format for business contacts or recipient notifications.
• Incorrect country code format (must be 2-letter ISO codes like "US" or "CA").
• Invalid currency code format (must be 3-letter ISO codes like "USD" or "CAD").
• Unsupported language or date format values in recipient information.
• Request ID conflicts or tracking issues across onboarding workflow steps.

Resolution Approach:

• Validate all required fields against API specification requirements.
• Use proper ISO format codes for countries and currencies.
• Verify email addresses follow standard email format validation.
• Check supported language values: en-us, en-uk, fr-fr, fr-ca, de-de, it-it, pt-br, es-us, es-es.
• Ensure proper workflow sequencing (supplier onboarding before customer onboarding).
• Track request IDs consistently across all onboarding steps.

Data Format and Validation Errors

API requests fail due to data format or validation issues, preventing proper processing of request data. The new endpoints enforce specific API constraints for data validation.

Common Causes:

• Invalid JSON format in request bodies.
• Missing required fields or parameters.
• Incorrect data types or formats.
• Invalid currency codes or amount formats.
• Phone number structure errors (must include phone_country_code and phone_number as separate required fields).
• Character length violations ( originator_supp_id: maximum 100 characters, email addresses: maximum 253 characters, payment_id: 1-10 characters).
• Pattern validation failures for ISO codes (country: ^[A-Z]{2}$, currency: ^[A-Z]{3}$).

Resolution Approach:

• Validate JSON format before sending requests.
• Check API documentation for required fields.
• Verify data types match API specifications.
• Use standard formats for currencies and amounts.
• Ensure Address schema includes all five required fields ( country_code, address_line1, zipcode, state, and city).
• Validate array size limits ( payment_details: 1-10 items for deposit confirmation batch operations).
• Apply proper decimal formatting for amounts (minimum 0.01, multiple of 0.01 for AmountDetails).

Troubleshooting

This troubleshooting section provides systematic approaches to diagnosing and resolving common issues with the Visa AR Manager APIs.

Before beginning troubleshooting, ensure you have access to API logs, error messages, and relevant configuration information.

1. Identify the error type and scope to determine the nature of the issue. Document the specific error messages and codes for reference.
   • HTTP Level Errors – Check HTTP status codes (4xx, 5xx).
   • Business Logic Errors – Examine response body status, reason codes, and descriptions.
   • Authentication Problems – Verify credential-related failures.
2. Validate authentication credentials and systematically check all authentication elements. Test authentication with minimal requests to isolate credential issues.
   • Verify client ID values for payment operations.
   • Ensure proper header names and case sensitivity.
3. Examine request format and data validation. Use JSON validation tools to verify request format correctness.
   • Validate JSON format and syntax.
   • Check for required fields and parameters.
   • Verify data types match API specifications.
   • Confirm currency codes and amount formats.
4. Analyze error responses in detail. Cross-reference error codes with API documentation for specific guidance.
   • Record HTTP status codes and their meanings.
   • Parse response body status, reason codes, and descriptions.
   • Identify specific error categories (authentication, validation, processing).
   • Note any additional error context or correlation IDs.
5. Verify proper workflow implementation. Review workflow documentation to confirm proper sequence implementation.
   • Confirm request IDs are properly generated and tracked.
   • Check timing for asynchronous operations and status inquiries.
   • Validate pagination parameters for large result sets.
6. Isolate the problem using simplified test cases. Document successful test cases to establish baseline functionality.
   • Create minimal test requests with required fields only.
   • Test individual endpoints separately.
   • Use development environment for safe testing.
   • Gradually add complexity to identify specific failure points.
7. Review logs and implement enhanced monitoring. Implement additional logging if needed to capture more diagnostic information.
   • Review application logs for error patterns.
   • Check API response times and success rates.
   • Monitor authentication failure rates.
   • Analyze error frequency and timing patterns.
8. Implement appropriate retry and error handling logic. Test error handling logic with various error scenarios.
   • Use exponential backoff for transient errors.
   • Avoid retrying permanent validation errors.
   • Set appropriate timeout values for different operations.
   • Implement circuit breaker patterns for resilience.
9. Document troubleshooting results and next steps. Escalate to Visa support if issues persist after following troubleshooting procedures.
   • Record identified root causes and resolutions.
   • Document configuration changes or fixes applied.
   • Note any unresolved issues requiring escalation.
   • Update integration documentation with lessons learned.

After completing the troubleshooting process, you should have identified the root cause of the issue and implemented appropriate resolution steps. Document the resolution for future reference and to prevent similar issues.

Monitor the resolved issue to ensure the fix is effective and implement preventive measures to avoid similar problems in the future. Update your integration monitoring and alerting based on lessons learned from the troubleshooting process.