Transfer Schedule API

Transfer schedules are a type of schedules. For more information about schedules, check the schedules documentation

Transfer schedules allow you to plan balance transfers to a recipient's account at regular intervals. When setting up a transfer schedule, you need to know: - How often you want your transfers to be made (See schedules documentation for more information) - Which recipient you want to transfer to. - How much you want to transfer: - A fixed amount (e.g.: 10 000 thb) - A percentage of your balance (e.g. 75%) - Everything you have in your balance

For example, if you want to transfer 50% of your balance on the 1st and 15th of every month, you could do:

curl http://api.omise.co/schedules \
  -X POST \
  -u skey_test_585d7gxv63schldqyzq: \
  -d "every=1" \
  -d "period=month" \
  -d "on[days_of_month][]=1" \
  -d "on[days_of_month][]=15" \
  -d "start_date=2017-06-06" \
  -d "end_date=2018-06-06" \
  -d "transfer[recipient]=rcpt_test_585d7gxv63dpecaoch" \
  -d "transfer[percentage_of_balance]=50"

Some important notes regarding transfer schedules:

  • A recipient can only have one active transfer schedule at a time.

  • If a transfer should be created on the same day you created the schedule (in the above example: If the current date is a 1st or 15th), the first transfer will be created immediately.

  • Similarly to the dashboard and API transfers, schedules can create transfers greater than what is in your balance. E,g,: If you create a daily transfer of 10 000 THB but only charge 2000 THB per day on average.

  • However, unlike dashboard and API transfers, scheduled transfers are never retried in case of failure.

  • If you wish to transfer all your balance, omit both transfer[amount] and transfer[percentage_of_balance]

Attribute

Name Type Description
object string

The string schedule.

id object_id

The SCHEDULE_ID.

livemode boolean

Whether this is a live (true) or test (false) transfer schedule.

location string

Path to retrieve the transfer schedule.

status string

One of:

  • active: The schedule is running.
  • expiring: The schedule's next occurrence is its last.
  • expired: The schedule has reached its last occurrence and is not running anymore.
  • deleted: The schedule has been deleted and is not running anymore.
  • suspended: The schedule could not be completed and was stopped.

every integer

How often the schedule runs. E.g.: Every 3 weeks.

period string

day, week or month. E.g.: Every 3 weeks

on[weekdays] Array

Only for the week period. An array of weekday names. E.g.: ['Monday', 'Wednesday'].

on[days_of_month] Array

Only for month period when on[weekday_of_month] is omitted. An array of days of month numbers (1..28). Please note that 29, 30 and 31 are not supported as not all months have these. E.g.: [1, 15, 20]

on[weekday_of_month] string

Only for month period when on[days_of_month] is omitted. An ordinalized weekday. E.g.: 2nd_monday, last_friday

in_words string

The schedule, in english. E.g.: Every 2 months on the 15th, Every 3 days, Every week on monday and friday

start_date Date

The start date of the schedule in ISO 8601 format

end_date Date

The end date of the schedule in ISO 8601 format

transfer[amount] integer

The amount in the smallest currency unit (e.g. satang, cent, ... ) to transfer at regular intervals. Omit this field if you are not doing a fixed amount schedule.

transfer[percentage_of_balance] Decimal

The percentage of balance to be transfered. Omit this field if you are not doing a percentage schedule.

transfer[recipient] string

The recipient ID to get the transfer.

occurrences list

A list of occurrence objects.

next_occurrence_dates Array

An array of up to 30 upcoming occurrence dates in ISO 8601 format. Returns an empty array in case of expired, suspended or deleted schedule.

created datetime

Creation date of the schedule in ISO 8601 format.

Example

  • Json Response

List all transfer schedules

- GET https://api.omise.co/transfers/schedules

Returns a list of schedule objects.

Returns all transfer schedules that belong to your account. You can learn more about lists in the pagination documentation. Please note that this endpoint returns only transfer schedules. For other types of schedules, check the schedules documentation

Example

  • List all transfer schedules

List all transfer schedules for a given recipient

- GET https://api.omise.co/recipients/RECIPIENT_ID/schedules

Returns a list of schedule objects. Returns all transfer schedules that belong to a given recipient.

Example

  • List all transfer schedules for a recipient.

Retrieve a transfer schedule

- GET https://api.omise.co/schedules/SCHEDULE_ID

Create a transfer schedule

- POST https://api.omise.co/schedules

Creates and returns a new transfer schedule object.

Request Parameter

Name Type Description
every integer

How often the schedule runs. E.g.: Every 3 weeks.

period string

day, week or month. E.g.: Every 3 weeks

on Hash

This hash keys depend on the period:

  • day: Omitted.
  • week: An array of weekday names. E.g.: { weekdays: ['Monday', 'Wednesday'] }.
  • month:
    • Either an array of days of month numbers (1..28). E.g.: { days_of_month: [1, 15, 20] }
    • Or one ordinalized weekday. E.g.: { weekday_of_month: "second_monday" }, { weekday_of_month: "last_friday" }

start_date Date

(optional) When the schedule should start, in ISO 8601 format (YYYY-MM-DD). Defaults to today.

end_date Date

When the schedule should end, in ISO 8601 format (YYYY-MM-DD)

transfer[amount] integer

The amount in the smallest currency unit (e.g. satang, cent, ... ) to transfer at regular intervals. Omit this field if you are not doing a fixed amount schedule.

transfer[percentage_of_balance] Decimal

The percentage of balance to be transfered. Omit this field if you are not doing a percentage schedule.

transfer[recipient] string

The recipient ID to get the transfer.

Example

  • Transfer a fixed amount every 2 days

  • Transfer a percentage of the balance every Monday and Friday

  • Transfer the whole balance on the 1st, 10th and 15th every 3 months

  • Transfer the whole balance on the second Monday every month

Destroy a transfer schedule

- DELETE https://api.omise.co/schedules/SCHEDULE_ID