Payment Plans

Payment Plans allow a merchant to setup a billing schedule for a customer which can charge their credit card, or (if the merchant is configured for Direct Debit) debit from a bank account.

Prior to setting up a Payment Plan, a customer record needs to be setup in the system with an associated payment method (i.e. Credit Card or Bank Account). Details on how to create a customer can be found under the Customers section.

Processing and Retries

Payment Plans are processed daily at 3am Sydney time. When a payment succeeds, the payment plan is 'Rolled Over' which will either generate the next payment to replace the one just processed, or update the payment plan (for example, marking as completed, suspending, re-activating etc).

Payments will be retried up to 3 times before suspending a plan, with a delay between retries (this delay is defined when setting up a plan as retry_interval, however it will default to 3 days).

Response object

Field

Type

Description

id

String

Unique identifier for this payment plan.

customer

String

Unique identifier for this payment plan's customer.

amount

Integer

The recurring payment amount in the smallest unit for the currency e.g. 1000 = AU$10.

currency

String

The currency code for the plan.

setup_fee

Integer

A setup fee to be charged upon creation of the payment plan.

frequency

String

The frequency of the payments. Acceptable values are: Weekly, Fortnightly, Monthly, 4-Weekly, Quarterly and Annually

anniversary

Integer

The anniversary of the recurring payments.

For Weekly and Fortnightly payments this will be the day of the week (1 - Monday, 2 - Tuesday, 3 - Wednesday, 4 - Thursday, 5 - Friday)
For Monthly this will be the day of the month. If the day of the month is greater then 28, and the month is shorter
then the anniversary this date will be moved forward to the nearest possible date (i.e. a payment for the 31st will fall on the 30th for monthly like September etc).

start_date

Date (yyyy-mm-dd)

The date the payment plan should start. This must be in the future.

end_date

Date (yyyy-mm-dd)

The date the payment plan should end on. This must be in the future and greater then the start_date. Optional.

total_count

Integer

The total number of payments to process for this plan. Optional.

total_amount

Integer

The total amount of all payments to be processed for this plan. Optional.

payment_method

String

The payment method for the plan - this can be Credit Card or Direct Debit.
Note: if a merchant is not configured for Direct Debit, or a customer is not setup with the defined payment method, an error will be returned.

reference

String

Your reference for the payment plan.

description

String

A description for the payment plan (e.g. Model 200R Blender Lay-by)

status

String

The status of the payment plan.

status_reason

String

The reason the status was most recently changed.

created_at

Date as String (ISO 8601)

The date that the payment plan was created.

failed_payment_fee

Integer

A fee to apply to the retried payment in the event of any declined payment. Default: 0
Note: This amount will compound for the total number of retries (3) performed.

retry_interval

Integer

The number of days between payment retries for any declined payments. Default: 3

status_change_date

Date (yyyy-mm-dd)

The date at which the status will roll over from Active to Suspended or vice versa.

payments

Array of Payment objects

Payment object
`id`	string	Unique identifier for this payment.
`payment_plan`	string	Unique identifier for this payment's plan.
`amount`	integer	The amount for the payment.
`currency`	string	The currency code for the payment.
`scheduled_date`	Date (yyyy-mm-dd)	The date of the scheduled payment.
`payment_method`	string	The payment method for the payment - this can be Credit Card or Direct Debit
`status`	string	The status of the payment. Possible values are: Scheduled, Completed, Declined, Error and Error - Contact Support.
`result`	string	The result of the payment - this will be any of the Response Codes messages.
`records`	Array	This is an array of the payment method records (i.e. Purchases or Direct Debits). This will include any declined and approved payments.

Note that on Payment Plan bounds (End Date, Total Count, Total Amount): If a plan is bounded by an end date, total count or total amount there may be a balloon payment (large final payment) at the end of the plan. For example, if a plan is setup to start on 16/07/2015, end on 31/07/2015, has an amount of $100 and a total amount of $1,000 then the payment amounts created will be: $100, $100, $800. The final large amount is due to the bounding implied by the end date, along with the expectation that a total of $1,000 for the plan will be collected.