Recurring payments

Merchants can collect payments from customers on a regular basis without customers initiating a new payment each time. In this guide, we’ll discuss how to use Moov’s API to implement recurring payments and ensure successful transactions.

Card schemes

To use recurring payments effectively, it’s important to understand the card scheme rules that govern them. Moov ensures these mandates are met if transfers are properly identified. Use the create a transfer POST endpoint to pass the necessary information to the transactionSource field located in source.cardDetails.

transactionSource Description
first-recurring Indicates when a cardholder initiates the first in a series of recurring transactions, or if the card is being saved to 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

Set up initial transaction

Use the first-recurring option when the cardholder is setting up the subscription for the first time. This step is crucial to ensure that the card issuer has the correct information about subsequent transactions. Creating a recurring or unscheduled transaction without an existing first-recurring will result in a failure. If your payment flow upsells a subscription, you can default to first-recurring 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}

Set up subsequent transactions

After the initial first-recurring transaction has completed, you can create a second request with the recurring option for subsequent transactions that are part of the recurring series. Failing to use the recurring option may result in a declined transaction.

An additional option after setting up a first-recurring transaction is creating unscheduled merchant-initiated transactions using the unscheduled option. The unscheduled option is useful when a customer needs to make an additional payment outside of the regular recurring schedule.