Payment Schedules

Customers may want to set up scheduled payments for their mortgage or to move money into savings. Synctera enables you to easily create and manage scheduled payments for your customers. Synctera will manage updating the payment date if the payment is scheduled to occur on a date the payment method is not available such as weekends for ACH.

Payment Schedule Resource

The payment schedule resource consists of two primary fields: schedule and payment_instruction. schedule is a schedule configuration to
define the frequency and number of recurring payments. payment_instruction defines how the payments are executed. There are two fields: type
defines the supported payment types like ACH and INTERNAL_TRANSFER, and request will be the same request body for the corresponding payments.

The resource also has the fields description and metadata, so the users can provide additional information for the resources.

{
  "description": "example schedule",
  "schedule": {
      "start_date": "2022-04-26",
      "frequency": "DAILY",
      "interval": 2,
      "count": 2
  },
  "payment_instruction": {
      "type": "INTERNAL_TRANSFER",
      "request": {
          "amount": 10,
          "currency": "USD",
          "originating_account_id": "{ACCOUNT_ID}",
          "receiving_account_id": "{ACCOUNT_ID}",
          "type": "ACCOUNT_TO_ACCOUNT"
      }
  }
}

Schedule Configuration

The schedule has several fields to define the recurrence. Refer to POST /v0/payment_schedules

start_date: The scheduled date of the first recurrence to be executed. Please note that the scheduled date and execution date (details below) cannot
be earlier than today's date, depends on the underlying bank's timezone.
frequency: The recurrence could be executed on a DAILY, WEEKLY, or MONTHLY basis.
interval: Interval describes the number of frequency between the recurrence. For example, you have interval set to 2 with frequency set to DAILY,
then this recurrence will be executed every other day.
count: Total number of the recurrence.
end_date: The last date of the recurrence could be executed. The date is exclusive.
Important: count and end_date are optional fields, but you have to provide exactly one of them to avoid the infinite recurrence.

Scheduled Date vs Execution Date

Once the payment schedule is created, or the current scheduled one has been executed, it will calculate the next scheduled date and execution date. The next
scheduled date will simply be calculated based on the schedule configuration for the next recurrence. Please note that if frequency is set to MONTHLY, but
the next scheduled date does not have the day of the month, then it will be the last day of the month, e.g. start_date is Jan 31 with interval is 1, then
the next recurrence will be Feb 28/29.

Execution date is based on the underlying bank's business dates. If a scheduled date falls on the bank's holiday or weekend, then the execution date will be
the last business day of the scheduled date. Otherwise, it will be the same as the scheduled date.

Execution Timing

The payment executions starts to happen on the execution date, 11:00 AM on the underlying bank's timezone. Please note that the payment could be delayed depends
on the volume of the payment schedules needs to be processed at the time.

Status

Status is the enumeration value

ACTIVE: The payment schedule has the next scheduled date and execution date determined and will be executed at the execution time.
CANCELLED: The payment schedule has been cancelled. This status can be set via the payment schedule update endpoint. Once the status is set, the next scheduled
date and execution date will be set to null, so no future payments will be executed.
EXPIRED: The payment schedule has completed all the recurrence based on the schedule, so no future payments will be executed.

Examples

A customer wants to set up scheduled payments save $100 bi-weekly for a year starting on April 26, 2022.

curl \
  -X POST \
  https://api.synctera.com/v0/payment_schedules \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "example schedule",
    "metadata": {
        "foo": "bar"
    },
    "schedule": {
        "start_date": "2022-04-26",
        "frequency": "WEEKLY",
        "interval": 2,
        "count": 26
    },
    "payment_instruction": {
        "type": "INTERNAL_TRANSFER", 
        "request": {
            "amount": 10000,
            "currency": "USD",
            "originating_account_id": "{ACCOUNT_ID}",
            "receiving_account_id": "{ACCOUNT_ID}",
            "type": "ACCOUNT_TO_ACCOUNT"
        }
    }
}'

You will have the response like below.

{
    "description": "payola testing",
    "id": "{PAYMENT_SCHEDULE_ID}",
    "metadata": {
        "key": "value"
    },
    "next_payment_date": {
        "execution_date": "2022-04-26",
        "scheduled_date": "2022-04-26"
    },
    "payment_instruction": {
        "request": {
            "amount": 10,
            "currency": "USD",
            "originating_account_id": "{ACCOUNT_ID}",
            "receiving_account_id": "{ACCOUNT_ID}",
            "type": "ACCOUNT_TO_ACCOUNT"
        },
        "type": "INTERNAL_TRANSFER"
    },
    "schedule": {
        "count": 2,
        "frequency": "DAILY",
        "interval": 2,
        "start_date": "2022-04-26"
    },
    "status": "ACTIVE"
}

Note that next_payment_date and status are the new fields. This means the next execution will be on 2022-04-26, it will
call POST /v0/internal_transfers with the request as the request body. Once it is completed, both execution_date and schedule_date
will be set to 2022-04-28

A customer wants to see all the payments from the schedule

Refer to GET /v0/payment_schedules/payments

curl \
  -X GET \
  https://api.synctera.com/v0/payment_schedules/payments?schedule_id={PAYMENT_SCHEDULE_ID} \
  -H "Authorization: Bearer $apikey"
{
  "payments": [
    {
      "description": "example schedule",
      "id": "{PAYMENT_SCHEDULE_ID}",
      "metadata": {
        "foo": "bar"
      },
      "payment_date": {
        "execution_date": "2022-04-26",
        "scheduled_date": "2022-04-26"
      },
      "payment_instruction": {
        "request": {
          "amount": 10,
          "currency": "USD",
          "originating_account_id": "{ACCOUNT_ID}",
          "receiving_account_id": "{ACCOUNT_ID}",
          "type": "ACCOUNT_TO_ACCOUNT"
        },
        "type": "INTERNAL_TRANSFER"
      },
      "payment_schedule_id": "{PAYMENT_SCHEDULE_ID}",
      "status": "COMPLETED",
      "transaction_id": "{TRANSACTION_ID}"
    }
  ]
}'

There are a few keys are worth to note:

description, metadata, and payment_instruction are identical as payment schedule at the time of payment is executed.
payment_date is the date of the payment is executed
status is the enumeration value
- COMPLETED: The payment is executed successfully, you can use transaction_id to retrieve further information via internal transfer
  endpoint GET /v0/transactions/posted/{TRANSACTION_ID}
- ERROR: The payment execution failed. You should look into error_details for further information and make the manual payment. Schedule will NOT
  retry on any failed payments.

A customer wants to cancel the future payments of the schedule

curl \
  -X PATCH \
  https://api.synctera.com/v0/payment_schedules/{PAYMENT_SCHEDULE_ID} \
  -H "Authorization: Bearer $apikey"
{
  "status": "CANCELLED"
}'

Webhook Events

There are several events you can subscribe from webhook endpoints

PAYMENT_SCHEDULE.CREATED: A payment schedule is created.
PAYMENT_SCHEDULE.UPDATED: A payment schedule is updated. Note that payment execution triggers this event as well because next_payment_date will be updated.
PAYMENT_SCHEDULE.PAYMENT.CREATED: A payment has been executed.