Clients can create a frictionless and consistent recurring payment or subscription management mobile experience for cardholders using the Visa Subscription Manager APIs.
Visa Subscription Manager allows cardholders to monitor and manage recurring payments directly, reducing the need to contact cardholder support for help. Cardholders can view merchants that have their card on file and stop unwanted recurring payments using their banking application anytime, allowing them to instantly address payment issues and saving them time and energy.
This page provides UX recommendations and best practices, and technical implementation guidance to help clients develop an optimal user experience for cardholders.
An optimal user experience allows cardholders to
Recommendations, best practices and examples are illustrative only, non-comprehensive and any implementation requires client's independent legal and business analysis.
The below user experience diagram shows how clients can use VSM APIs to create an optimal user experience for their cardholders. It is recommended that clients provide cardholders with multiple paths to manage recurring payments within their mobile application.
This section provides UX and technical recommendations on building a mobile user experience that provides cardholders transparency and control over managing their subscription payments.
Stop payments for an active subscription/service/membership
View all screens seen in this user flow here
Technical Specifications and User Experience Recommendations corresponding to each screen shown in the prorotype is provided to help simplify implementation.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Tech Specs |
|
|
Account Home fields will be dynamically populated by issuers using internal data sources. | ||
Please review the VSPS API reference for sample API requests and responses | ||
UX Recommendations | ||
Use key customer touch points, such as the Welcome screen, to alert cardholders to new features available to manage their finances – e.g., use a “New Card Benefits” promo to introduce cardholders to VSPS. | ||
Provide cardholders an easy way to get more information about new services – e.g., link to a “Learn More” popup with more information about VSPS benefits to help drive enrollment. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Offer multiple entry points for cardholders to access account management tools.
Tech Specs | ||
Recent transactions are assumed to be available to the issuer internally. | ||
Please review the VSPS API reference for sample API requests and response | ||
UX Recommendations | ||
Offer multiple entry points for cardholders to access account management tools. | ||
If the Account Details screen is the cardholder’s first interaction with recurring payments, include a “Learn More” link to provide an easy way to get answers to their questions about the feature to encourage engagement. |
Tech Specs |
|
|
To distinguish between Active and Stopped payments, use |
||
|
To get a list COF merchants where the PAN is used for recurring or installment type payments, use URL: /cofds-web/v1/datainfo |
|
To get last payment date, use To get payment frequency, use |
||
Tip: Filter out stopped transactions (returned by the Search API) from the COF Data Service API to get a list of merchants to be displayed under the ‘Active’ section of the screen. If Search API does not return merchant name for a stop instruction, get the corresponding merchant name returned by the COF API for the same CAID. | ||
Please review the VSPS API reference for sample API requests and responses | ||
UX Recommendations | ||
“Learn more” aids cardholders in understanding how this feature can help them gain more visibility and control over their finances and encourage enrollment. | ||
Clearly communicate the status of subscriptions so cardholders can easily distinguish between active and stopped subscriptions. |
Tech Specs |
|
|
To get other recurring payments at the retailer, use URL:cofds-web/v1/datainfo/merchants Retreive the Merchant Reference Id (Field: mrchRef) from the and provide that as input (query parameter) in URL:cofds-web/v1/datainfo/merchants |
||
|
To get transaction amount, use |
|
To stop all recurring payments under a retailer, get merchant identifiers for each sub retailer URL: cofds-web/v1/datainfo/merchants Then call the Add merchant API to stop all recurring payments for the retailer. |
||
Please review the VSPS API reference for sample API requests and responses | ||
UX Recommendations | ||
Have clear call outs for any action that the user needs to take to manage their payments. | ||
Issuer could use any additional space on the page to display any merchant offers or benefits. Offer or benefit related info is not provided by VSM APIs. |
Tech Specs |
|
|
Merchant logos are to be sourced internally by the issuer. | ||
To get the payment status and determine if the payment is active / paused use URL: /vsps/search Include the PAN If the response doesn't include the transaction being displayed, then the status can be assumed to be 'active'. This API returns all transactions that have been stopped on a PAN. |
||
Please review the VSPS API reference for sample API requests and responses | ||
UX Recommendations | ||
Include a “Learn More” link to provide an easy way to get answers to their questions about each of the options. | ||
Clearly call out all all options available to the cardholder to manage payments. Also include additional information related to each of these options so cardholders clearly understand what each option will result in. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Tech Specs |
|
|
All legal and information text to be hosted internally by the issuer. | ||
To place a stop instruction (R1) use Ensure field "oneTimeStop" = False Use merchant identifiers returned by |
||
|
Tip: If PFID/SMID is avaialble in URL: /cofds-web/v1/datainfo it is best practice to create a stop instruction on the PFID+SMID. Note: Both PFID and SMID are required. IF PFID and SMID are not availabel, create stop instructions with both merchant name and CAID. | |
Please review the VSPS API reference for sample API requests and responses | ||
UX Recommendations | ||
Clearly communicate that stopping recurring charges will only stop future charges to set cardholder expectations about how the feature works and reduce inquiries to the call center and customer dissatisfaction. Ensure cardholders understand that they should contact the merchant first to ensure the service / subscription is canceled or their payment concerns are addressed. |
Tech Specs |
|
|
Once the Add Merchant API call is placed, a 200 or 400 response is returned along with stop instruction ID and details. A 200 response will also include the status of the request, which includes success (00), partial success (01) or fail (02). | ||
Please review the VSPS API reference for sample success and error responses. | ||
UX Recommendations | ||
Clearly communicate all settings associated with a stop to ensure cardholders understand and agree to the stop payment terms and reduce cardholder support inquiries. Create default stop settings for your organization. Providing too many customized options can overcomplicate the user flow and increase API calls if a cardholder sets a duration that is not long enough to block the recurring payment. |
||
Tip: The default stop payment is 13 months. A good rule of thumb is to set the stop payment duration for monthly payments to 6 months and for yearly payments to 13 months. | ||
Tip: Use the auto cancel and auto extend features to ensure better customer experience and cost reduction. |
|
Process Flow Description |
---|---|
1 |
Cardholder logs in to their banking application and selects the option to view subscription payments. |
2 |
Client triggers the VSM Merchant Aggregation API passing the PAN in the request. |
3 |
Visa responds with data of all merchants with card on file transactions in the with the last 13 month. |
4 |
Client displays the subscription payment data to the cardholder. |
5 |
Cardholder selects a particular transaction. |
6 |
Client triggers the VSM Merchant Details API. |
7 | Visa responds with last transaction details (including raw merchant name) for each merchant subscription. |
8 | Client displays the list of transactions to the cardholder on the banking application. |
9 | Cardholder chooses to pause or stop payments. |
10 | Client triggers the VSM Add Merchant API. |
11 | Visa processes the request and responds with the status of the request. |
12 | Client displays the status of the request on the banking application |
Pause payments for an active subscription/service/membership
View all screens seen in this user flow here
Technical Specifications and User Experience Recommendations corresponding to each screen shown in the prorotype is provided to help simplify implementation.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Tech Specs |
|
|
Account Home fields will be dynamically populated by issuers using internal data sources. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Use key customer touch points, such as the Welcome screen, to alert cardholders to new features available to manage their finances – e.g., use a “New Card Benefits” promo to introduce cardholders to VSPS. | ||
Provide cardholders an easy way to get more information about new services – e.g., link to a “Learn More” popup with more information about VSPS benefits to help drive enrollment. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Tech Specs |
|
|
Recent transactions are assumed to be available to the issuer internally. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Offer multiple entry points for cardholders to access account management tools. | ||
If the Account Details screen is the cardholder’s first interaction with recurring payments, include a “Learn More” link to provide an easy way to get answers to their questions about the feature to encourage engagement. |
Tech Specs |
|
|
To distinguish between Active and Paused payments, use |
||
|
To get a list COF merchants where the PAN is used for recurring or installment type payments, use URL: /cofds-web/v1/datainfo |
|
To get last payment date, use |
||
Tip: Filter out stopped transactions (returned by the Search API) from the COF Data Service API to get a list of merchants to be displayed under the ‘Active’ section of the screen. If Search API does not return merchant name for a stop instruction, get the corresponding merchant name returned by the COF API for the same CAID. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
“Learn more” aids cardholders in understanding how this feature can help them gain more visibility and control over their finances and encourage enrollment. | ||
Clearly communicate the status of subscriptions so cardholders can easily distinguish between active and stopped subscriptions. |
Tech Specs |
|
|
To get other recurring payments at the retailer, use
Retreive the Merchant Reference Id (Field: mrchRef) from the |
||
|
To get transaction amount, use
URL: cofds-web/v1/datainfo/merchants Field: lastTranAmtBillCurrency |
|
To stop all recurring payments under a retailer, get merchant identifiers for each sub retailer Then call the Add merchant API to stop all recurring payments for the retailer. |
||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Have clear call outs for any action that the user needs to take to manage their payments. | ||
|
Providing merchant contact information will encourage issuers to contact the merchant to report problems prior to stopping or pausing the payment. Issuer could use any additional space on the page to display any merchant offers or benefits. Offer or benefit related info is not provided by VSM APIs. |
Tech Specs |
|
|
Merchant logos are to be sourced internally by the issuer. | ||
To get the payment status and determine if the payment is active / paused use URL: /vsps/search Include the PAN If the response doesn't include the transaction being displayed, then the status can be assumed to be 'active'. This API returns all transactions that have been stopped on a PAN. |
||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Include a “Learn More” link to provide an easy way to get answers to their questions about each of the options. | ||
Clearly call out all all options available to the cardholder to manage payments. Also include additional information related to each of these options so cardholders clearly understand what each option will result in. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Tech Specs |
|
|
All legal and information text to be hosted internally by the issuer. | ||
To place a stop instruction (R1) use Ensure field "oneTimeStop" = True Use merchant identifiers returned by |
||
Tip: If PFID/SMID are available in URL: /cofds-web/v1/datainfo, it is best practice to create a stop instruction on the PFID+SMID. Note: Both PFID and SMID are required. IF PFID and SMID are not available, create stop instructions with both merchant name and CAID. | ||
valign="top"> Tip: Best practice to add stops on merchant and CAID if PFID/SMID are not available. |
||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Clearly communicate that stopping recurring charges will only stop future charges to set cardholder expectations about how the feature works and reduce inquiries to the call center and customer dissatisfaction. Ensure cardholders understand that they should contact the merchant first to ensure the service / subscription is canceled or their payment concerns are addressed. |
Tech Specs |
|
|
Once the Add Merchant API call is placed, a 200 or 400 response is returned along with stop instruction ID and details. A 200 response will also include the status of the request, which includes success (00), partial success (01) or fail (02). | ||
Please review the VSPS API reference for sample success and error responses. | ||
UX Recommendations | ||
Clearly communicate all settings associated with a stop to ensure cardholders understand and agree to the stop payment terms and reduce cardholder support inquiries. Create default stop settings for your organization. Providing too many customized options can overcomplicate the user flow and increase API calls if a cardholder sets a duration that is not long enough to block the recurring payment. |
||
Tip: The default stop payment is 13 months. A good rule of thumb is to set the stop payment duration for monthly payments to 6 months and for yearly payments to 13 months. | ||
Tip: Use the auto cancel and auto extend features to ensure better customer experience and cost reduction. |
# |
Process Flow Description |
---|---|
1 |
Cardholder logs in to their banking application and selects the option to view subscription payments. |
2 |
Client triggers the VSM Merchant Aggregation API passing the PAN in the request. |
3 |
Visa responds with data of all merchants with card on file transactions in the with the last 13 month. |
4 |
Client displays the subscription payment data to the cardholder. |
5 |
Cardholder selects a particular transaction. |
6 |
Client triggers the VSM Merchant Details API. |
7 | Visa responds with last transaction details (including raw merchant name) for each merchant subscription. |
8 | Client displays the list of transactions to the cardholder on the banking application. |
9 | Cardholder chooses to pause or stop payments. |
10 | Client triggers the VSM Add Merchant API. |
11 | Visa processes the request and responds with the status of the request. |
12 | Client displays the status of the request on the banking application |
Restart payments for stopped subscription
View all screens seen in this user flow here
Technical Specifications and User Experience Recommendations corresponding to each screen shown in the prototype is provided to help simplify implementation.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Tech Specs |
|
|
Account Home fields will be dynamically populated by issuers using internal data sources. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Use key customer touch points, such as the Welcome screen, to alert cardholders to new features available to manage their finances – e.g., use a “New Card Benefits” promo to introduce cardholders to VSPS. | ||
Provide cardholders an easy way to get more information about new services – e.g., link to a “Learn More” popup with more information about VSPS benefits to help drive enrollment. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Tech Specs |
|
|
Recent transactions are assumed to be available to the issuer internally. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Offer multiple entry points for cardholders to access account management tools. | ||
If the Account Details screen is the cardholder’s first interaction with recurring payments, include a “Learn More” link to provide an easy way to get answers to their questions about the feature to encourage engagement. |
Tech Specs |
|
|
To distinguish between Active and Stopped payments, use |
||
|
To get a list COF merchants where the PAN is used for recurring or installment type payments, use URL: /cofds-web/v1/datainfo |
|
To get last payment date, use
|
||
To get transaction amount, use |
||
Tip: If Search API does not return merchant name for a stop instruction, get the corresponding merchant name returned by the COF API for the same CAID. Remove any duplicates from results returned by the COF and Add merchant APIs. | ||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
“Learn more” aids cardholders in understanding how this feature can help them gain more visibility and control over their finances and encourage enrollment. | ||
Clearly communicate the status of subscriptions so cardholders can easily distinguish between active and stopped subscriptions. |
Tech Specs |
|
|
Merchant logos are to be sourced internally by the issuer. | ||
To get payment status, use Select all transactions returned in from the VSPS Search API with field "stopInstructionType": "MERCHANT" to get a list of stopped transactions. |
||
Please review the VSPS API reference for sample API requests and responses. | ||
UX Recommendations | ||
Include a “Learn More” link to provide an easy way to get answers to their questions about each of the options. | ||
Tip: Use clear, simple calls to action, such as “Learn More.” Link to the content vs. using a button so cardholders understand this isn’t a step they need to complete. |
Tech Specs |
|
||
All legal and information text to be hosted internally by the issuer. |
|||
To restart payment, first use to get the stop instruction ID from Then use to cancel the stop instruction using the stop instruction Id. |
|||
|
Tip: To ensure all linked instructions are stopped, retrieve merchant identifiers from and use that info to choose the stop instructions with corresponding merchant identifiers. URL: /cofds-web/v1/datainfo |
||
Please review the VSPS API reference for sample API requests and responses. | |||
UX Recommendations | |||
Clearly communicate that stopping recurring charges will only stop future charges to set cardholder expectations about how the feature works and reduce inquiries to the call center and customer dissatisfaction.
|
|||
|
Ensure cardholders understand that they should contact the merchant first to ensure the service / subscription is canceled or their payment concerns are addressed. |
Tech Specs |
|
|
Once the Cancel API call is placed, a 200 or 400 response is returned along with stop instruction ID and details. A 200 response will also include the status of the request, which includes success (00), partial success (01) or fail (02). A 400 response will include an error code along with the reason for failure. | ||
Please review the VSPS API reference for sample success and error messages. | ||
UX Recommendations | ||
Clearly communicate that it may require interactions between the merchant and cardholder to have the service reactivated. The issuer will not work with the retailer to handle any contracts or terms with the retailer. |
Additional Recommendation |
|
|
Capture customer behavior patterns to make sure cardholders are not misusing the service to get out of payment obligations. |
# |
Process Flow Description |
---|---|
1 |
Cardholder logs in to their issuer mobile app and selects the option to view stopped subscription payments. |
2 |
Issuer triggers the VSM Search API passing the PAN in the request. |
3 |
Visa VSM Search API responds with information on stop instructions and associated details. |
4 |
Issuer displays a list of merchants with stopped subscription payments. |
5 |
Cardholder selects a particular merchant. |
6 |
Issuer displays merchant related details and the option to restart payment. |
7 | Cardholder chooses to restart the payment. |
8 | Issuer triggers the VSM Cancel API. |
9 | Visa processes the request and responds with the status of the request. |
10 | Issuer displays the status of the request to through the banking application. |
This section covers additional use cases on top of the core end- to- end experiences. Refer to the Stop, Pause ad Restart Payment sections above for API interactions, UX recommendations and technical requirements.
Stopping all recurring payments at a retailer
Issuers can opt to provide additional types of experiences that allow cardholders to stop payments for all subscriptions under a merchant. For example, a cardholder may have subscription at merchants like Amazon that provide multiple subscritpions like Amazon Prime, Kindle or Prime Video, and may wish to cancel all Amamzon subscription together.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Restarting all stopped recurring payments at a retailer
The following screens show how issuers can allow cardholders to restart all subscription payments that they previosuly cancelled for a retailer. For example, a cardholder may want to restart all their subscriptions provided by Lot Plus. The services they would like to restart could be their streaming service, gaming service and music service provided by Lot Plus.
Stopping a particular subscription payment under a wallet
The following screens show how issuers can allow cardholders to stop a particular subscription payment setup under a wallet. For example, a cardholder may be using a wallet like Paypal to pay for multiple subscriptions, and may want to cancel one of those subscriptions.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Informational Messaging
The following user experience screens contain messaging to communicate the value of Subscription Manager and how it works. It is important to build awareness and understanding of subscription management capabilties available within the issuer's mobile application. Issuers can provide additional information about the service using a “Learn More” overlay. You can also include information on how it works on the “Recurring Payment Details” screen to help cardholders understand how to pause / stop a recurring payment, or restart a stopped payment. Additionally, this may also help increase cardholder satisfaction and engagement, and reduce the issuer’s cardholder support volume. All informational messaging will be owned and internally hosted by the issuer.
All user flows and messaging shown are for illustrative purposes only. They are not comprehensive and do not constitute legal or marketing advice or replace participant's own analysis.
Displaying recurring payments
Creating stop instructions with precision
The number of unwanted transactions stopped depends on the quality of transaction data, specifically merchant details, and stop instructions placed. Follow these best practices to
create stop instructions that can help you optimize performance and cost.
Display subscription payments only
This helps prevent cardholders from blocking single payments, which increases issuer costs and can cause acceptance problems for the merchant/cardholder.
Benefit from cost-control features
Visa does not provide legal, regulatory, tax or financial advice. Each client is fully responsible for ensuring that its program operates in compliance with applicable legal and regulatory requirements and is responsible for conducting independent legal and regulatory reviews through its legal counsel. The best practices, recommendations and sample user interfaces herein, including any sample legal language therein, are provided for informational purposes, non-comprehensive, illustrative and provided for reference only. They are neither mandatory, nor should they be relied upon for marketing, legal, regulatory or other advice. Each client needs to conduct its own independent analysis in light of its specific business needs and any applicable laws and regulations. Visa is not responsible for your use of any of the information herein, including errors of any kind.
Benefits are illustrative only and depend on implementation details and business factors.
Without limiting any other VSPS requirement as set forth in the Visa Rules, usage of VSPS does not remove any obligation of the cardholder to meet payment terms or any other agreement with the merchant, including but not limited to informing the merchant the cardholder wishes to cancel the respective service. Clients that wish to use third party services in order to provide cancellation services to their cardholders do so at their own risk. Visa does not have insight into the operations of such third party providers and disclaims any and all liability or responsibility in that regard. |