Visa Recurrent APIs for sellers

The Visa Recurrent API enables sellers to confirm recurring order status for their customers.

The API provides this operation to sellers:

• Confirm Recurring Payment Order Status – Confirm whether a recurring payment order cancellation was successfully processed or whether the cardholder was retained after a cancellation notification is received from Visa

The Visa Recurrent enrollment form captures business and technical configuration details required for Visa to provision Visa Recurrent. By submitting the enrollment form, the seller authorizes Visa to make the configuration changes specified in the form.

Sellers must complete these steps before beginning implementation:

1. Download the enrollment form from Visa Developer Center (VDC).
2. Complete the enrollment form with the required configuration and integration details:
   • Select the target environment (sandbox, CERT, or production).
   • Provide a requested effective date for service activation.
3. Submit the completed enrollment form:
4. For Visa Recurrent APIs, register and enroll in Visa Recurrent on VDC to access the APIs in the sandbox environment.

Review the relevant regional Visa Fee Schedule on Visa Access for implementation, usage, and other fees that may apply.

The enrollment form includes these sections:

• Merchant Information – Business name, Business ID, contact name, email, phone, website address, region, country, environment, requested effective date, billing entity and BID, and type of Visa Recurrent request.
• Organization Details – Merchant identifiers (VMID, CAID, Merchant Name, PFID|SMID, TRID) If enrolling multiple merchants or merchant businesses, provide details in the merchant details sheet.
• Organization Preferences – Redirect URL per merchant identifier for cardholder order management, whether to receive notifications on cardholder actions, and the notification URL endpoint.

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

• Visa Developer Center (VDC) Account – Developers register and 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.

  Initial project creation with data collection for profile setup, connectivity and authentication MLE validation, and simulated functional tests. Sandbox uses mock data; payment-block execution cannot be tested end-to-end in sandbox.

• Certification (CERT) Environment – Optional, on-request end-to-end validation environment with PACE callbacks and implementation manager-guided readiness checks. CERT is not a mandatory phase; production quiet testing is the recommended approach for validating payment-block execution.
• Production Environment – Only participating issuers with an applicable and current Visa Developer API agreement can use Visa Recurrent APIs in the production environment.
• Visa Developer Center (VDC) Agreement – The VDC Agreement governs. In the event of any conflict between this specification and the VDC Agreement, the VDC Agreement controls.

Verify client prerequisite tasks before implementing Visa Recurrent APIs.

1. The enrollment form is the client's enrollment vehicle and captures the identifiers, contacts, and configuration data Visa needs to provision Visa Recurrent. Activation cannot proceed until enrollment form submission and provisioning are confirmed.
2. Verify that the client has a signed click-through Visa Recurrent agreement (before production access) and that the enrollment or Visa Recurrent organization set up is provisioned.
3. Confirm the client is registered on Visa Developer Center (VDC).

   The client must have an active registration on developer.visa.com before a sandbox project can be created. If the client is not registered, direct them to complete registration before proceeding.

4. Confirm the client can host HTTPS webhook endpoints with mTLS for PACE callback delivery and has the capability to implement MLE for API calls.

Visa Recurrent environments for implementation and operations. The Visa Recurrent API is available in these environments:

• Sandbox – https://sandbox.api.visa.com/vr/v1/merchant/
• Certification (CERT) – https://cert.api.visa.com/vr/v1/merchant/
• Production – https://api.visa.com/vr/v1/merchant/

Sandbox Environment Details:

• API Base Path – /vr/v1/merchant/
• Confirm Recurring Payment Order Status Endpoint – https://sandbox.api.visa.com/vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation

Sandbox Capabilities:

Initial project creation with data collection for profile setup, connectivity and authentication MLE validation, and simulated functional tests. Sandbox uses mock data; payment-block execution cannot be tested end-to-end in sandbox.

For testing, clients use the PANs and VRR IDs provided in the sample payloads on VDC. Client PANs and test data are supported only in production.

• All Authentication Methods – X-Pay-Token and Two-way SSL authentication are supported
• Complete Operations – Confirm Recurring Payment Order Status operation is available for testing
• MLE Support – Full Message Level Encryption implementation
• Error Simulation – Test various error scenarios and response codes

Sandbox Limitations: The VDC sandbox does not support authorization and clearing test cases for cancelled or reactivated recurring orders, end-to-end payment processing, or notification testing. Clients access APIs through VDC and receive webhook notifications through PACE. While WSI acts as the Visa notification infrastructure behind the scenes, clients integrate only with PACE.

General Testing Approach:

• Test with different dummy dates available in the sandbox environment and search criteria
• Verify pagination with different page sizes

[Optional] Certification Environment: The Certification (CERT) environment is available for connectivity testing.

Transitioning to Production

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

Before moving to production (VDC and PACE)

1. Complete comprehensive testing in sandbox.
2. Verify all error handling scenarios.
3. Confirm performance meets requirements.
4. Complete and sign the required product terms.
5. Update base URLs to production endpoints.
6. Switch to production credentials.

Additional requirement for PACE

1. Validate webhook notification processing.
2. Confirm webhook callbacks are successfully received and acknowledged.

Additional requirement for VDC

1. Test all API operations with production data.

Visa Recurrent supports seller workflows for confirming recurring payment outcomes.

The API provides these operations to sellers:

• Notification Workflow – PACE notification configuration requires a callback URL in the Seller Profile on Visa Recurrent. See Enrollment. Sellers receive cancellation and reactivation events.
• Confirm Recurring Payment Order Status Workflow – Confirm recurring order outcomes through Visa Access using POST /vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation.

Sellers that provide a notification URL and have completed setup in PACE automatically receive webhook notifications when recurring orders are cancelled or reactivated.

Notification Endpoint Configuration

Sellers must configure their postback notification URL and API key during onboarding. The webhook endpoint must:

• Accept POST requests from Visa backend servers
• Accept mTLS connections from Visa for authentication
• Return 2XX response for successful processing
• Support automatic retries (2 retries with random 1-30 minute intervals for 5XX or 404 errors)

Notification Message Structure

Merchant notification callbacks include:

• messageMetadata – Contains vMessageId (unique UUID), createdDateTime, and message type. Valid values: RECURRING_PAYMENT_ORDER_CANCELLATION and RECURRING_PAYMENT_ORDER_REACTIVATION.
• visaRecurrentReferenceId – Correlation ID associated with the recurring order
• recurringPaymentOrderStatus – Current status of the order
• lastTransactionId – The last transaction ID associated with the recurring order
• subscriptionTransactionId (Optional) – Unique transaction ID that tracks the transaction across recurring payments

Merchant Confirmation Status

After receiving a cancellation notification, merchants confirm the outcome using the Confirm Recurring Payment Order Status API. Valid values are:

• RETAINED – Merchant successfully retained the recurring payment with the customer
• CANCELLED – Merchant confirmed the cancellation

Cancellation and Service Cancellation

Cancelling a recurring order places a payment block and updates the VRR ID status to CANCELLED. When Visa notifies the seller of the cancellation, the notification can also serve as a request to cancel the associated service agreement, as applicable. Depending on the seller's processes, additional actions may be required to fully terminate the service, and these actions should be handled directly with the merchant.

Notification Prerequisites

• Merchants must opt in to receive cancellation notifications during onboarding and profile setup. The required information is provided in the CIQ, which is submitted through Account Executors (AEs) or Client Support (CS) to the Support Hub.
• The callback URL must be configured in the merchant profile in PACE.
• Merchant endpoint must be accessible and properly secured
• Authentication credentials (API key) must be configured.

Authentication Requirements

Webhook notification callbacks use mTLS (mutual TLS) as the currently supported authentication method. Configure your notification endpoint to accept client certificates from Visa. The apiKey query parameter is not operative for outbound notifications at this time; it applies only after migration to the VDC outbound gateway.

Merchants must:

• Configure the notification endpoint to accept mTLS connections from Visa
• Use HTTPS for all webhook endpoints
• Implement appropriate logging without exposing sensitive data

Webhook callbacks from Visa include:

• X-Message-Tracking-Id header – Tracking ID for the notification

After receiving a cancellation notification, call this endpoint to confirm whether the recurring payment was retained or cancelled. This applies only when the merchant's integrationMode is set to NOTIFICATION_ONLY or REDIRECT_AND_NOTIFICATION.

Endpoint

POST /vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation

Sandbox: https://sandbox.api.visa.com/vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation

Production: https://api.visa.com/vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation

Include the V-C-Idempotency-Key header with a unique UUID for each request. Use Two-way SSL authentication. All payloads must use Message Level Encryption (MLE).

Response

HTTP 200 on success. The response body includes:

• visaRecurrentReferenceId – VRR ID of the confirmed recurring payment order
• merchantConfirmationStatus – Confirmed status: RETAINED or CANCELLED

Steps

1. Receive cancellation notification from Visa (includes visaRecurrentReferenceId)
2. Process the cancellation request internally and, where applicable, work with the cardholder to retain the service or update billing systems to cancel the recurring payment
3. Call POST /vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation with the VRR ID and merchantConfirmationStatus
4. Visa updates the order record

Implementing these best practices, which are non-comprehensive and illustrative only, can help ensure reliable, secure, and efficient integration with the Visa Recurrent APIs. Issuers should clearly explain the consequences of each action and obtain cardholder consent, where required, and remain responsible for complying with all applicable laws and regulations. This includes notifying merchants of cancellation requests and using any third-party services involved in processing cancellations or related workflows.

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
• Use unique V-C-Idempotency-Key values for each confirmation request

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
• 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
• 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
• 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

Visa Recurrent Profile Data Setup

• Provide all available merchant identifiers during enrollment, including merchant name, CAID, PFID/SMID, OTID, and any other supported identifiers, to improve recurring order identification accuracy.
• Ensure merchant identifiers are provided consistently and accurately.
• If merchant information changes, submit an update request through the Support Hub promptly.
• Accurate merchant identifiers help Visa Recurrent distinguish between unique recurring orders, improve recurring order matching, and reduce the risk of blocking unrelated recurring orders.
• Configure redirect URLs to take cardholders directly to the recurring order cancellation or recurring order management experience whenever possible.
• Avoid using generic homepages or landing pages that require cardholders to navigate further to find cancellation options.
• Review redirect URLs regularly to ensure they remain active and continue directing cardholders to the intended recurring order management experience.
• Accurate enrollment data and targeted redirect experiences improve the cardholder experience, reduce support inquiries, and increase successful recurring order management outcomes.

Authorization and Clearing – Ensure proper handling of merchant-initiated transactions (MITs) and transaction lifecycle events:

• Comply with the Merchant-Initiated Transaction (MIT) framework requirements.
• Ensure the correct Original Transaction Identifier (OTID) is passed to avoid overblocking and to support recurring payment use cases.

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.

Visa Developer Center (VDC):

• Two-way SSL – Certificate-based mutual authentication

PACE:

• Two-way SSL – Certificate-based mutual authentication

Two-way SSL provides certificate-based authentication where both client and server verify each other's identities.

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
   • 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
   • Certificate Verification – Enable full certificate chain validation
5. Verify proper SSL configuration before API calls.
   1. Client requests access to Visa API endpoint.
   2. Server presents its certificate to client.
   3. Client verifies server certificate against CA.
   4. Client sends its certificate to server.
   5. Server validates client certificate and signature.
   6. 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

Expected 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

Complete reference of error codes and handling guidelines for the Visa Recurrent API.

Errors use the same basic response shape:

Status codes (401, 403, 500, 503, and others) are generic and apply the same way across any Visa API. Only 404 and 409 carry meaning specific to recurring payment orders — and even then, the reason text alone won't identify exactly what went wrong.

Prepare these information before reaching out to Visa Support:

• The exact request you sent (method, URL, body, and headers, excluding secrets)
• The full error response, including the Ex-Correlation-Id header if present
• Whether the issue is reproducible or intermittent

Codes you can usually resolve yourself: 400, 401, 404, 406, 409, and 413. These are almost always something to fix in your own request, credentials, or logic.

Contact Visa Support at [email protected] if:

• You get a 500 or 503 that persists after retrying with backoff
• You get a 403 or 429 and your account/project setup looks correct
• You're unsure whether a 404 or 409 reflects a real data issue on Visa's side versus your own request — send the correlation ID and Visa can check

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

Success Status Codes

Client Error Status Codes (4xx)

Server Error Status Codes (5xx)

Response Headers

• 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.

Business logic errors in the Visa Recurrent 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.

• Status Confirmation Errors
  • Recurring order not found
  • Confirmation already submitted for this order (409)
  • Invalid merchantConfirmationStatus value
  • Order not associated with requesting merchant

Webhook authentication failures are not retried — ever. If your webhook receiver rejects a Visa notification with 401 or 403, that notification is gone permanently, with no visibility on Visa's side into why it failed. Visa only retries a callback on a 5xx server error or a 404 — 2 retries, spaced randomly 1–30 minutes apart.

• Set up alerting on your own receiver for any 401 or 403 it emits. This is the one failure mode with no safety net.
• You must opt in for the cancellation notification webhook and configure the callback URL in your Merchant Profile. Confirm this is set up correctly, ideally with a test call, before relying on production traffic to surface a misconfiguration.

After you call statusConfirmation, allow time for the issuer to see the updated merchantConfirmationStatus — the confirmation doesn't appear on their side instantaneously. See Merchant Status Confirmation for the full request/response flow.

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

Sample request and response payloads for the Visa Recurrent API endpoints used by sellers.

POST /vr/v1/merchant/card/recurringPaymentOrders/statusConfirmation

Sample request

Sample response (200 OK)

Sample error response (400 Bad Request)

POST {postbackNotificationUrl}

Visa sends this webhook to the seller's configured postbackNotificationUrl when the issuer cancels a recurring payment order. This callback is sent only if the seller has opted in for cancellation notifications and configured a callback URL in the merchant profile.

Sample request body

The seller returns an HTTP 2XX status code to acknowledge successful processing. Visa retries the callback up to two times, at random intervals between 1 and 30 minutes, if the seller returns a 5XX or 404 status code.