> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```json JSON theme={"system"}
{
"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`](/reference/createpaymentschedule)
* `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.
* `execution_time`: The local time of day in the banks configured timezone at which the payments in the given schedule should execute. This is an optional field that can be omitted; system behavior will default to `11:00:00` if not applied. Note that execution times cannot be changed after creation.
### 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.
```shell Shell theme={"system"}
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.
```json JSON theme={"system"}
{
"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`](/reference/listpayments)
```shell Shell theme={"system"}
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
```shell Shell theme={"system"}
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.