👍
Customer Benefit
Wallet creates payment flexibility for merchants' customers by allowing subscribers to assign subscriptions to different payment methods or for specific one time transactions. Customers can utilize a primary payment method as the default for subscriptions or one-time transactions.

Wallet Feature Documentation

These docs are intended to be used in conjunction with the API documentation.

Also reference the Wallet Implementation Guide.

Learn more about Backup Payment Methods.

Wallet Functional Use Cases

Add multiple payment methods to each customer account.
Assign a “Primary” billing info (payment method) on an account that can be used by default when a billing info is not assigned to a subscription or for a one-time purchase.
Assign a specific billing info to each subscription on an account.
Assign a specific billing info to be used for one-time purchases.
Assign and use a billing info as a backup when the billing info fails on a subscription renewal (learn more)

Prerequisites and Table Stakes

Merchants must have the following features enabled: Credit Invoices and Only Bill What Changed.
Merchants must be using the latest version of API V3 version 2020-10-10 or later, or API V2 2.29 or later to utilize the Wallet feature.
This feature must be added to your Recurly contract (see pricing and availability) in order to be enabled on your site. Please reach out to your Customer Success Manager or support ([email protected]) to have Wallet enabled.

Managing Billing Infos

Definitions

Billing info: the set of information regarding a specific payment method, including data such as address, card number, IP address. Each billing info will be tied to the unique billing address provided.
Payment method: the funding source for making transactions. Such as credit or debit cards, bank account, PayPal.
Primary Payment method: the first payment method on an account, or one that is set as primary, which will be used as default when no other billing info is specified.

Endpoint support for billing infos

When creating a billing info through the following endpoints, /accounts/billing_infos, /purchases, /subscriptions, the first billing info on the account will be added as the primary billing info.
If a primary_payment_method value is passed in, it will be ignored (whether true or false) if the billing info is the first billing info added to the account.
/accounts endpoint:
Allows creating a new account with new billing info.
Allows updating a billing info on an account, but will only update the primary billing info on the account (PUT).
/accounts/billing_infos endpoint:
Allows adding new billing info to the account.
Allows editing existing billing infos with billing_info_id.
Allows setting new primary billing info on the account with primary_payment_method.
/purchases endpoint:
Allows adding new billing info to the account while creating a purchase.
Allows setting new primary billing info on the account by sending primary_payment_method with new billing info, when there is an existing billing info on the account.
/subscriptions endpoints:
Allows setting a specific billing info on a subscription.

Additionally, billing info can be updated during a purchase or subscription create request using the /purchases or /subscriptions endpoints for accounts with existing billing infos. When updating a billing info during a one of these requests, follow these guidelines:

primary_payment_method is true, the existing primary billing info will be updated
primary_payment_method is false, create a new non-primary billing info
primary_payment_method is not included, the existing primary billing info will be updated

This is helpful when a customer wants to update some of the information associated with the billing info (example: billing address) but not the full billing info such as a credit card number.

📘
Adding multiple billing infos
Provide flexibility to your customers by allowing them to store multiple payment methods on their account.

The first billing info added will be the primary payment method on the account, which can be used as the default for transactions.

Customers can add additional billing infos on their account, and change one of the new billing infos to be set as the primary payment method.

Accounts

When creating an account including a billing info, the new billing info will become the primary billing info on the account.
Each billing info will have a specific billing_info_id returned in the response that can be used on certain actions for subscriptions or one-time purchases.
New billing infos, which can include primary_payment_method, can be added to an account.
Including primary_payment_method as true will set the new billing info as primary on the account.
Including primary_payment_method as false, or omitting this parameter, will simply add the new billing info to the account.
GET /accounts/billing_infos will return an array of billing infos on the requested account, noting which billing info is marked as primary.
When creating billing infos on an account, the response will include the billing info ID.
Accounts can have a max of 20 billing infos.

Subscriptions

Subscriptions will default to using the primary billing info, when a specific billing info is not set.
Subscription renewals will use whatever billing info is set as primary on the account.
Subscriptions can be set to use a billing info, which is the primary, by adding the billing_info_id of the primary billing info on the subscription. If the primary billing info changes, the subscription will continue to use the specified billing info.
Subscriptions can be set to use a billing info, which is NOT the primary.
To set a specific billing info to be used on a subscription pass the specific billing_info_id (returned in the API response). In order to do this, you will need to save the billing_info_id, or GET billing infos to determine the needed billing_info_id.
If a subscription has a billing info specified, the subscription will use that billing info for recurring charges.
If a subscription had a billing info specified, and that billing info is deleted, the subscription will begin using the primary billing info on the account for recurring charges, until a different billing info is specified.

📘
Changing Billing Info on a Subscription
Example use case - if you want to change the billing info on a subscription, follow these steps:

Create new billing info via the /accounts/billing_infos endpoint.

PUT to /subscriptions endpoint to change billing info on the subscription.

Invoices

Invoices created via API will use the billing info included in the request or the specified billing_info_id. If no billing info is provided, the primary billing info on the account will be used.
Past due invoices can be edited via API, to have the associated billing info updated when attempting collection (force collect).
Unpaid / past due invoices will be billed against the primary payment method unless a specific payment method is has been set on the invoice.
If a billing info is updated, an attempt will be made to collect all unpaid invoices that bill to the billing info.

Deleting Billing Infos

Merchants are able to delete a customer's non-primary billing infos that are stored on the account.
When there is only one billing info on the account, which is marked as primary, the billing info can be deleted.
In order to delete a primary billing info, when there are multiple billing infos on the account, a new primary must be set, and then the previous primary may be deleted.
Note: Subscriptions or invoices that are tied to the deleted billing info will use the primary billing info for subsequent recurring charges or retry attempts, unless a new billing info is specified.

Manual Collection Method

Subscriptions or invoices that are set to Automatic Collection Method will default to the primary billing info unless otherwise specified.
Subscriptions or invoices that are set to Manual Collection Method do not require a billing info.
When a subscription is moved from Automatic Collection Method to Manual Collection Method, any assigned billing info will be cleared from the subscription.

Recurly App Admin UI

Wallet is supported in the Recurly admin console, with a read only view at this time. Additional support for other Wallet actions in progress and will be rolled out when available.
Payment methods supported in the UI include:
Credit Cards: Visa, MasterCard, Amex, Discover, JCB, Diners Club (create and edit)
Payment Wallets: Amazon Pay, PayPal, Apple Pay (view and limited edit)
ACH Bank Payments

Exports

Wallet is supported in the Accounts Export and the billing_info Export:

Accounts Export added or updated the following fields to VERSION 4 - 12/10/20:

tax_location_valid column will populate off each the specific billing info in each row
Added new columns to the end of the export, but BEFORE any custom field columns:
Added new primary_payment_method column, which will display TRUE or FALSE based on if the billing info is the primary payment method
Added new billing_info_id will display the ID of the billing info

billing_info Export added the following fields to VERSION 5 - 12/3/20:

Added new primary_payment_method column, which will display TRUE or FALSE based on if the billing info is the primary payment method
Added new billing_info_id will display the ID of the billing info

Hosted Pages

Recurly’s hosted pages will return the primary billing info only for management.
Non-primary billing info will not be editable via Hosted Account Management pages at this time.

Payment Gateway & Account Updater Support

Payment routing functionality is compatible with Wallet, including:
Custom Gateway Routing (info).
Gateway Failover (info).
Account Updater (info).

Wallet & Account Hierarchy Feature Support

Wallet is integrated with Account Hierarchy, including Invoice roll-up.

Supported Use Cases

Child billing self
- Can bill using primary payment method
- Can bill using specific payment method
- Backup payment method from child billing self will be used when an invoice fails
Parent billing self
- Can bill using primary payment method
- Can bill using specific payment method
- Backup payment method from child billing self will be used when an invoice fails
Child billing parent
- Can bill using primary billing info from parent account
- Can bill using specific billing info from parent account
- Backup payment method from parent account will be used when an invoice fails
Aggregate invoices will combine when invoices from single child account when invoices are set to use the same billing info on parent account
- Can be set to use primary, or specific billing info on parent account
- Invoice Roll-up will combine invoices from multiple child accounts when invoices are set to use the same billing info on parent account
- Can be set to use primary, or specific billing info on parent account

Additional Notes

When changing the bill_to account, all invoices must be paid (current functionality)
When changing the bill_to account, subscriptions will use the primary payment method from the new bill_to account until a new / different payment method is specified.
When changing the bill_to for an account, any previous billing_info_id that was set on a subscription will be cleared. If the account changes the bill_to again, subscriptions will default to the primary billing info for the bill_to account until a new billing_info_id is set.
Any uninvoiced charges will be picked up on the next invoice created and use the associated payment method

Other Recurly Feature Support

Wallet is integrated with the Calendar Billing feature. Subscriptions that are set to Align or Aggregate onto the same invoice will do so when they share the same payment method.
When a subscription or downgrade request is made, and the site setting to require all invoices to be successfully paid, a collection attempt on each invoice will be made, regardless of the associate payment method.

Additional Notes

Wallet will work with all payment methods that Recurly supports.
Refunds will be made back to the original payment method used for the transaction.
If a customer wants to change a billing info for the next recurring charge, the billing info needs to be updated before the next recurring charge occurs.
If a customer wants to change a billing info for an "immediate change" to a subscription, the billing info needs to be updated before the change is made.
Recurly's email templates will only return / include the primary billing info.
3rd party integrations such as NetSuite, SalesForce and Zendesk will only display the primary payment method and details, if the primary payment method is a credit card.
Ability to list site’s accounts (GET /accounts) will return back accounts and the primary billing info only.
Recurly's fraud limits apply at the account level and not at the billing info level.
Wallet is supported in conjunction with 3DS flows, in accordance with the PSD2 mandate. Transaction challenges will be tied to the specific billing info that was initially attempted.
Wallet is not compatible with the following features: Auth and Capture, Adyen HPP, Verify Billing Info Endpoint.

Pricing and Availability

There are additional fees to use Wallet. Please reach out to your Account Manager, Account Executive or contact Recurly Support to learn more.