Skip to main content

Recurring Payments

Recurring Payments allows you to create and execute future payments (at the moment only Credit ACH and Credit Book Payments are supported) according to defined patterns, so different use cases like subscriptions, savings, rent payments and many more are supported. When creating a Recurring Payment, you can set a schedule and control the start time and frequency of the creation of future payments (at the moment only monthly occurrences are supported).

As long as the Recurring Payment is in Active status, payments will keep being created and you should expect the standard flow according to the payment type (e.g. for insufficient funds a payment will be created and instantly rejected for InsufficientFunds and a payment.rejected event will be fired.

When an account containing recurrent payments schedule(s) is frozen or closed the schedule will not be deleted but the payments will be rejected upon creation, until the account is reopened\unfrozen. If the creation of a payment according to the Recurring Payments schedule fails, a Recurring Payment Failed webhook event will be fired.

Recurring Payment Schedule#

The schedule will determine details about the patterns (frequency and execution time) of the future payments that are part of the Recurring Payments. The schedule in the response resource will include additional fields compared to the input fields that were passed by the user initially. In case the start time was not defined, the start time will be set to the current time. In case the end time was not set, the recurring payment will run until it is manually disabled. Recurring payments will be executed by the end of each day.

note

The execution day time may alter and be adjusted to the bank's working days.

note

Times in Recurring Payments are in EST.

Recurring Payment Statuses#

Recurring Payments have a status attribute, which represents their current status.

StatusDescription
ActiveUpon creation, the status will be set to Active.
CompletedWhen the end date of the recurring payment has passed, the status will be set to Completed.
DisabledWhen recurring payment has been disabled, the status will be set to Disabled.

Create Recurring Credit ACH payment#

Originates a Recurring Credit ACH payment to a Counterparty. The counterparty should be created separately through the Create Counterparty API. The Recurring Payment Created webhook event will be fired.

VerbPOST
Urlhttps://api.s.unit.sh/recurring-payments
Required Scopepayments-write-counterparty or payments-write
Data TyperecurringCreditAchPayment
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents).
descriptionstringPayment description (maximum of 10 characters), also known as Company Entry Description, this will show up on the statement of the counterparty.
addendastringOptional, additional payment description (maximum of 80 characters), not all institutions present that.
scheduleCreate ScheduleThe schedule details of the recurring payment. All times must be in the future.
idempotencyKeystringOptional. See Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
counterpartyJSON:API RelationshipThe Counterparty to which the payment will be made.
Example Request:
curl -X POST 'https://api.s.unit.sh/recurring-payments'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "recurringCreditAchPayment",    "attributes": {      "schedule": {        "interval": "Monthly",        "dayOfMonth": 16,        "totalNumberOfPayments": 12      },      "amount": 1000,      "description": "Rent-Apt15"    },    "relationships": {      "account": {        "data": {          "type": "depositAccount",          "id": "10002"        }      },      "counterparty": {        "data": {          "type": "counterparty",          "id": "1"        }      }    }  }}'

Response#

Response is a JSON:API document.

201 Created#

FieldTypeDescription
dataRecurringCreditAchPaymentThe target resource after the operation was completed.
Example Response:
{  "data": {    "type": "recurringCreditAchPayment",    "id": "1",    "attributes": {      "createdAt": "2022-06-25T08:50:49.391Z",      "updatedAt": "2022-06-25T08:50:49.391Z",      "amount": 1000,      "description": "Rent-Apt15",      "schedule": {        "startTime": "2022-06-25",        "interval": "Monthly",        "nextScheduledAction": "2022-07-18",        "dayOfMonth": 16,        "totalNumberOfPayments": 12      },      "status": "Active",      "numberOfPayments": 0    },    "relationships": {      "counterparty": {        "data": {          "type": "counterparty",          "id": "1"        }      },      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "customer": {        "data": {          "type": "customer",          "id": "10004"        }      },      "org": {        "data": {          "type": "org",          "id": "1"        }      }    }  }}

Create Recurring Credit Book payment#

The Recurring Payment Created webhook event will be fired.

VerbPOST
Urlhttps://api.s.unit.sh/recurring-payments
Required Scopepayments-write
Data TyperecurringBookPayment
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents).
descriptionstringPayment description (maximum of 80 characters), this will show up on the statement of the counterparty.
transactionSummaryOverridestringOptional. If this field is populated, its contents will be returned as the bookTransaction’s summary field (maximum of 100 characters).
scheduleCreate ScheduleThe schedule details of the recurring payment. All times must be in the future.
idempotencyKeystringOptional. See Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
counterpartyAccountJSON:API RelationshipThe Counterparty account to which the payment will be made.
Example Request:
curl -X POST 'https://api.s.unit.sh/recurring-payments'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "recurringCreditBookPayment",    "attributes": {      "amount": 40,      "description": "Subscription - Basic Plan",      "tags": {        "test": "test"      },      "schedule": {        "interval": "Monthly",        "dayOfMonth": 5      }    },    "relationships": {      "account": {        "data": {          "type": "depositAccount",          "id": "10002"        }      },      "counterpartyAccount": {        "data": {          "type": "depositAccount",          "id": "10000"        }      }    }  }}'

Response#

Response is a JSON:API document.

201 Created#

FieldTypeDescription
dataRecurringCreditBookPaymentThe target resource after the operation was completed.
Example Response:
{  "data": {    "type": "recurringCreditBookPayment",    "id": "4",    "attributes": {      "createdAt": "2022-06-25T14:27:41.093Z",      "updatedAt": "2022-06-25T14:27:41.093Z",      "amount": 40,      "description": "Subscription - Basic Plan",      "schedule": {        "startTime": "2022-06-25",        "interval": "Monthly",        "nextScheduledAction": "2022-07-05",        "dayOfMonth": 5      },      "status": "Active",      "tags": {        "test": "test"      },      "numberOfPayments": 0    },    "relationships": {      "org": {        "data": {          "type": "org",          "id": "1"        }      },      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "counterpartyAccount": {        "data": {          "type": "account",          "id": "10000"        }      },      "customer": {        "data": {          "type": "customer",          "id": "10004"        }      }    }  }}

Disable Recurring Payment#

Disable a Recurring Payment by id. When a Recurring Payment is disabled, the Recurring Payment Status Changed webhook event is fired and future payments will no longer be created according to the defined schedule.

VerbPOST
Urlhttps://api.s.unit.sh/recurring-payments/{id}/disable
Required Scopepayments
Timeout (Seconds)5

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataOne of the following types (Recurring Credit ACH Payment or Recurring Credit Book PaymentRecurring Payment resource.
curl -X POST 'https://api.s.unit.sh/recurring-payments/12/disable' \-H "Authorization: Bearer ${TOKEN}"

Response#

Response is a JSON:API document.

Example Response:
{  "data": {    "type": "recurringCreditBookPayment",    "id": "4",    "attributes": {      "createdAt": "2022-06-25T14:27:41.093Z",      "updatedAt": "2022-06-25T15:43:07.516Z",      "amount": 40,      "description": "Subscription - Basic Plan",      "schedule": {        "startTime": "2022-06-25",        "interval": "Monthly",        "nextScheduledAction": "2022-07-05",        "dayOfMonth": 5      },      "status": "Disabled",      "tags": {        "test": "test"      },      "numberOfPayments": 0    },    "relationships": {      "org": {        "data": {          "type": "org",          "id": "1"        }      },      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "counterpartyAccount": {        "data": {          "type": "account",          "id": "10000"        }      },      "customer": {        "data": {          "type": "customer",          "id": "10004"        }      }    }  }}

Enable Recurring Payment#

Enable a recurring payment by id. When a Recurring Payment is enabled, its status is set to Active/Completed according to the start date and end date that were defined in the schedule. See Recurring Payment Statuses. When enabled, the Recurring Payment Status Changed webhook event is fired.

VerbPOST
Urlhttps://api.s.unit.sh/recurring-payments/{id}/enable
Required Scopepayments
Timeout (Seconds)5

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataOne of the following types (Recurring Credit ACH Payment or Recurring Credit Book PaymentRecurring Payment resource.
curl -X POST 'https://api.s.unit.sh/recurring-payments/12/enable' \-H "Authorization: Bearer ${TOKEN}"

Response#

Response is a JSON:API document.

Example Response:
{  "data": {    "type": "recurringCreditAchPayment",    "id": "1",    "attributes": {      "createdAt": "2022-06-25T08:50:49.391Z",      "updatedAt": "2022-06-25T14:28:23.376Z",      "amount": 1000,      "description": "Rent - Apartment 15",      "schedule": {        "startTime": "2022-06-25",        "interval": "Monthly",        "nextScheduledAction": "2022-07-18",        "dayOfMonth": 16      },      "status": "Active",      "numberOfPayments": 1    },    "relationships": {      "counterparty": {        "data": {          "type": "counterparty",          "id": "1"        }      },      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "customer": {        "data": {          "type": "customer",          "id": "10004"        }      },      "org": {        "data": {          "type": "org",          "id": "1"        }      }    }  }}

Get by Id#

Get a recurring payment by id.

VerbGET
Urlhttps://api.s.unit.sh/recurring-payments/{id}
Required Scopepayments
Timeout (Seconds)5

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataOne of the following types (Recurring Credit ACH Payment or Recurring Credit Book PaymentRecurring Payment resource.
curl -X GET 'https://api.s.unit.sh/recurring-payments/100' \-H "Authorization: Bearer ${TOKEN}"

List Recurring Payments#

List recurring payments resources. Filtering, paging and sorting can be applied.

VerbGET
Urlhttps://api.s.unit.sh/recurring-payments
Required Scopepayments
Timeout (Seconds)5

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. Number of resources to skip. See Pagination.
filter[accountId]string(empty)Optional. Filters the results by the specified account id.
filter[customerId]string(empty)Optional. Filters the results by the specified customer id.
filter[status][]string(empty)Optional. Filter recurring payments by status (Active, Completed or Disabled). Usage example: *filter[status][0]=Active
filter[type][]string(empty)Optional. Filter recurring payments by Recurring Payment type. such as (RecurringCreditAchPayment, RecurringCreditBookPayment). Usage example: filter[type][0]=RecurringCreditAchPayment&filter[type][1]=RecurringCreditBookPayment
filter[fromStartTime]RFC3339 Date string(empty)Optional. Filters the Recurring Payments that their start time occurred after the specified date. e.g. 2022-06-13
filter[toStartTime]RFC3339 Date string(empty)Optional. Filters the Recurring Payments that their start time occurred before the specified date. e.g. 2022-05-13
filter[fromEndTime]RFC3339 Date string(empty)Optional. Filters the Recurring Payments that their end time occurred after the specified date. e.g. 2022-06-13
filter[toEndTime]RFC3339 Date string(empty)Optional. Filters the Recurring Payments that their end time occurred before the specified date. e.g. 2022-05-13
sortstringsort=-createdAtOptional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
curl -X GET 'https://api.s.unit.sh/recurring-payments?page[limit]=20&page[offset]=10&filter[status][]=Enabled' \-H "Authorization: Bearer ${TOKEN}"

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataArray of Recurring Payments (ACH Credit Recurring Payment, Book Recurring PaymentArray of recurring payment resources.
metaJSON object that contains pagination dataPagination data includes offset, limit and total (total items).
Example Response:
{  "data": [    {      "type": "recurringCreditAchPayment",      "id": "1",      "attributes": {        "createdAt": "2022-06-25T08:50:49.391Z",        "updatedAt": "2022-06-25T14:28:23.376Z",        "amount": 200,        "description": "ACH PYMT",        "schedule": {          "startTime": "2022-06-25",          "interval": "Monthly",          "nextScheduledAction": "2022-07-18",          "dayOfMonth": 16        },        "status": "Active",        "numberOfPayments": 1      },      "relationships": {        "counterparty": {          "data": {            "type": "counterparty",            "id": "1"          }        },        "account": {          "data": {            "type": "account",            "id": "10002"          }        },        "customer": {          "data": {            "type": "customer",            "id": "10004"          }        },        "org": {          "data": {            "type": "org",            "id": "1"          }        }      }    },    {      "type": "recurringCreditAchPayment",      "id": "3",      "attributes": {        "createdAt": "2022-06-25T08:53:02.265Z",        "updatedAt": "2022-06-25T08:53:02.265Z",        "amount": 200,        "description": "ACH PYMT",        "schedule": {          "startTime": "2022-06-25",          "interval": "Monthly",          "nextScheduledAction": "2022-07-18",          "dayOfMonth": 16        },        "status": "Active",        "numberOfPayments": 0      },      "relationships": {        "counterparty": {          "data": {            "type": "counterparty",            "id": "1"          }        },        "account": {          "data": {            "type": "account",            "id": "10002"          }        },        "customer": {          "data": {            "type": "customer",            "id": "10004"          }        },        "org": {          "data": {            "type": "org",            "id": "1"          }        }      }    },    {      "type": "recurringCreditBookPayment",      "id": "4",      "attributes": {        "createdAt": "2022-06-25T14:27:41.093Z",        "updatedAt": "2022-06-25T15:44:35.388Z",        "amount": 200,        "description": "Book payment",        "schedule": {          "startTime": "2022-06-25",          "interval": "Monthly",          "nextScheduledAction": "2022-07-05",          "dayOfMonth": 5        },        "status": "Active",        "tags": {          "test": "test"        },        "numberOfPayments": 0      },      "relationships": {        "org": {          "data": {            "type": "org",            "id": "1"          }        },        "account": {          "data": {            "type": "account",            "id": "10002"          }        },        "counterpartyAccount": {          "data": {            "type": "account",            "id": "10000"          }        },        "customer": {          "data": {            "type": "customer",            "id": "10004"          }        }      }    }  ],  "meta": {    "pagination": {      "total": 3,      "limit": 100,      "offset": 0    }  }}