Visa AR Manager

Visa AR Manager provides comprehensive API workflows that support both onboarding processes and payment capabilities, working together to deliver complete virtual card payment solutions.

If you are onboarding suppliers yourself, follow this sequential process to implement a complete Visa AR Manager integration:

1. Supplier Profile API – Register new suppliers with complete business profile information including company details, addresses, and business contacts using the /varm/v1/onboarding/supplier endpoint.

2. Supplier Onboarding Status API – Track the progress of supplier setup through various provisioning stages including registration, consent, configuration, and customer creation using the /varm/v1/onboardingstatus endpoint.

3. Supplier Participation Agreement API – Submit supplier's consent to the participation agreement terms using the /varm/v1/participationagreement endpoint.

4. Supplier Customer Onboarding API – Onboard customer relationships for onboarded suppliers using the /varm/v1/onboarding/customer endpoint.

5. Supplier Relationship Details API – Query and manage established supplier-customer relationships for ongoing operational needs using the /varm/v1/relationshipinfo endpoint.

6. Payment Request API – Transmit virtual card transactions using the /varm/v1/payment endpoint. This API can also be used to initiate a penny test to validate account details during supplier onboarding.

7. Supplier Deposit Confirmation API – Validate account details during supplier onboarding by providing confirmation of penny test using the /varm/v1/deposit endpoint.

8. Retrieve Payment Status API – 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. Choose your starting point based on whether you need onboarding or payment capabilities.

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 integration workflow.

   Onboarding APIs (typically called first to establish supplier and customer relationships):

   • Supplier Profile – Use POST /varm/v1/onboarding/supplier to register new suppliers with business profile information.
   • Supplier Onboarding Status – Use GET /varm/v1/onboardingstatus to track supplier provisioning progress if you have a request ID.
   • Supplier Participation Agreement – Use POST /varm/v1/participationagreement to submit supplier's consent to the participation agreement.
   • Supplier Customer Onboarding – Use POST /varm/v1/onboarding/customer to onboard new customers and link them to existing suppliers.
   • Supplier Relationship Information – Use GET /varm/v1/relationshipinfo to query existing supplier-customer relationships.

   Payment APIs (used after onboarding is complete):

   • Payment Request – 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.
   • Supplier Deposit Confirmation – Use POST /varm/v1/deposit to process deposit transactions and confirm that penny test deposits were successfully received by suppliers.
   • Status Inquiry – Use GET /varm/v1/paymentinfo if you have existing request IDs to query.

   For initial testing, the onboarding status or relationship information endpoints are often easier to test as they require fewer parameters. If you are testing the payment functionality, the status inquiry endpoint is recommended as a starting point.

2. Set up the required headers based on your chosen endpoint.

   Onboarding APIs:

   • For POST /varm/v1/onboarding/supplier, set Content-Type: application/json (no authentication headers required).
   • For GET /varm/v1/onboardingstatus, no authentication headers required.
   • For POST /varm/v1/participationagreement, set Content-Type: application/json (no authentication headers required).
   • For POST /varm/v1/onboarding/customer, set Content-Type: application/json (no authentication headers required).
   • For GET /varm/v1/relationshipinfo, no authentication headers required.

   Payment APIs:

   • For POST /varm/v1/payment, set Content-Type: application/json.
   • For POST /varm/v1/deposit, set Content-Type: application/json.
   • For GET /varm/v1/paymentinfo, no authentication headers required.
3. Build the complete URL using the certification environment base URL. VDP Sandbox base URL will be published once it is live.

   Onboarding API query parameters:

   • For /varm/v1/onboardingstatus, set the request_id (required).
   • For /varm/v1/relationshipinfo, set the type (optional), supplierId (optional), and customerId (optional). If customerId is passed, supplierId is mandatory.

   Payment API query parameters: For /varm/v1/paymentinfo, set the request_id (required), payment_id (optional), and pageno (optional, defaults to 1).

4. Prepare your request body (if applicable).

   Onboarding APIs:

   • For POST /varm/v1/onboarding/supplier, prepare JSON with supplier_info containing company details, address, business contact, and notification recipient information.
   • For POST /varm/v1/participationagreement, prepare JSON with signer_details, participation_agreement_link, and supplier_id.
   • For POST /varm/v1/onboarding/customer, prepare JSON with customer_info, supplier_id, and optional address.
   • For GET requests (onboardingstatus, relationshipinfo), no request body is needed.

   Payment APIs:

   • For POST /varm/v1/payment, prepare JSON with request_id, supplier_id, and payment_details array.
   • For POST /varm/v1/deposit, prepare JSON with request_id, supplier_id, and payment_details array.
   • 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 and message 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.

Onboard a new supplier to Visa AR Manager with complete company details, address, business contact, and notification recipient information using the Supplier Profile API endpoint (/varm/v1/onboarding/supplier).

Supplier profile establishes the foundational business entity within Visa AR Manager that will receive virtual card payments. This process requires business information and establishes notification preferences.

Before doing so, ensure you have valid client credentials configured for authentication and have completed Visa AR Manager program enrollment.

1. Prepare the supplier company information with all required business details.
   • company_name – Legal name of the company
   • dba_name – Doing Business As name (optional)
   • mcc – Merchant Category Code
   • supp_time_zone – Time zone preference for the supplier
2. Structure the complete business address information.
   • country_code – Two-letter ISO country code
   • address_line1 – Primary address line
   • address_line2 – Secondary address line (optional)
   • city – City name
   • state – State or province
   • zipcode – Postal or ZIP code
3. Configure the primary business contact information.
   • first_name and last_name – Business contact name
   • company_email_address – Email for business communications
   • phone – Phone number with country code structure, including phone_country_code (country code without + sign) and phone_number (phone number without country code)
4. Set up reconciliation and exception notification recipients. The email address populated will receive the daily reconciliation file for all payments and associated invoices successfully authorized by the acquirer/processor or designated gateway. If Visa AR Manager will not be sending notifications to the supplier, include a no-reply email address (for example, [email protected]). Configure both recon_recipient_info and exception_recipient_info with:
   • email – Recipient email address
   • language – Language preference (en-us, en-uk, fr-fr, fr-ca, de-de, it-it, pt-br, es-us, es-es)
   • time_zone – Time zone in specific format (refer to the API specifications for more details)
   • date_format – Date format preference (MM/dd/yyyy, dd/MM/yyyy, yyyy/MM/dd, MMM-dd-yyyy, dd-MMM-yyyy)
5. Configure payment preferences (optional). Set allow_payments_on_invoice_mismatch boolean flag to indicate whether payments should be relayed to the acquirer/processor or designated payment gateway if invoice amounts do not add up to the total payment amount.
6. Make a POST request to the /varm/v1/onboarding/supplier endpoint and send the supplier profile request.
   • URL – https://[base-url]/varm/v1/onboarding/supplier
   • Method – POST
   • Content-Type – application/json
   • Headers – No authentication headers required
7. Process the response and extract key information.
   • Check the status field: 1000 (Enqueued), 1001 (Success), 4001 (Validation Error), 5000 (Error).
   • Store the request_id for tracking onboarding progress.
   • Record the varm_email_id for future supplier identification.
   • Save the participation_agreement_link for compliance workflow.
   • Review any details array for validation error information.

After successful supplier onboarding, you will receive a response with status 1000 (Enqueued) or 1001 (Success), along with a request ID for tracking the onboarding progress and a participation agreement link for the consent workflow.

Use the request ID to monitor the onboarding status. Proceed with participation agreement consent submission once supplier profile provisioning is complete.

Retrieve the current status of a supplier onboarding request and track provisioning progress using the Visa AR Manager Supplier Onboarding Status API endpoint (/varm/v1/onboardingstatus).

Supplier onboarding status monitoring provides detailed visibility into the supplier provisioning workflow, including completion status for each stage of the onboarding process from initial profile creation through final account validation.

Before doing so, ensure you have the request ID returned from the initial supplier onboarding request.

1. Prepare the request ID from the initial supplier onboarding response. Use the request_id value returned from the /varm/v1/onboarding/supplier endpoint response. This integer value uniquely identifies the onboarding request to track.
2. Configure the status inquiry request with proper query parameters. The request_id is an integer (int64) identifier used to track supplier onboarding status.
3. Make a GET request to the /varm/v1/onboardingstatus endpoint and send the supplier onboarding status request.
   • URL – https://[base-url]/varm/v1/onboardingstatus?request_id={request_id}
   • Method – GET
   • Headers – No authentication headers required
   • Query Parameters – request_id (required)
4. Analyze the onboarding status response for comprehensive status tracking.
   • Check the overall status field: 1000 (Enqueued), 1001 (Success), 4001 (Validation Error), 5000 (Error).
   • Review the message for detailed status information.
   • Examine supplier_id details for supplier identification.
   • Access participation_agreement_link for supplier consent.
5. Track completion of each provisioning stage in supplier_provisioning_status.
   • supplier_onboarding – Supplier profile creation (boolean)
   • participation_agreement – Participation agreement consent submission (boolean)
   • supplier_configuration – Supplier configuration (boolean)
   • customer_creation – At least one customer relationship created (boolean)
   • penny_test – Penny test completion (boolean)
   • deposit – Deposit confirmation (boolean)
6. Implement appropriate handling based on provisioning status.
   • In Progress – Continue monitoring if any stages show false status.
   • Ready for Next Steps – Proceed with participation agreement submission when supplier_onboarding is true.
   • Customer Onboarding Ready – Begin customer creation when supplier_configuration is complete.
   • Penny Test Ready – Initiate penny test process when configuration allows.
   • Fully Provisioned – All stages complete, ready for payment.

After successful status inquiry, you will receive comprehensive provisioning status information showing the completion state of each onboarding stage, enabling you to proceed with appropriate next steps in the workflow.

Based on the provisioning status, proceed with the next appropriate step such as participation agreement consent submission, customer creation, or penny test completion. Continue monitoring until all provisioning stages are complete.

Submit the supplier participation agreement consent with authorized signer details after supplier onboarding completion using the Visa AR Manager Supplier Participation Agreement API endpoint (/varm/v1/participationagreement).

Participation agreement consent submission captures authorized signer information and formally establishes the legal agreement between the supplier and Visa AR Manager.

Before doing so, ensure that the supplier_onboarding provisioning stage is complete and you have received the participation agreement link from the Supplier Profile API response.

1. Prepare the authorized signer details and collect the required signer information for the participation agreement.
   • name – First and last name of the authorized signer
   • email – Email address of the authorized signer
   • title – Job title or position of the authorized signer
2. Retrieve and use the participation agreement link (participation_agreement_link) returned from the supplier onboarding API response. This URL contains the consent document that needs to be referenced in the agreement submission.
3. Provide supplier identification using one or both identifiers.
   • originator_supp_id – Your internal supplier identifier (optional)
   • primary_email_address – Supplier's Visa AR Manager email address (optional)
4. Validate signer information and agreement link.
   • Ensure the signer email format is valid.
   • Confirm the participation agreement link is accessible and has been opened by the authorized signer.
   • Verify the supplier identification matches the onboarded supplier.
5. Make a POST request to the /varm/v1/participationagreement endpoint and send the participation agreement request.
   • URL – https://[base-url]/varm/v1/participationagreement
   • Method – POST
   • Content-Type – application/json
   • Headers – No authentication headers required
6. Process the participation agreement response.
   • Check the status field: 1001 (Success) or 4001 (Validation Error).
   • Record the agreement_id for future reference and audit trails.
   • Note the submission_date in ISO 8601 format for compliance records.
   • Review any validation errors if status indicates failure.

After successful participation agreement submission, you will receive a response with status 1001 (Success), along with a unique agreement ID and submission timestamp for compliance and audit purposes.

With the participation agreement consent submitted, the supplier provisioning process can continue.

Create new customer relationships and link them to existing suppliers in Visa AR Manager using the Supplier Customer Onboarding API endpoint (/varm/v1/onboarding/customer).

Supplier customer onboarding establishes the customer-supplier relationships required for virtual card payment initiation.

Before doing so, ensure that the associated supplier has been successfully onboarded and provisioned in Visa AR Manager.

1. Prepare the customer identification and basic information with all required customer details.
   • customer_id – Unique identifier for the customer that will be used in the payment instruction
   • customer_name – Full company name of the customer
   • preferred_currency – Three-letter ISO currency code (for example, USD, EUR, CAD)
2. Provide the supplier identification using one or both identifiers to establish the customer relationship.
   • originator_supp_id – Your internal supplier identifier (optional)
   • primary_email_address – Supplier's primary email address (optional)
3. Add customer address information (optional, but highly recommended for US suppliers).
   • country_code – Two-letter ISO country code
   • zipcode – Postal or ZIP code
   • state – State or province identifier
4. Validate currency code format and supplier status.
   • Ensure the preferred currency follows the three-character ISO format pattern.
   • Verify the supplier exists and is properly provisioned in Visa AR Manager.
5. Make a POST request to the /varm/v1/onboarding/customer endpoint and send the customer onboarding request.
   • URL – https://[base-url]/varm/v1/onboarding/customer
   • Method – POST
   • Content-Type – application/json
   • Headers – No authentication headers required
6. Process the customer onboarding response.
   • Check the status field: 1001 (Success) or 4001 (Validation Error).
   • Record the returned customer_id for future reference.
   • Review any details array for validation error information.
   • Verify the customer-supplier relationship has been established.

After successful customer onboarding, you will receive a response with status 1001 (Success) and a customer ID confirming the establishment of the customer-supplier relationship within the Visa AR Manager system.

Verify the customer-supplier relationship. The customer is now ready to initiate virtual card payments to Visa AR Manager.

Retrieve information about established customer–supplier relationships, with support for filtering by type, supplier ID, or customer ID, using the Visa AR Manager Supplier Relationship Details API endpoint (/varm/v1/relationshipinfo).

Supplier relationship details retrieval provides comprehensive visibility into established customer-supplier relationships, supporting operational management and relationship monitoring through flexible filtering options and pagination support for large datasets.

Before doing so, ensure that suppliers and customers have been properly onboarded and their relationships established within Visa AR Manager.

1. Determine the scope of relationship information to retrieve. Choose the appropriate information type using the type parameter:
   • ALL – Retrieve all established relationships (default)
   • SUPPLIER – Focus on supplier-specific relationship information
   • CUSTOMER – Focus on customer-specific relationship information
2. Configure filtering parameters to narrow the relationship results based on your requirements (optional). Use filters independently or in combination to target specific relationships.
   • supplierId – Primary email address of the supplier to filter by (email format)
   • customerId – Specific customer ID to filter relationship information
3. Validate query parameters before submission.
   • Ensure the type parameter uses valid enumeration values (ALL, SUPPLIER, CUSTOMER).
   • Verify supplierId follows proper email format if provided.
   • Confirm customerId matches existing customer identifiers if specified.
   • Check that filtering parameters align with your operational requirements.
4. Make a GET request to the /varm/v1/relationshipinfo endpoint and send the relationship information query request.
   • URL – https://[base-url]/varm/v1/relationshipinfo
   • Method – GET
   • Headers – No authentication headers required
   • Query Parameters – type, supplierId, customerId (all optional)
5. Analyze the comprehensive relationship data returned in the response.
   • Check the status field: 1001 (Success), 4001 (Validation Error), 5000 (System Error).
   • Review the message for operational status information.
   • Process the relationship array containing supplier-customer relationship details.
   • Access customer information through the customer.customer_list array within each relationship.
   • Access nested supplier and customer information, including detail links for expanded data.
   • Review pagination details in both response-level and customer-level page_dtls objects if present.
6. Process pagination information from the response to handle large relationship datasets efficiently.
   • Response-level pagination – Use page_dtls in the main response for overall result navigation.
   • Customer-level pagination – Use page_dtls within each relationship's customer container for customer-specific navigation.
   • Navigation URLs – Utilize provided URLs for first, last, next, and previous pages.
   • Record counts – Monitor current_no_records, total_records, and total_pages.

   Customer data is accessed through the container structure: response.relationship[0].customer.customer_list[]

   Key pagination fields include:

   • current_page, page_size – Current page information
   • total_pages, total_records – Overall dataset information
   • next_page_url, previous_page_url – Navigation URLs
   • first_page_url, last_page_url – Direct navigation to boundaries

   Example pagination structure:

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 Request 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)
   • primary_email_address (optional)
3. Build the customer_info object with the customer information.
   • Customer Identifier – Either originator or customer ID
   • Customer Name – Full customer company 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.
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.

Validate penny test deposits were successfully received by suppliers using the Visa AR Manager Supplier Deposit Confirmation API endpoint (/varm/v1/deposit).

This API supports batch processing of multiple deposit confirmations.

Before doing so, ensure that the supplier is properly onboarded, customers are linked, and a penny test has been initiated by Visa AR Manager.

1. Send the unique payment request identifier for the deposit confirmation batch. Send the unique payment request_id string (1-100 characters) from the penny test payment that will be used to track this deposit confirmation request.
2. Provide the supplier identification using one or both identifiers for the deposit confirmation.
   • originator_supp_id – Your internal supplier identifier (optional)
   • primary_email_address – Supplier's Visa AR manager email address (optional)
3. Structure the payment details array for deposit confirmations. Create payment details array (1-10 items) with transaction information structured as follows:
   • payment_id – Unique identifier for the specific payment transaction
   • customer_name – Full customer company name (optional)
   • customer_identifier – Customer identification object with originator_customer_id (optional) or customer_id
4. For each payment detail, structure the order information and amount details.
   • total_amount – Payment amount in decimal format (minimum 0.01, multiple of 0.01)
   • currency – Three-letter ISO currency code (for example, USD, EUR, CAD)
5. Validate deposit confirmation data before submission.
   • Ensure request_id is unique and within character limits.
   • Verify payment_id values are unique within the request.
   • Confirm currency codes follow the ISO 4217 three-character format.
   • Validate amount values are properly formatted decimals.
   • Check that payment details array contains 1-10 items.
6. Make a POST request to the /varm/v1/deposit endpoint and send the deposit confirmation request.
   • URL – https://[base-url]/varm/v1/deposit
   • Method – POST
   • Content-Type – application/json
   • Headers – No authentication headers required
7. Analyze the response for comprehensive status information.
   • Check the status field: SUCCESS, ENQUEUED, PARTIAL_SUCCESS, FAILED, VALIDATION_FAILURE, or SYSTEM_ERROR.
   • Review the reason_code: 1001 (Success), 1000 (Enqueued), 1003 (Partial Success), 1004 (Failed), 4001 (Validation Failure), 5001 (System Error).
   • Examine the reason_desc for detailed status explanation.
   • Record the returned request_id for audit and tracking purposes.

After successful deposit confirmation, you will receive a response indicating the overall status, with SUCCESS or PARTIAL_SUCCESS indicating completion of the penny test validation process for the supplier.

With deposit confirmation complete, supplier validation is finalized. Monitor the onboarding status to confirm all provisioning stages are complete and the supplier is ready for live payments.

Monitor and retrieve payment transaction status using the Visa AR Manager Retrieve Payment Status 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. Use pagination parameters when expecting large result sets to optimize performance.
   • payment_id (optional; specific payment transaction identifier, up to 20 characters)
   • pageno (optional; page number for pagination, defaults to "1")
3. Set up required authentication headers.
4. Build the complete URL with required and optional parameters. Ensure proper URL encoding for all query parameters.

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

5. Make a GET request to the /varm/v1/paymentinfo endpoint and send the status inquiry request. A request body is not required for status inquiry operations.
   • URL – Complete URL with query parameters
   • Method – GET
   • Headers – Client credentials
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 operations including relaying payment instructions to the acquirer/processor or designated payment gateway, supplier onboarding, and deposit confirmation.
  • 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.
  • For onboarding operations, use integer format (int64) request IDs for status tracking and monitoring.
  • For deposit confirmation operations, use string format request IDs (1-100 characters) that cannot be reused even for retry attempts.
• 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.
  • Respect array size limits: payment_details arrays support 1-10 items maximum for batch operations.
  • Adhere to character length constraints: request_id (1-100 characters), payment_id (1-10 characters), originator IDs (maximum 100 characters), email addresses (maximum 253 characters).
  • Use appropriate data types for request parameters: integer (int64) for onboarding status request_id and string format for deposit confirmation request_id.
• Data Handling – Follow best practices for sensitive data handling:
  • Validate all input data before sending API requests according to API specification constraints.
  • Implement proper data sanitization and encoding.
  • Follow PCI compliance standards for payment card information.
  • Use secure communication channels (HTTPS) for all API interactions.
  • Apply specific validation patterns: ISO country codes (2-letter, pattern ^[A-Z]{2}$), ISO currency codes (3-letter, pattern ^[A-Z]{3}$), email format validation (maximum 253 characters).
  • Validate language codes against supported values (en-us, en-uk, fr-fr, fr-ca, de-de, it-it, pt-br, es-us, es-es) and date formats (MM/dd/yyyy, dd/MM/yyyy, yyyy/MM/dd, MMM-dd-yyyy, dd-MMM-yyyy).
  • Ensure phone number structure includes phone_country_code (without + sign) and phone_number components as separate fields.
• 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 API 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 information.
  • Implement proper state management for multi-step transmission of virtual card details.
  • Handle workflow dependencies and prerequisites appropriately.
  • Follow the required onboarding sequence: supplier onboarding first, then status monitoring, participation agreement submission, customer onboarding, and finally deposit confirmation.
  • Monitor supplier provisioning status before proceeding to dependent operations (customer onboarding requires supplier_configuration to be complete).
  • Implement polling mechanisms for asynchronous onboarding operations that return status 1000 (Enqueued) until completion.
  • Ensure participation agreement is submitted only after supplier onboarding is complete and before customer onboarding begins.
• 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.