Visa Accounts Receivable Manager (Visa AR Manager)

Visa AR Manager provides two main API workflows that work together to support comprehensive payment capabilities.

• Payment Workflow – Transmit virtual card transactions using the /varm/v1/payment endpoint.
• Status Inquiry Workflow – Monitor and retrieve virtual card transaction status using the /varm/v1/paymentinfo endpoint.

Making your first API call helps verify that your authentication is properly configured and that you can successfully communicate with the Visa AR Manager API. Visa recommends that you start with a simple status inquiry call to test your setup.

Before making your first API call, ensure you have completed the authentication setup and have access to the development environment.

1. Select the appropriate endpoint for your first call based on your use case.
   • Payment – Use POST /varm/v1/payment if you need to relay virtual card details to acquirer's designated payment gateway, acquirer, acquirer processor or VisaNet who can process virtual card transactions.
   • Status Inquiry – Use GET /varm/v1/paymentinfo if you have existing request IDs to query.

   For initial testing, the status inquiry endpoint is often easier to test as it requires fewer parameters.

2. Set up the required headers based on your chosen endpoint:
   • For /varm/v1/payment, set the Content-Type: application/json and clientId: [your-client-id].
   • For /varm/v1/paymentinfo, set the clientId: [your-client-id].
3. Build the complete URL using the certification environment base URL:

   VDP Sandbox base URL will be published once it's live.

   For /varm/v1/paymentinfo, include required query parameters:

   • request_id (required)
   • payment_id (optional)
   • pageno (optional, defaults to 1)
4. Prepare your request body (if applicable).

   For POST /varm/v1/payment, prepare a JSON request body with:

   • request_id (unique identifier for the payment request)
   • supplier_id (supplier identification information)
   • payment_details (array of virtual card transaction details)

   For GET /varm/v1/paymentinfo, no request body is needed.

5. Make the HTTP request using your preferred HTTP client or programming language and send your API request.

   Ensure you:

   • Use HTTPS for secure communication.
   • Include all required headers.
   • Set appropriate timeout values.
   • Enable logging for debugging purposes.
6. Examine the API response to verify successful communication.
   • Check the HTTP status code (should be 200 for successful requests).
   • Review the response body for status, reason_code, and reason_desc fields.
   • Validate that the response structure matches the expected schema.

After successfully making your first API call, you will have verified that your authentication is properly configured and that you can communicate with the Visa AR Manager API. The response will provide status information and confirm that your integration is working correctly.

Once you have successfully made your first API call, you can proceed to implement the specific workflows required for your application, such as payment and status inquiry.

Transmit virtual card details to an acquirer's designated payment gateway, acquirer, acquirer processor or VisaNet who can initiate transactions using the Visa AR Manager Payment API endpoint (/varm/v1/payment).

Before doing so, ensure you have valid client credentials configured for authentication.

1. Create a unique request_id for the payment transaction.

   The request ID must be a unique string (1-100 characters) and cannot be reused, even for correcting failed requests. This unique request identifier is essential for:

   • Tracking the payment through its lifecycle
   • Correlating requests across systems
   • Retrieving payment status information
   • Debugging and troubleshooting
2. Structure the supplier_id object with the supplier identification information.

   Include at least one of these identifiers:

   • originator_supp_id (optional; your internal supplier identifier, up to 100 characters)
   • primary_email_address (optional; primary contact email for the supplier, up to 253 characters)
3. Build the customer_info object with the customer information.
   • Customer Identifier – Both originator and system customer IDs
   • Customer Name – Full customer name information
   • Payment Instrument – Payment method details (card)
   • Order Information – Shipping details, amounts, and invoice information
4. Set up the payment method information based on your payment type.

   For card payments (type: "CARD"), include:

   • cardType: "001" (Visa cards only)
   • cardNumber: 16-digit card number
   • securityCode: 3-4 digit CVV/CVC
   • expirationMonth: MM format (01-12)
   • expirationYear: YYYY format
5. Structure comprehensive order and invoice information.
   • Shipping Details – Postal code, country, administrative area (state/province)
   • Amount Details – Total amount and currency
   • Invoice Information – Invoice ID, date, amounts, and additional invoice related details
6. Set up required authentication headers, which include the clientId (your client identifier).
7. Make a POST request to the /varm/v1/payment endpoint and send the payment request.
   • URL – https://[base-url]/varm/v1/payment
   • Method – POST
   • Content-Type – application/json
   • Headers – Client credentials
8. Analyze the response for payment results.
   • Check HTTP status code (200 for successful requests).
   • Review the status field for processing values and outcome.
   • Examine reason_desc for detailed information.
   • Store the request_id for future status inquiries.
9. Handle payment results.
   • Success – Process confirmation and update your systems.
   • Failure – Analyze reason codes and implement appropriate error handling.
   • Pending – Set up status monitoring using the request ID.

After successful completion of the payment workflow, you will receive a response indicating the payment status. The response includes detailed status information and reason codes that help you understand the outcome and take appropriate next steps.

Use the request ID from the payment response to monitor transaction status through the status inquiry workflow. Implement appropriate business logic based on the payment results and maintain audit trails for compliance purposes.

Monitor and retrieve payment transaction status using the Visa AR Manager Status Inquiry API endpoint (/varm/v1/paymentinfo).

Before using the status inquiry workflow, ensure you have valid client credentials and request IDs from previous payment operations.

1. Use the request_id from your payment request.

   This unique identifier is required for retrieving status information and correlating transactions across systems.

2. Configure additional or optional query parameters as needed.
   • payment_id (optional; specific payment transaction identifier, up to 20 characters)
   • pageno (optional; page number for pagination, defaults to "1")

   Use pagination parameters when expecting large result sets to optimize performance.

3. Set up required authentication headers, which include the clientId (your client identifier).
4. Build the complete URL with required and optional parameters.

   https://[base-url]/varm/v1/paymentinfo?request_id=[request-id]&payment_id=[payment-id]&pageno=[page-number]

   Ensure proper URL encoding for all query parameters.

5. Make a GET request to the /varm/v1/paymentinfo endpoint and send the status inquiry request.
   • URL – Complete URL with query parameters
   • Method – GET
   • Headers – Client credentials

   A request body is not required for status inquiry operations.

6. Analyze the response for comprehensive status information.
   • Check HTTP status code (200 for successful requests).
   • Review payment_status for overall request status.
   • Examine payment_statuses array for individual payment details.
   • Check pagination information for large result sets.
7. For large result sets, process pagination information if applicable.
   • Review total_pages (minimum of 1) and total_count (minimum of 0).
   • Implement pagination logic to retrieve additional pages.
   • Use per_page information (1-10 items per page) to understand result set size.
   • Check page field to confirm current page number.
8. Process individual payment status details.
   • payment_id (specific payment transaction identifier, up to 20 characters)
   • payment_status (current status of the payment: COMPLETED, PENDING, or FAILED).
   • reason (additional context for the payment status, up to 255 characters)
9. Implement status-based business logic based on the retrieved status information.
   • Completed Payments – Update your systems and notify relevant parties.
   • Pending Payments – Schedule follow-up status checks.
   • Failed Payments – Implement error handling and notification procedures.

After successful completion of the status inquiry workflow, you will have comprehensive information about payment status, including individual payment details and pagination information for large result sets. This information enables you to make informed decisions about payment handling and system updates.

Use the status information to update your internal systems, trigger business processes, and provide status updates to relevant stakeholders. Implement appropriate retry logic for pending payments and error handling for failed transactions.

Implementing these best practices will help ensure reliable, secure, and efficient integration with the Visa AR Manager APIs.

• Request ID Management – Implement well-structured request ID management practices:
  • Generate unique, traceable request IDs for all payment operations.
  • Ensure request IDs are never reused, even for correcting failed requests.
  • Use consistent ID formats that include timestamps or sequence numbers.
  • Store request IDs with transaction details for audit and troubleshooting.
  • Implement correlation logic to track requests across system boundaries.
• Authentication and Security – Follow security best practices for API authentication:
  • Store credentials securely using environment variables or credential management systems.
  • Implement credential rotation according to your organization's security policies.
  • Monitor authentication failures and implement appropriate alerting.
• Error Handling and Resilience – Implement comprehensive error handling strategies:
  • Parse and handle both HTTP status codes and business logic errors in response bodies.
  • Handle specific response status values.
  • Use reason codes and descriptions to provide meaningful error messages.
  • Implement appropriate retry logic for transient failures.
  • Log detailed error information for debugging and monitoring.
• Performance Optimization – Optimize API usage for better performance:
  • Use pagination parameters for status inquiry operations with large result sets (1-10 items per page).
  • Implement efficient pagination handling with proper page number management (minimum of 1).
  • Implement connection pooling and reuse for HTTP clients.
  • Set appropriate timeout values for different operation types.
  • Cache authentication tokens when possible to reduce overhead.
• Data Handling – Follow best practices for sensitive data handling:
  • Validate all input data before sending API requests.
  • Implement proper data sanitization and encoding.
  • Follow PCI compliance standards for payment card information.
  • Use secure communication channels (HTTPS) for all API interactions.
• Monitoring and Observability – Implement comprehensive monitoring and logging:
  • Log all API requests and responses with appropriate detail levels.
  • Monitor API response times and success rates.
  • Set up alerting for authentication failures and error conditions.
  • Track business metrics such as payment success rates and processing times.
• Testing and Validation – Establish thorough testing practices:
  • Use the development environment for comprehensive integration testing.
  • Test all error scenarios and edge cases.
  • Validate response parsing and error handling logic.
  • Implement automated testing for critical payment workflows.
• Workflow Sequencing – Follow recommended workflow sequences:
  • Use status inquiry workflow to monitor asynchronous payment processing.
  • Implement proper state management for multi-step transmission of virtual card details.
  • Handle workflow dependencies and prerequisites appropriately.
• Documentation and Maintenance – Maintain proper documentation and code practices:
  • Document your integration patterns and configuration details.
  • Keep API client libraries and dependencies up to date.
  • Maintain clear separation between configuration and business logic.
  • Document error handling procedures and escalation paths.