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 aDAILY
,WEEKLY
, orMONTHLY
basis.interval
: Interval describes the number of frequency between the recurrence. For example, you haveinterval
set to 2 withfrequency
set toDAILY
,
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
andend_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 theschedule
, 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
, andpayment_instruction
are identical as payment schedule at the time of payment is executed.payment_date
is the date of the payment is executedstatus
is the enumeration valueCOMPLETED
: The payment is executed successfully, you can usetransaction_id
to retrieve further information via internal transfer
endpointGET /v0/transactions/posted/{TRANSACTION_ID}
ERROR
: The payment execution failed. You should look intoerror_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.
Updated 10 months ago