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.