Sign in

v1

latestOpenAPI 3.0.02026-07-26280204.9 KB
Recurring Payin

Create Recurring Payin

Recurring Payin is a method for setting up automated, recurring payments from customers. This allows merchants to collect funds on a scheduled basis without requiring manual intervention for each payment.

Recurring Payins are useful for:

  • Subscription Services: Monthly or yearly subscription payments
  • Membership Fees: Recurring membership or service fees
  • Utility Bills: Automated bill payments

Key Features

  • Flexible Scheduling: Support for WEEKLY, MONTHLY, QUARTERLY, and YEARLY frequencies
  • Auto Debit: Automatic payment processing without customer intervention
  • Fixed or Variable Amounts: Support for both fixed recurring amounts and variable amounts
  • Payment Plans: Integration with existing payment plans or standalone recurring payments
  • Activation Delays: Configurable delays before the first payment is processed

Prerequisites

Before creating a Recurring Payin, ensure you have:

  1. Customer Created: The customer must exist in the system (optional but recommended)
  2. Payin Method: A valid payin method ID for the payment type
  3. Payment Plan (Optional): If using an existing payment plan, ensure it's properly configured

Recurring Payin Types

  • With Payment Plan: Uses an existing payment plan configuration
  • Standalone: Creates a new recurring payment configuration without a payment plan

Status Flow

  • CREATED: Initial status when recurring payin is created
  • ACTIVE: When the recurring payin is active and processing payments
  • CANCELLED: Permanently cancelled recurring payments
  • COMPLETED: When all scheduled payments have been completed

Webhook Notifications

Finmo will send webhook notifications for recurring payin events:

  • RecurringPayin_CREATED: When a recurring payin is created
  • RecurringPayin_ACTIVATED: When the recurring payin becomes active
  • RecurringPayin_PAYMENT_PROCESSED: When a scheduled payment is processed
  • RecurringPayin_PAYMENT_FAILED: When a scheduled payment fails
  • RecurringPayin_CANCELLED: When the recurring payin is cancelled
post/recurring-payin

Request body

customer_idstring

Customer ID (cus_*). Optional but recommended for customer-specific recurring payments

payin_method_namestring required

Payin method Name to be used for recurring payments

payment_plan_idstring

Payment plan ID (payment_plan_*). If provided, other payment plan fields will be ignored

is_auto_debitboolean

Whether payments should be automatically debited without customer intervention

frequency'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY'

Frequency of recurring payments. Required if payment_plan_id is not provided

currencystring

Currency code for the recurring payment (ISO 4217). Required if payment_plan_id is not provided

countrystring

Country code for the recurring payment (ISO 3166-1 alpha-2). Required if payment_plan_id is not provided

amountnumber required

Amount for each recurring payment. Required if is_recurring_amount_fixed is true or not provided

start_atstring date-time required

Start date and time for the recurring payments (ISO 8601 format)

end_atstring date-time

End date and time for the recurring payments (ISO 8601 format). Optional

initial_activation_delayinteger

Delay in minutes before the first payment is processed. Optional

is_recurring_amount_fixedboolean

Whether the recurring amount is fixed. If false, amount field is not required

Example request

{
  "customer_id": "cus_123",
  "payin_method_name": "sg_card_visa_sgd",
  "payment_plan_id": "payment_plan_2c21b91b84c848fa87a78c7c8c4b05f5",
  "is_auto_debit": true,
  "frequency": "MONTHLY",
  "currency": "SGD",
  "country": "SG",
  "amount": 598,
  "start_at": "2025-07-18T00:00:00.000Z",
  "end_at": "2027-07-21T00:00:00.000Z",
  "initial_activation_delay": 1000,
  "is_recurring_amount_fixed": true
}

Response

Created