Wallet Implementation Guide

Overview

This guide will provide detailed instructions on how to implement Wallet with your site. There are a few key actions to be sure to take, as well things to avoid. This guide will walk you through the following actions:

• Setting a primary payment method on an account.
• Adding additional payment methods.
• Using a specific payment method on a subscription or purchase.
• Updating a subscription to use a specific payment method.
• Managing payment methods on an account.
• Updating specific payment methods on the account.

Also reference the Wallet documentation.

👍

Go Live Checklist

Before going live with the Wallet feature on your Recurly site, test through all scenarios to ensure your integration will be successful. It is recommended that you test your integration in a Sandbox site before going live in PROD with Wallet.

Additional documentation should be referenced with the Product Documentation (link), paired with the API Documentation (link).

Definitions

1. 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.
2. Payment method: the funding source for making transactions. Such as credit or debit cards, bank account, PayPal.
3. 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 payment method is specified.

Setting a primary payment method on an account

📘

Primary Payment Method

The first payment method added to the account will be marked as the primary payment method. This can be accomplished by noting this in the initial request, but is not required.

Subsequent payment methods that are added to the account can be marked as primary during creation. Existing payment methods can be updated to become primary at any time by setting the primary indicator on that payment method.

Adding additional payment methods

After the primary payment method is added to the account, additional payment methods can be added, up to 20 per account. These additional payment methods can be tied to specific subscriptions on an account.

When adding additional payment methods on an account, a specific billing_info_id will be returned in the response. This value can be used for subsequent requests to create a subscription that will be tied for recurring subscription payments.

New payment methods that are added to an account have the option to be set as primary. Be sure to pass in the correct flag for subsequent payment methods (true or false), with new payment methods. If the new payment method is meant to be primary, pass true. If the new payment method is mean to be a non-primary payment method, pass false.

📘

Primary Payment Method

Remember, the first payment method added to the account will be marked as the primary payment method.

When adding additional payment methods, if neither true nor false is passed in the request, then the payment method will be added as non-primary.

Using a specific payment method on a subscription or purchase

Once a payment method has been created on an account, it can be added to the subscription. Complete a GET request to the accounts/billing_infos endpoint for the specific payment methods that are on an account, to then be set on a subscription.

To create a subscription or a purchase using a specific payment method, simply pass the billing_info_id with the request. This will use the specified payment method for the transaction, or set the billing_info_id on subscription for future billing.

Within a single purchase, only one payment method can be assigned, so everything in a single purchase request will be billed to the payment method provided.

👍

Example Use Case

A customer would like one-time purchases billed to one payment method and subscriptions billed to a different payment method.

1. Create the primary payment on the account by adding the initial payment method.
2. Add a second payment method on the account which will be non-primary.
3. When creating the subscription, assign the non-primary payment method to the subscription, which will renew using that payment method.
4. When creating one-time purchases do not assign or pass in a payment method, so that the purchase will default to the primary payment method on the account. This will simplify subsequent one-time purchase requests as the billing_info_id will not need to be provided.

Note: Each integration is different, and a payment method can be assigned to one-time purchases while subscriptions default the primary.

Setting a specific payment method on a subscription

Once a payment method has been created on an account, it can be added to a subscription. To set a payment method on a subscription, pass in the payment method id as a PUT request to the subscription.

To create the payment method along with a subscription or purchase, pass in the new billing information with the request.

👍

Default to Primary

The primary payment method can be used as a default for subscriptions or purchases that do not have a payment method specified.

📘

Payment Method and Subscriptions

Wallet is a flexible solution that allows the customer to manage the payment methods on an account and bill recurring subscription charges using specific payment methods.

• If the new payment method is the first on the account, it will be added as primary payment method on the account.
• Subscriptions can be set to default to the primary payment method by not setting a billing_info_id. In this scenario, if a new payment method is added and made primary, subscriptions without a billing_info_id set on it will default to the new primary payment method.
• Subscriptions can be set to use a specific non-primary payment method by setting a specific billing_info_id.
• Subscriptions can use a specific payment method by setting a billing_info_id, which can be the billing_info_id of the current primary payment method. In this scenario, if the primary payment method changes on the account, the subscription will continue to use the specific payment method that was previously the primary on the account.
• Subscriptions that once had a specific billing_info_id set, and that payment method is subsequently deleted, will default to use the primary payment method.
• If all payment methods on an an account are deleted and there are active subscriptions, the subscriptions will expire if there is not a new payment method added to the account.

Managing payment methods on an account

For new merchants integrating with Recurly and Wallet, use the /accounts/billing_infos endpoints should be used to return all the payment methods from the account. Existing merchants who are already integrated with Recurly will need to begin using the new /accounts/billing_infos endpoints to manage multiple payment methods on an account.

The existing GET /accounts/billing_info endpoint will only return the primary payment method from an account. The new GET /accounts/billing_infos endpoints will return all the payment methods on the account.

The new endpoints will allow you to display all the payment methods on an account to your customers so they can manage their payment methods on their account and subscriptions.

🚧

Managing Payment Methods

Note: do not pass in the same billing info details repeatedly for the same account when creating subscriptions, or one-time purchases. This will create the same payment method multiple times on the account. Once 20 payment methods on an account are reached you will begin to receive an error message.

Instead: only add unique billing info details one time on an account and reference the billing_info_id for subsequent purchases or subscriptions.

Updating specific payment methods on the account

To update a specific payment method on an account, you will need to pass in the ID of the payment method to make a change. Use a PUT to /accounts/billing_infos/<billing_info_id> to make an update to the information of a specific payment method, such as card or account number, address information, etc.

This endpoint will also allow you to change the primary payment method on an account. A PUT request to /accounts/billing_infos/<billing_info_id> that includes primary_payment_method=true will update the specific payment method to primary. This action will also make the previous primary payment method a non-primary payment method.

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.