Recurring Payments

Recurring Payments allows you to create and execute future payments (at the moment only Credit ACH, Debit 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 (monthly or weekly intervals 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.

Status	Description
Active	Upon creation, the status will be set to `Active`.
Completed	When the end date of the recurring payment has passed, the status will be set to `Completed`.
Disabled	When 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.

Verb	`POST`
Url	`https://api.s.unit.sh/recurring-payments`
Required Scope	`payments-write-counterparty` or `payments-write` or `ach-payments-write`
Data Type	`recurringCreditAchPayment`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
description	string	Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on the statement of the counterparty.
addenda	string	Optional, additional payment description (maximum of 80 characters), not all institutions present that.
schedule	Create Schedule	The schedule details of the recurring payment. All times must be in the future.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
counterparty	JSON:API Relationship	The 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

Field	Type	Description
data	RecurringCreditAchPayment	The 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 Debit ACH payment

Originates a Recurring Debit 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.

Verb	`POST`
Url	`https://api.s.unit.sh/recurring-payments`
Required Scope	`payments-write-counterparty` or `payments-write` or `ach-payments-write`
Data Type	`recurringCreditAchPayment`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
description	string	Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on the statement of the counterparty.
addenda	string	Optional, additional payment description (maximum of 80 characters), not all institutions present that.
schedule	Create Schedule	The schedule details of the recurring payment. All times must be in the future.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
verifyCounterpartyBalance	boolean	Optional, default is `false`. Verify the counterparty balance, if balance verification fails the payment will be rejected with reason set to `CounterpartyInsufficientFunds`.
sameDay	boolean	Optional, default is `false`. See Same Day ACH.

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
counterparty	JSON:API Relationship	The 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": "recurringDebitAchPayment",
    "attributes": {
      "schedule": {
        "interval": "Monthly",
        "dayOfMonth": 16,
        "totalNumberOfPayments": 12
      },
      "amount": 1000,
      "description": "Rent-Apt15",
      "verifyCounterpartyBalance": true
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10002"
        }
      },
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "1"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	RecurringDebitAchPayment	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "recurringDebitAchPayment",
    "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.

Verb	`POST`
Url	`https://api.s.unit.sh/recurring-payments`
Required Scope	`payments-write`
Data Type	`recurringBookPayment`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
description	string	Payment description (maximum of 80 characters), this will show up on the statement of the counterparty.
transactionSummaryOverride	string	Optional. If this field is populated, its contents will be returned as the bookTransaction’s summary field (maximum of 100 characters).
schedule	Create Schedule	The schedule details of the recurring payment. All times must be in the future.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
counterpartyAccount	JSON:API Relationship	The 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

Field	Type	Description
data	RecurringCreditBookPayment	The 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.

Verb	`POST`
Url	`https://api.s.unit.sh/recurring-payments/{id}/disable`
Required Scope	`payments`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	One of the following types (Recurring Credit ACH Payment or Recurring Credit Book Payment	Recurring 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.

Verb	`POST`
Url	`https://api.s.unit.sh/recurring-payments/{id}/enable`
Required Scope	`payments`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	One of the following types (Recurring Credit ACH Payment or Recurring Credit Book Payment	Recurring 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.

Verb	`GET`
Url	`https://api.s.unit.sh/recurring-payments/{id}`
Required Scope	`payments`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	One of the following types (Recurring Credit ACH Payment or Recurring Credit Book Payment	Recurring 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.

Verb	`GET`
Url	`https://api.s.unit.sh/recurring-payments`
Required Scope	`payments`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. 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`
sort	string	`sort=-createdAt`	Optional. 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

Field	Type	Description
data	Array of Recurring Payments (ACH Credit Recurring Payment, Book Recurring Payment	Array of recurring payment resources.
meta	JSON object that contains pagination data	Pagination 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
    }
  }
}

Recurring Payments

Recurring Payment Schedule​

Recurring Payment Statuses​

Create Recurring Credit ACH payment​

Attributes​

Relationships​

Response​

201 Created​

Create Recurring Debit ACH payment​

Attributes​

Relationships​

Response​

201 Created​

Create Recurring Credit Book payment​

Attributes​

Relationships​

Response​

201 Created​

Disable Recurring Payment​

Response​

200 OK​

Response​

Enable Recurring Payment​

Response​

200 OK​

Response​

Get by Id​

Response​

200 OK​

List Recurring Payments​

Query Parameters​

Response​

200 OK​

Recurring Payment Schedule

Recurring Payment Statuses

Create Recurring Credit ACH payment

Attributes

Relationships

Response

201 Created

Create Recurring Debit ACH payment

Attributes

Relationships

Response

201 Created

Create Recurring Credit Book payment

Attributes

Relationships

Response

201 Created

Disable Recurring Payment

Response

200 OK

Response

Enable Recurring Payment

Response

200 OK

Response

Get by Id

Response

200 OK

List Recurring Payments

Query Parameters

Response

200 OK