Recurring Merchant Billing

Learn how to set up recurring charges against sellers.

With Recurring Merchant Billing, Platforms can automatically charge their Merchants on a fixed billing plan. Recurring Merchant Billing can be used to charge a Fee to a Merchant for a service, good, or any other use case.

You can create Subscriptions to charge your Merchants using the Finix Dashboard or the Finix API.

There are three steps to create a recurring billing plan (called a Subscription in Finix) and apply it to a Merchant :

Create a subscription schedule that dictates the cadence of fees.
Create a subscription amount for the schedule.
Enroll the merchant to a subscription.

info

If you have any questions about Recurring Merchant Billing, please reach out to the Finix Support team.

Step 1: Create a Subscription Schedule

The Subscription Schedule details when the Subscription Fee is charged to the Merchant . When creating a Subscription Schedule, there are two schedules available forsubscription_type:

FIXED_TIME_INTERVAL
PERIODIC

FIXED_TIME_INTERVAL

The FIXED_TIME_INTERVAL Subscription Schedule charges a Merchant on a fixed hourly interval. For example, if a Merchant purchases a POS for $100, you can set a FIXED_TIME_INTERVAL schedule to charge the Merchant $25 four times until the $100 is paid.

To charge a Fee every day for 4 days, pass 24 in the hourly_interval field and 4 in the interval_count field. There is no limit to the number of intervals you can include in interval_count.

Example Create FIXED_TIME_INTERVAL

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "fixed_time_interval_offset": {
	        "interval_count": 4,
	        "hourly_interval": 24
	    },
	    "line_item_type": "FEE",
	    "nickname": "Fixed_Time_Subscription_Schedule",
	    "subscription_type": "FIXED_TIME_INTERVAL"
	}'

Response:

Copy

Copied

{
  "id" : "SUBSCHEDULE_dKsos3dXZ1Wf1spQPHZcaa",
  "created_at" : "2022-10-10T04:24:17.00Z",
  "updated_at" : "2022-10-10T04:24:17.00Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fixed_time_interval_offset" : {
    "hourly_interval" : 24,
    "interval_count" : 4
  },
  "line_item_type" : "FEE",
  "nickname" : "Fixed_Time_Subscription_Schedule",
  "period_offset" : null,
  "subscription_type" : "FIXED_TIME_INTERVAL",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_dKsos3dXZ1Wf1spQPHZcaa"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_dKsos3dXZ1Wf1spQPHZcaa/subscription_amounts"
    }
  }
}

PERIODIC

The PERIODIC Subscription Schedule charges a Merchant on a specific day. Examples include a monthly software Fee or an annual PCI compliance Fee to be charged monthly or annually. There are two PERIODIC Subscription Schedules you can charge:

PERIODIC_YEARLY: The Subscription Schedule charges a Merchant a Fee once a year on a specific day and month. If you pass in a day that does not exist, such as 2/31 or 11/30 in the day field, an error will return.
PERIODIC_MONTHLY: The Subscription Schedule charges a Merchant a Fee once a month on a specific day. The month field should not be passed in the payload, or the request will return an error.
- If you pass in 31 to represent the last day of a month, for every month that does not have 31 days, the Fee will be charged on the last day of the month. For example, Fees for February would be charged on the 28th, September on the 30th, and etc. This also applies to leap years.

Example PERIODIC_MONTHLY

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "line_item_type": "FEE",
	    "nickname": "Monthly_Subscription_Schedule",
	    "period_offset": {
	        "day": 1,
	        "month": null
	    },
	    "subscription_type": "PERIODIC_MONTHLY"
	}'

Response:

Copy

Copied

{
  "id" : "SUBSCHEDULE_iLPPNko32TDK3kdfs4Mbxy",
  "created_at" : "2022-10-10T04:25:25.25Z",
  "updated_at" : "2022-10-10T04:25:25.25Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fixed_time_interval_offset" : null,
  "line_item_type" : "FEE",
  "nickname" : "Monthly_Subscription_Schedule",
  "period_offset" : {
    "day" : 1,
    "month" : null
  },
  "subscription_type" : "PERIODIC_MONTHLY",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_iLPPNko32TDK3kdfs4Mbxy"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_iLPPNko32TDK3kdfs4Mbxy/subscription_amounts"
    }
  }
}

Example PERIODIC_YEARLY

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "line_item_type": "FEE",
	    "nickname": "Yearly_Subscription_Schedule",
	    "period_offset": {
	        "day": 5,
	        "month": 1
	    },
	    "subscription_type": "PERIODIC_YEARLY"
	}'

Example Response:

Copy

Copied

{
  "id" : "SUBSCHEDULE_nQUWWDVbG9imyPw7JMUucC",
  "created_at" : "2022-10-10T04:26:20.55Z",
  "updated_at" : "2022-10-10T04:26:20.55Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fixed_time_interval_offset" : null,
  "line_item_type" : "FEE",
  "nickname" : "Yearly_Subscription_Schedule",
  "period_offset" : {
    "day" : 5,
    "month" : 1
  },
  "subscription_type" : "PERIODIC_YEARLY",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_nQUWWDVbG9imyPw7JMUucC"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_nQUWWDVbG9imyPw7JMUucC/subscription_amounts"
    }
  }
}

To create the schedule, specify and subscription_type and corresponding schedule information.

For this example, this is creating a FIXEDTIMEINTERVAL to charge once a week for a year:

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "fixed_time_interval_offset": {
	        "interval_count": 52,
	        "hourly_interval": 168
	    },
	    "line_item_type": "FEE",
	    "nickname": "Fixed_Time_Subscription_Schedule",
	    "subscription_type": "FIXED_TIME_INTERVAL"
	}'

A successful response returns a 201 and the subscription schedule.

Copy

Copied

{
  "id" : "SUBSCHEDULE_rRawohVCr1rrF2DVpLm8Qp",
  "created_at" : "2022-10-10T04:27:14.96Z",
  "updated_at" : "2022-10-10T04:27:14.96Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fixed_time_interval_offset" : {
    "hourly_interval" : 168,
    "interval_count" : 52
  },
  "line_item_type" : "FEE",
  "nickname" : "Fixed_Time_Subscription_Schedule",
  "period_offset" : null,
  "subscription_type" : "FIXED_TIME_INTERVAL",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_rRawohVCr1rrF2DVpLm8Qp"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_rRawohVCr1rrF2DVpLm8Qp/subscription_amounts"
    }
  }
}

Step 2: Create a Subscription Amount

The next step is to create and associate a Subscription Amount to a Subscription Schedule. The Subscription Amount is the amount to be charged to a Merchant . To associate a Subscription Amount with a Subscription Schedule pass FEE in the amount_type field of the request. You can associate up to 25 amounts to a schedule. To add an additional Subscription Amount to a schedule, make a new Subscription Amount request with the Subscription Schedule ID.

If you add another Subscription Amount to a schedule, all Merchants enrolled in that schedule will be charged the additional amount when the enrollment is triggered. For example, if your schedule charges a monthly software license fee of $10, and you add another monthly $10 reporting fee, all Merchants enrolled in this schedule will be charged $20 per month once the enrollment is triggered.

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts  \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "amount_type": "FEE",
	    "fee_amount_data": {
	        "amount": 2500,
	        "currency": "USD",
	        "label": "POS_INSTALLMENT_FEE"
	    },
	    "nickname": "POS_INSTALLMENT_FEE",
	    "tags": {
	        "order_number": "124"
	    }
	}'

A successful response returns 201 and the Subscription Amount.

Copy

Copied

{
  "id" : "SUBAMOUNT_bym9JVzQA5n8eKUCvDvNwf",
  "created_at" : "2022-06-24T17:44:44.90Z",
  "updated_at" : "2022-06-24T17:44:44.90Z",
  "amount_type" : "FEE",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fee_amount_data" : {
    "amount" : 1266,
    "currency" : "USD",
    "label" : "POS_INSTALLMENT_FEE"
  },
  "nickname" : "finix",
  "subscription_schedule" : "SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ",
  "tags" : {
    "keysssssss" : "key_example"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts/SUBAMOUNT_bym9JVzQA5n8eKUCvDvNwf"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ"
    }
  }
}

Step 3: Create a Subscription Enrollment and Enroll the Merchant

A Subscription Enrollment details which Merchant gets charged, to what schedule, and when the subscription will start. The Subscription Enrollment must be associated with a Subscription Schedule.

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_enrollments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "merchant": "MUucec6fHeaWo3VHYoSkUySM",
	    "nickname": "Security Fee",
	    "started_at": "2022-11-11T16:50:59.891Z",
	    "tags": {
	        "enrollment_info": "Security Fee Enrollment"
	    }
	}'

Example Response:

Copy

Copied

{
  "id" : "SUBENROLLMENT_nRZCWcrB5podxxmM7q5PCM",
  "created_at" : "2022-10-10T04:33:30.30Z",
  "updated_at" : "2022-10-10T04:33:30.30Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "ended_at" : null,
  "merchant" : "MUucec6fHeaWo3VHYoSkUySM",
  "nickname" : "Security Fee",
  "started_at" : "2022-11-11T16:50:59.89Z",
  "subscription_schedule" : "SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ",
  "tags" : {
    "enrollment_info" : "Security Fee Enrollment"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_enrollments/SUBENROLLMENT_nRZCWcrB5podxxmM7q5PCM"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts"
    }
  }
}

The merchant is now set to be billed per the schedule, amount, and enrollment.

You can delete the enrollment to stop the recurring billing of the Merchant .