Recurring payments

In this guide, we’ll introduce card schemes and discuss how to implement recurring payments with Moov’s API.

Recurring payments allow merchants to collect from customers on a regular basis, without customers initiating a new payment each time. To set up recurring payments, you’ll need to set up an initial payment before establishing a recurring schedule. You also have the ability to set up unscheduled payments, which occur outside the set schedule.

1. Understand card schemes

To use recurring payments, it’s important to understand card scheme rules. Card brands mandate certain information be stored to facilitate recurring payments, and Moov ensures these mandates are met if transfers include the appropriate card scheme.

transactionSource	Description
first-recurring	Indicates when a cardholder initiates the first in a series of recurring transactions, or if the card is being saved for subsequent unscheduled charges initiated by the merchant
recurring	Indicates subsequent recurring transactions initiated by the merchant on a regular schedule
unscheduled	Indicates a subsequent transaction that occurs on an irregular basis, such as an account top-up

2. Set up card account updater

Card account updater is optional, but ensures there’s no disruption to processing recurring payments if card details change. Card account updater automatically receives updates when a user changes card information on file, like expiration date. To set up card account updater, link a card to an account and save it for future use by setting cardOnFile to true and setting the merchantAccountID. The account associated with merchantAccountID will be billed for successful card updates.

Accounts must be approved to use Moov’s card account updater. Reach out to your relationship manager, or contact support and select submit a support ticket for payment acceptance issues to request access.

 1{
 2  "cardNumber": "string",
 3  "expiration": {
 4    "month": "01",
 5    "year": "28"
 6  },
 7  "cardCvv": "0123",
 8  "holderName": "Jules Jackson",
 9  "billingAddress": {
10    "addressLine1": "123 Main Street",
11    "addressLine2": "Apt 302",
12    "city": "Boulder",
13    "stateOrProvince": "CO",
14    "postalCode": "80301",
15    "country": "US"
16  },
17  "cardOnFile": true,
18  "merchantAccountID": "50469144-f859-46dc-bdbd-9587c2fa7b42"
19}

3. Set up initial payment

Set up a payment schedule in your app, and initiate the first payment with the transfer POST endpoint. Set the transactionSource, located in source.cardDetails, to the first-recurring card scheme. This step is crucial to ensure the card issuer has the correct information about subsequent payments.

Creating a recurring or unscheduled payment without an existing first-recurring payment will result in a failure. If you handle subscription changes, like upsells, you can default to first-recurring for the upsell payment in order to be safe.

 1{
 2  "amount": {
 3    "value": 5000,
 4    "currency": "USD"
 5  },
 6  "source": {
 7    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
 8    "cardDetails": {
 9      "dynamicDescriptor": "WhlBdy Monthly",
10      "transactionSource": "first-recurring"
11    },
12    "destination": {}
13  }
14}

4. Set up recurring payments

After the initial first-recurring payment has completed, create a second request using the transfer POST endpoint. Set the transactionSource to the recurring card scheme. This sets up a payment method for a recurring series of payments. Failing to use the recurring option may result in a declined transaction.

After the first recurring payment, another option is to create unscheduled, merchant-initiated payments. This is done by setting transactionSource to unscheduled. The unscheduled option is useful when a cardholder needs to make an additional payment outside of the regular recurring schedule.

 1{
 2  "amount": {
 3    "value": 5000,
 4    "currency": "USD"
 5  },
 6  "source": {
 7    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
 8    "cardDetails": {
 9      "dynamicDescriptor": "WhlBdy Monthly",
10      "transactionSource": "recurring"
11    },
12    "destination": {}
13  }
14}

 1{
 2  "amount": {
 3    "value": 5000,
 4    "currency": "USD"
 5  },
 6  "source": {
 7    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
 8    "cardDetails": {
 9      "dynamicDescriptor": "WhlBdy Monthly",
10      "transactionSource": "unscheduled"
11    },
12    "destination": {}
13  }
14}

1. Understand card schemes

2. Set up card account updater

3. Set up initial payment

4. Set up recurring payments

Was this helpful?