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 Debitstatus | 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.