Visa Recurrent

Visa Recurrent APIs for Issuers

Available for use by:
Issuer banks Acquirer banks Merchants Independent developers Issuer banks for small businesses

Getting Started — Issuers

The Visa Recurrent API enables Issuers to access and manage subscription details related to cardholders' recurring payment agreements.

The API provides two primary operations for Issuers:

  • View Recurring Payment Agreements – Retrieve lists of recurring payment agreements based on card information, merchant details, status, and date ranges
  • Cancel Recurring Payment Agreements – Terminate existing recurring payment agreements with optional cancellation reasons

Prerequisites

Before integrating with Visa Recurrent APIs, ensure all prerequisites are in place.

  • Visa Developer Center (VDC) Account – Developers register and then log in to Visa Developer Center to obtain credentials, including API Keys and cryptographic key material.
  • Sandbox Environment – Visa Recurrent APIs are available in the sandbox after registration and acceptance of VDC terms and conditions.
  • Production Environment – Only participating issuers use Visa Recurrent APIs in production environment.
  • Visa Developer Center (VDC) Agreement – The VDC Agreement governs and controls if any conflict exists between this specification and the VDC Agreement.

Sandbox Environment

The Visa Recurrent API provides a dedicated sandbox environment for development, testing, and integration verification before production deployment.

The Visa Recurrent API is available in both sandbox and production environments:

  • Sandbox – https://sandbox.api.visa.com/vr/v1/issuer/
  • Production – https://api.visa.com/vr/v1/issuer/

Sandbox Environment Details:

  • API Base Path – /vr/v1/issuer/
  • View Endpoint – https://sandbox.api.visa.com/vr/v1/issuer/card/recurringPaymentAgreements/search
  • Cancel Endpoint – https://sandbox.api.visa.com/vr/v1/issuer/card/recurringPaymentAgreements/{vRecurringPaymentAgreementId}/cancel

Sandbox Capabilities:

  • All Authentication Methods – X-Pay-Token and Two-way SSL authentication are supported
  • Complete Operations – Both search and cancel operations available for testing
  • MLE Support – Full Message Level Encryption implementation
  • Error Simulation – Test various error scenarios and response codes
  • Callback Testing – Webhook notification testing capabilities

General Testing Approach:

  • Use test card number that Visa provided in the sample request for payment instrument searches. For example, 4111111111111111
  • Test with different dummy dates available in the sandbox environment and search criteria
  • Verify pagination with different page sizes
  • Test cancellation operations with different agreement states

Transitioning to Production

Production URL: https://api.visa.com/vr/v1/issuer/

Before moving to production:

  1. Complete comprehensive testing in sandbox
  2. Verify all error handling scenarios
  3. Validate webhook notification processing (if applicable)
  4. Confirm performance meets requirements
  5. Update base URLs to production endpoints
  6. Switch to production credentials

How To Use — Issuers

Visa Recurrent provides two main API workflows for issuers that work together to manage cardholder recurring payment agreements.

  • View Recurring Payment Agreement Workflow – Use POST /vr/v1/issuer/card/recurringPaymentAgreements/search to handle cases where cardholders contact customer service or use the issuer app to view or search for recurring charges on their accounts.
  • Cancel Recurring Payment Agreement Workflow – Use DELETE /vr/v1/issuer/card/recurringPaymentAgreements/{vRecurringPaymentAgreementId}/cancel to cancel recurring payment agreements when charges are unauthorized, disputed, or voluntarily canceled.

Make Your First API Call

Making your first API call helps verify connectivity and authentication to successfully communicate with Visa Recurrent API.

Prerequisites:

Before making your first API call, ensure you have completed:

  • Completed all prerequisite setup requirements
  • Configured your chosen authentication method
  • Implemented Message Level Encryption (MLE)
  • Access to sandbox environment (sandbox.api.visa.com)

Your first API call should be a simple search operation to verify that your authentication, MLE implementation, and basic connectivity are working correctly. The search endpoint is ideal for initial testing as it requires minimal parameters and provides clear success/failure feedback.

Steps:

{
  "paymentInstrument": {
    "accountNumberType": "PAN",
    "cardAccountNumber": "4111111111111111"
  }
}
Copied!

Result:

A successful first API call confirms:

Next Steps:

After successful completion:

View Recurring Payment Agreement Workflow

The View Recurring Payment Agreement Workflow supports the scenario in which cardholders contact customer service or use the issuer application to view or search for recurring charges on their accounts.

Use POST /vr/v1/issuer/card/recurringPaymentAgreements/search.

Steps:

  1. View Recurring Payments – Cardholders select the option to view recurring payments. This action triggers the Search or View API.
  2. Retrieve PAN – The Search or View API request returns a Primary Account Number (PAN).
  3. Review Subscription Plan – Cardholder selects a recurring payment agreement or subscription. This action triggers the Search or View API, with additional filters.
  4. Present Information – Provide cardholder with recurring payment agreement details.

Cancel Recurring Payment Agreement Workflow

When cardholders report unauthorized or disputed recurring charges, or when they want to cancel recurring charges without a dispute, this workflow provides a path to cancel the agreement.

Steps:

  1. View Recurring Payments – Cardholders select the option to view recurring payments. This action triggers the Search or View API. Use POST /vr/v1/issuer/card/recurringPaymentAgreements/search.
  2. Review Agreement Details – Review merchant, plan, and payment information.
  3. Authorize Cancellation – The cardholder authorizes the cancellation in the application. This action serves as the trigger and verification.
  4. Execute Cancellation – Execute cancel API with appropriate cancellation reason. Use DELETE /vr/v1/issuer/card/recurringPaymentAgreements/{vRecurringPaymentAgreementId}/cancel.

Best Practices

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

API Integration – Guidelines for robust and maintainable API integrations:

  • Always include Ex-Correlation-Id headers with unique values
  • Log correlation IDs for troubleshooting and support requests
  • Maintain request/response audit trails
  • Implement proper pagination logic for search operations
  • Use reasonable page sizes (100-500 items) for performance
  • Handle empty result sets gracefully
  • Monitor totalCount for data volume planning
  • Respect the 12-month historical data limit
  • Use specific date ranges to optimize query performance
  • Handle timezone considerations in date calculations
  • Validate date ranges before API calls

Authentication and Security – Follow security best practices for API authentication:

  • Store API keys and shared secrets securely using encryption
  • Use environment variables or secure key management systems
  • Rotate credentials regularly according to security policies
  • Never expose credentials in client-side code or logs
  • Implement MLE correctly for all request and response payloads
  • Validate encryption/decryption before production deployment
  • Handle MLE key lifecycle and rotation properly
  • Test MLE implementation with various payload sizes
  • Always use HTTPS/TLS for API communications
  • Validate SSL certificates properly
  • Use TLS 1.2 or higher versions
  • Implement certificate pinning where appropriate

Error Handling – Implement comprehensive error handling for reliable operations:

  • Implement exponential backoff for retryable errors (503, 429)
  • Respect Retry-After headers when provided
  • Set maximum retry limits to avoid infinite loops
  • Do not retry non-retryable errors (400, 401, 403)
  • Parse error response details arrays for specific field issues
  • Log complete error responses for troubleshooting
  • Use reason codes for programmatic error handling
  • Provide meaningful error messages to end users
  • Set appropriate connection and read timeouts
  • Handle timeout scenarios gracefully
  • Implement circuit breaker patterns for resilience
  • Monitor timeout rates and adjust as needed

Performance Optimization – Optimize API integration for performance and efficiency:

  • Reuse HTTP connections where possible
  • Group related operations when applicable
  • Cache frequently accessed data appropriately
  • Implement client-side rate limiting to avoid 429 errors
  • Track API response times and success rates

Data Management Best Practices – Follow best practices for sensitive data handling:

  • Follow data protection regulations
  • Minimize data storage and retention periods
  • Encrypt sensitive data at rest and in transit
  • Implement proper data access controls
  • Validate all input parameters before API calls
  • Handle data format conversions properly (dates, amounts)
  • Verify card number formats and checksums
  • Sanitize data for logging and display

Operational – Establish operational excellence for production environments:

  • Set up comprehensive monitoring for API health and performance
  • Implement structured logging with appropriate detail levels
  • Maintain comprehensive test coverage for all scenarios
  • Use staged deployments with proper validation
  • Keep integration documentation current and accessible
  • Establish clear procedures for incident response and support

Authentication Methods — Issuers

Visa Recurrent API supports multiple authentication methods to provide flexibility and security for different integration requirements. All authentication methods work in conjunction with Message Level Encryption (MLE) to ensure comprehensive security for API communications.

Clients can choose X-Pay-Token or Two-way SSL authentication.

  • X-Pay-Token – Recommended for most integrations, using API Key and Shared Secret
  • Two-way SSL – Certificate-based mutual authentication

X-Pay-Token Authentication

X-Pay-Token is the recommended authentication method for Visa Recurrent API. It provides strong security through HMAC-SHA-256 signatures with timestamp-based replay protection and 480-second token expiration.

Prerequisites:

Before implementing X-Pay-Token authentication, ensure you have:

  • API Key from your Visa Developer Center (VDC) project
  • Shared Secret from your VDC project credentials
  • HMAC-SHA-256 cryptographic capability in your development environment
  • UTC timestamp generation functionality

Steps:

  1. Generate the UTC timestamp for the request.

    This timestamp must be within 8 minutes of the current time when the request reaches Visa servers. For example, 1587756817 (UTC seconds).

  2. Prepare the API name component.

    The API name is the resource path without the leading slash:

    • View endpoint – issuer/card/recurringPaymentAgreements/search
    • Cancel endpoint – issuer/card/recurringPaymentAgreements/{vRecurringPaymentAgreementId}/cancel
  3. Construct the query string component.

    Concatenate all query string parameters (including apiKey) as URL-encoded UTF-8 characters:

    • Sort parameters lexicographically by name
    • Format as name=value pairs separated by &
    • URL-encode values per RFC 3986 (uppercase hex characters)
    • Do not URL-encode unreserved characters: - . _ ~

    For example, apiKey=M93HLKI2M55ST8QR9RYW3PUFG42mrpN0CsMeLNWbFWPAteAGA&page=0&size=100

  4. Prepare the request body with the raw JSON payload.
    • Include the entire MLE-encrypted request body
    • Use exact string representation
    • For GET requests with no body, use empty string
  5. Create the signature string.

    Concatenate the components in this order, signatureString = timestamp + apiName + queryString + entityBody.

    Ensure that there are no separators between components.

  6. Generate and compute the HMAC-SHA-256 signature using.
    • Key – Shared secret from VDC
    • Message – The signature string from previous step
    • Output – Hexadecimal representation (lowercase)
  7. Construct the X-Pay-Token header value.

    Format the token as X-Pay-Token: xv2:{timestamp}:{hmacSignature}

    For example, xv2:1587756817:2e1dbb9d10dcb8f22913a1900b3f985220fedb5918e9e8d192fa49a3f2c8a76c

  8. Add the X-Pay-Token header to your API request along with other required headers.
    • Content-Type: application/json
    • Accept: application/json
    • Ex-Correlation-Id: {unique-uuid}

Result:

Successful X-Pay-Token implementation provides:

  • Strong authentication with HMAC-SHA-256 cryptographic signatures
  • Replay attack protection through timestamp validation
  • Request integrity verification
  • 480-second token lifetime for security

Next Steps:

After implementing X-Pay-Token authentication:

  • Test with various request types and payloads
  • Verify proper error handling for expired tokens
  • Implement token regeneration for failed requests
  • Monitor timestamp accuracy to prevent authentication failures

Two-way SSL Authentication

Two-way SSL provides certificate-based authentication where both client and server verify each other's identities. This method is suitable for high-security environments and system-to-system integrations.

Prerequisites:

Before implementing Two-way SSL authentication, ensure that you have:

  • Valid client certificate from Visa Developer Center
  • Private key corresponding to your client certificate
  • Certificate Authority root certificate (DigiCert Global Root CA)
  • SSL/TLS client configuration capability in your development environment

Steps:

  1. Obtain and prepare your client certificate.
  2. Download and configure the DigiCert Global Root CA certificate.
    • Download URL – https://dl.cacerts.digicert.com/DigiCertGlobalRootCA.crt
    • Convert to PEM format if needed using OpenSSL or Windows Certificate Manager
    • Install in trust store of your HTTP client or system
  3. Set up your private key securely.

    Ensure proper private key management:

    • Store private key in secure location with restricted access
    • Use appropriate file permissions (600 on Unix systems)
    • Consider using hardware security modules (HSMs) for production
    • Implement key rotation procedures per security policies
  4. Configure SSL/TLS settings in your HTTP client
    • Client Certificate – Specify path to client certificate file
    • Private Key – Specify path to private key file
    • CA Bundle – Include DigiCert root certificate
    • TLS Version – Use TLS 1.2 or higher
    • Certificate Verification – Enable full certificate chain validation
  5. Verify proper SSL configuration before API calls
    • a. Client requests access to Visa API endpoint.
    • b. Server presents its certificate to client.
    • c. Client verifies server certificate against CA.
    • d. Client sends its certificate to server.
    • e. Server validates client certificate and signature.
    • f. Successful handshake enables encrypted communication.
  6. Execute API calls with Two-way SSL authentication.
    • No additional authentication headers required
    • Include standard headers
    • SSL certificate authentication occurs automatically during connection
    • Verify successful authentication through 200 OK responses

Result:

Successful Two-way SSL implementation provides:

  • Strong mutual authentication between client and server
  • Certificate-based identity verification
  • Encrypted communication channel
  • Non-repudiation through digital signatures

Next Steps:

After implementing Two-way SSL authentication:

  • Monitor certificate expiration dates and plan renewals
  • Test certificate validation error scenarios
  • Implement proper error handling for SSL handshake failures
  • Document certificate management procedures
  • Consider certificate revocation list (CRL) checking

Certificate management is critical for Two-way SSL. Ensure proper procedures for certificate lifecycle, renewal, and revocation.

API Key Authentication

API Key authentication provides a simplified authentication method using the API Key as a query parameter. This method is suitable for basic integrations where advanced cryptographic authentication is handled through other security layers.

Prerequisites:

Before implementing API Key authentication, ensure that you have:

  • API Key from your Visa Developer Center project
  • HTTPS-capable HTTP client for secure transmission
  • Secure credential storage mechanism
  • Understanding of query parameter handling

Steps:

  1. Obtain your API Key from Visa Developer Center.
    • a. Log in to Visa Developer Center
    • b. Navigate to your project dashboard
    • c. Locate the API Key in project credentials section
    • d. Copy the API Key for use in your integration
  2. Store the API Key securely.
    • Use environment variables or secure configuration files
    • Encrypt API Key at rest using appropriate encryption
    • Restrict access to API Key storage locations
    • Never expose API Key in client-side code or logs
  3. Add API Key to request query parameters.
    • Parameter name – apiKey
    • Parameter value – Your API Key from VDC
    • URL encoding – Apply proper URL encoding if needed
    • Example – apiKey=M93HLKI2M55ST8QR9RYW3PUFG42mrpN0CsMeLNWbFWPAteAGA
  4. Configure additional query parameters.
  5. Set required HTTP headers.
    • Content-Type – application/json
    • Accept – application/json
    • Ex-Correlation-Id – Unique UUID for request tracking

    No additional authentication headers are required when using API Key.

  6. Execute the API request.

Result:

Successful API Key authentication provides:

  • Simple integration with minimal setup complexity
  • Direct credential validation without cryptographic operations
  • Clear authentication error messages
  • Compatibility with standard HTTP client libraries

Next Steps:

After implementing API Key authentication:

  • Monitor API Key usage and access patterns
  • Implement API Key rotation procedures
  • Test authentication failure scenarios and error handling
  • Consider upgrading to X-Pay-Token for enhanced security
  • Ensure API Key is never logged or exposed in debugging

API Key authentication is simpler but less secure than X-Pay-Token. Consider using X-Pay-Token for production environments requiring stronger authentication.

Error Codes — Issuers

The Visa Recurrent API returns standard HTTP status codes with detailed error response structures to help diagnose and resolve issues.

For error resolution assistance, contact Visa Support at [email protected].

HTTP Status Codes

Complete reference of HTTP status codes returned by the Visa Recurrent API with detailed descriptions and recommended actions.

Success Status Codes

Status Code Description Details and Usage
200 OK Request successful. Response contains requested data for search operations or confirmation for cancel operations.

Client Error Status Codes (4xx)

Code Description Common Causes Recommended Actions
400 Bad Request
  • Invalid request payload format
  • Missing required parameters
  • Invalid field formats or values
  • Date range exceeds 12-month limit
  • Validate request structure and data
  • Check field formats and constraints
  • Review error response details array
  • Fix validation errors before retry
401 Unauthorized
  • Invalid X-Pay-Token signature
  • Timestamp beyond 8-minute window
  • Inactive or invalid API Key
  • SSL certificate validation failure
  • Regenerate authentication token
  • Verify timestamp synchronization
  • Check API Key configuration
  • Validate SSL certificate setup
403 Forbidden
  • API not in VDC project configuration
  • Insufficient permissions
  • BIN ownership validation failure
  • Resource access restrictions
  • Verify VDC project configuration
  • Check API access permissions
  • Confirm BIN ownership
  • Contact Visa support if needed
404 Not Found
  • Recurring payment agreement not found
  • Invalid agreement ID format
  • Agreement not owned by issuer
  • Verify agreement ID format
  • Confirm issuer ownership
  • Handle as valid business scenario
  • Check search criteria accuracy
406 Not Acceptable
  • Unsupported API version requested
  • Invalid Accept header values
  • Version newer than available
  • Check API version in URL path
  • Verify Accept header format
  • Use supported API version (v1)
  • Review API versioning documentation
409 Conflict
  • Duplicate operation request
  • Invalid state transition
  • Already cancelled agreement
  • Check current agreement status
  • Verify operation validity
  • Handle as business logic scenario
  • Use idempotency keys properly
410 Gone
  • API version end-of-life
  • Deprecated endpoint accessed
  • Resource permanently removed
  • Upgrade to supported API version
  • Check Content-Type header for version info
  • Review API migration guides
  • Update integration to current version
413 Payload Too Large
  • Request body exceeds size limits
  • Large search result sets
  • Reduce request payload size
  • Use pagination for large queries
  • Optimize search criteria
429 Too Many Requests
  • Rate limit exceeded
  • Too many concurrent requests
  • VDC project limits reached
  • Implement exponential backoff
  • Respect Retry-After header
  • Reduce request frequency
  • Contact Visa for limit increases

Server Error Status Codes (5xx)

Code Description Common Causes Recommended Actions
500 Internal Server Error
  • Visa system errors
  • Unexpected server conditions
  • Processing failures
  • Retry with exponential backoff
  • Contact Visa support with correlation ID
  • Monitor error frequency
  • Implement circuit breaker pattern
503 Service Unavailable
  • Temporary system overload
  • Maintenance periods
  • Server capacity issues
  • Retry with exponential backoff
  • Check Retry-After header
  • Implement graceful degradation
  • Monitor service status

Response Headers

Important response headers to monitor and utilize:

Ex-Correlation-Id

Echoed back from request for tracking and support purposes. Always log this value for troubleshooting.

Retry-After

Provided with 503 and 429 errors to indicate recommended wait time before retry. Format can be HTTP date or seconds.

Content-Type

With 410 errors, indicates the latest supported API version for migration guidance.

Status Code Handling Best Practices

  • Categorize Responses: Group status codes into success (2xx), client error (4xx), and server error (5xx) for different handling approaches
  • Preserve Context: Always log the correlation ID, request details, and complete error response for debugging
  • Implement Retries Selectively: Only retry 5xx errors and 429 rate limiting errors
  • Handle Business Logic: Treat 404 and 409 as valid business scenarios, not system failures
  • Monitor Patterns: Track error rate trends to identify systemic issues

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 recurring payment outcomes, configuration issues, and operational conditions that require attention.

  • Search Operation Errors
    • Date range exceeds 12-month historical limit
    • Invalid card account number format
    • Missing required search criteria
    • Invalid status enum values
  • Cancellation Errors
    • Agreement already cancelled or expired
    • Invalid recurring payment agreement ID
    • Insufficient permissions for cancellation
    • Agreement not owned by requesting issuer

Retry and Recovery Guidelines

Implement appropriate retry logic based on error types.

  • Retry Errors
    • 503 Service Unavailable – Retry with exponential backoff, respect Retry-After header
    • 429 Too Many Requests – Implement rate limiting backoff, check Retry-After header
    • 500 Internal Server Error – Limited retries with backoff for transient issues
  • Non-Retry Errors
    • 400 Bad Request – Fix request format and validation errors before retry
    • 401 Unauthorized – Refresh credentials or fix authentication configuration
    • 403 Forbidden – Verify VDC project configuration and permissions
    • 404 Not Found – Handle as business logic