Recurring Payments API

Recurring payments API

Recurring payments are schedules describing repeated instalments paid to your facility by customers.

This resource is used to retrieve and modify existing recurring payments. To create new recurring payments, see Create Recurring Payment. All recurring payments for a customer can be listed using List recurring payments.

See Recurring concepts for an in-depth description of the concepts relating to recurring payments.

Get

Get the payment and schedule details of a recurring payment.

Request

GET /recurring-payments/{paymentScheduleId}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentScheduleId string QuickStream's unique identifier for the recurring payment.

Request body

None.

Response

If successful, this method returns the Recurring Payment Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentScheduleId path parameter may be incorrect. View more.

List recurring payments

List all recurring payments for the customer referenced by the path parameter.

See Recurring concepts for an in-depth description of the concepts relating to recurring payments.

Request

GET /customers/{customerId}/recurring-payments

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
customerId string QuickStream's unique identifier for the customer.

Request body

None.

Response

This is a paginated resource. The list is sorted by status to show ACTIVE recurring payments first, and then alphabetically by paymentScheduleCode.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Recurring Payment Model A paginated list of Recurring Payments.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The customerId path parameter may be incorrect. View more.

Create recurring payment

Create a new recurring payment schedule for the customer referenced by the path parameter. Payments will be made according to this schedule using the account specified, starting on the date specified.

See Recurring concepts for an in-depth description of the concepts relating to recurring payments.

Request

POST /customers/{customerId}/recurring-payments

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
customerId string QuickStream's unique identifier for the customer.

Request body

Field Format Description
supplierBusinessCode string The business that the recurring payment is to be made against.
paymentScheduleCode string Optional. Your reference for this recurring payment schedule. If not supplied, this will be generated by QuickStream.
accountToken string Optional. The account token of the customer account to take payments against. If not supplied, this will be set to the customer's default account.
scheduleType string The type of the recurring payment schedule. One of:
  • ONE_OFF
  • CONTINUE_UNTIL_FURTHER_NOTICE
  • STOP_AFTER_SET_NUMBER_OF_PAYMENTS
  • STOP_AFTER_SET_AMOUNT
  • CONTINUE_UNTIL_DATE
frequency string How often payments will be taken against this schedule. One of:
  • WEEKLY
  • FORTNIGHTLY
  • MONTHLY
  • QUARTERLY
  • SIXMONTHLY
  • YEARLY
nextPaymentDate date The first date that an instalment will be made on this schedule.
instalmentAmount Money The amount of the payment taken for each instalment.
currency string Only AUD is currently accepted.
remainingInstalments integer For STOP_AFTER_SET_NUMBER_OF_PAYMENTS schedules, the number of instalments for this schedule.
totalPaymentAmount Money For STOP_AFTER_SET_AMOUNT schedules, this is the set total amount of payments to take. Instalments of the instalmentAmount will be made until the total paid amount equals this value. The final instalment may be a different amount to make up the total.
scheduleEndDate date For CONTINUE_UNTIL_DATE schedules, the date past which no instalments will be made. The actual final instalment date may be before this date depending on the frequency.

For example:

{
    "supplierBusinessCode" : "MYCOMPANY",
    "paymentScheduleCode" : "PAYMENT_SCHEDULE",
    "accountToken" : "ACCOUNT1",
    "scheduleType" : "STOP_AFTER_SET_AMOUNT",
    "frequency" : "WEEKLY",
    "nextPaymentDate" : "2017-01-01",
    "instalmentAmount" : "125.00",
    "currency" : "AUD",
    "totalPaymentAmount" : "500.00"
}

Response

If successful, this method returns the created Recurring Payment Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the recurring payment model is returned in the response body.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more

Update

Update an existing recurring payment schedule. Any future payments made according to this schedule will use the new schedule details.

See Recurring concepts for an in-depth description of the concepts relating to recurring payments.

Request

PUT /recurring-payments/{paymentScheduleId}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentScheduleId string QuickStream's unique identifier for the recurring payment.

Request body

Field Format Description
paymentScheduleCode string Optional. Your reference for this recurring payment schedule. If not supplied, this will be generated by QuickStream.
accountToken string Optional. The account token of the customer account to take payments against. If not supplied, this will be set to the customer's default account.
scheduleType string The type of the recurring payment schedule. One of:
  • ONE_OFF
  • CONTINUE_UNTIL_FURTHER_NOTICE
  • STOP_AFTER_SET_NUMBER_OF_PAYMENTS
  • STOP_AFTER_SET_AMOUNT
  • CONTINUE_UNTIL_DATE
frequency string How often payments will be taken against this schedule. One of:
  • WEEKLY
  • FORTNIGHTLY
  • MONTHLY
  • QUARTERLY
  • SIXMONTHLY
  • YEARLY
nextPaymentDate date The first date that an instalment will be made on this schedule.
instalmentAmount Money The amount of the payment taken for each instalment.
currency string Only AUD is currently accepted.
remainingInstalments integer For STOP_AFTER_SET_NUMBER_OF_PAYMENTS schedules, the number of instalments for this schedule. Instalments already made on the schedule do not count toward this total.
totalPaymentAmount Money For STOP_AFTER_SET_AMOUNT schedules, this is the set total amount of payments to take. Instalments of the instalmentAmount will be made until the total paid amount equals this value. The final instalment may be a different amount to make up the total. This value will include any instalments already made on the schedule.
scheduleEndDate date For CONTINUE_UNTIL_DATE schedules, the date past which no instalments will be made. The actual final instalment date may be before this date depending on the frequency.

For example:

{
    "accountToken" : "ACCOUNT2",
    "scheduleType" : "STOP_AFTER_SET_AMOUNT",
    "frequency" : "MONTHLY",
    "nextPaymentDate" : "2017-02-01",
    "instalmentAmount" : "175.00",
    "currency" : "AUD",
    "totalPaymentAmount" : "500.00"
}

Response

If successful, this method returns the updated Recurring Payment Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentScheduleId path parameter may be incorrect. View more.

Stop

Stop future instalments from being made against this schedule.

Request

PATCH /recurring-payments/{paymentScheduleId}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentScheduleId string QuickStream's unique identifier for the recurring payment.

Request body

Field Format Description
status string Must be "DISABLE".

Response

If successful, this method returns the stopped Recurring Payment Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentScheduleId path parameter may be incorrect. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

List payment history

List all transactions made by the recurring payment.

Request

GET /recurring-payments/{paymentScheduleId}/transactions

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentScheduleId string QuickStream's unique identifier for the recurring payment.

Request body

None.

Response

This is a paginated resource. The list is sorted to show the most recent transactions first.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Transaction Response Model A paginated list of transactions.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentScheduleId path parameter may be incorrect. View more.

Recurring payment model

Field Format Description
paymentScheduleId string Uniquely identifies the recurring payment schedule. This value is generated by QuickStream when a recurring payment is created.
paymentScheduleCode string Your reference for this recurring payment schedule.
supplierBusinessCode string The business that the recurring payment schedule was created against.
status string Current status of recurring payment. One of ACTIVE, STOPPED, COMPLETE or INACTIVE.
scheduleType string The type of the recurring payment schedule. One of:
  • ONE_OFF
  • CONTINUE_UNTIL_FURTHER_NOTICE
  • STOP_AFTER_SET_NUMBER_OF_PAYMENTS
  • STOP_AFTER_SET_AMOUNT
  • CONTINUE_UNTIL_DATE
frequency string How often payments will be taken against this schedule. One of:
  • WEEKLY
  • FORTNIGHTLY
  • MONTHLY
  • QUARTERLY
  • SIXMONTHLY
  • YEARLY
nextPaymentDate date The date that the next payment will be taken against this schedule.
scheduleEndDate date For CONTINUE_UNTIL_DATE schedules, this will be the last date that a payment will be taken.
remainingInstalments integer Where applicable, the number of instalments remaining for this schedule.
totalInstalments integer Where applicable, the total number of instalments for this schedule.
instalmentAmount Money with surcharge The amount of the payment taken for each instalment.
nextInstalmentAmount Money with surcharge The amount of the payment expected to be taken for the next instalment. For STOP_AFTER_SET_AMOUNT schedules, this may differ from the regular amount.
totalPaidAmount Money with surcharge The total amount of all payments taken against this schedule to date.
expectedTotalPaymentAmount Money with surcharge Where applicable, the expected total amount of all payments against this schedule. This includes payments to date (totalPaidAmount), and expected future payments calculated from the schedule type and details.
merchantAccount Merchant Account For credit card payments, your merchant facility.
directEntryAccount Direct Entry Account For Australian bank account payments, your direct entry settlement account.
creditCard Credit Card For credit card payments, your customer's credit card.
bankAccount Bank Account For Australian bank account payments, your customer's bank account.
links Array of Links Links to related documents and resources.

Example Recurring Payment response

{
    "paymentScheduleId": "12345678",
    "paymentScheduleCode": "12345678",
    "supplierBusinessCode": "MYCOMPANY",
    "status": "ACTIVE",
    "scheduleType": "STOP_AFTER_SET_NUMBER_OF_PAYMENTS",
    "frequency": "WEEKLY",
    "nextPaymentDate": "2017-01-01",
    "remainingInstalments": 5,
    "totalInstalments": 10,
    "instalmentAmount": {
        "principalAmount": {
            "currency": "AUD",
            "amount": 10.00,
            "displayAmount": "$10.00"
        },
        "surchargeAmount": {
            "currency": "AUD",
            "amount": 1.00,
            "displayAmount": "$1.00"
        },
        "totalAmount": {
            "currency": "AUD",
            "amount": 11.00,
            "displayAmount": "$11.00"
        }
    },
    "nextInstalmentAmount": {
        "principalAmount": {
            "currency": "AUD",
            "amount": 10.00,
            "displayAmount": "$10.00"
        },
        "surchargeAmount": {
            "currency": "AUD",
            "amount": 1.00,
            "displayAmount": "$1.00"
        },
        "totalAmount": {
            "currency": "AUD",
            "amount": 11.00,
            "displayAmount": "$11.00"
        }
    },
    "totalPaidAmount": {
        "principalAmount": {
            "currency": "AUD",
            "amount": 50.00,
            "displayAmount": "$50.00"
        },
        "surchargeAmount": {
            "currency": "AUD",
            "amount": 5.00,
            "displayAmount": "$5.00"
        },
        "totalAmount": {
            "currency": "AUD",
            "amount": 55.00,
            "displayAmount": "$55.00"
        }
    },
    "expectedTotalPaymentAmount": {
        "principalAmount": {
            "currency": "AUD",
            "amount": 100.00,
            "displayAmount": "$100.00"
        },
        "surchargeAmount": {
            "currency": "AUD",
            "amount": 10.00,
            "displayAmount": "$10.00"
        },
        "totalAmount": {
            "currency": "AUD",
            "amount": 110.00,
            "displayAmount": "$110.00"
        }
    },
    "merchantAccount": {
        "merchantId":"12345678",
        "merchantName":"My Westpac Account",
        "settlementBsb":"032-002",
        "settlementAccountNumber":"123465",
        "displayName":"Your Company 032-002 123465 (12345678)",
        "acquiringInstitution": "WBC",
        "currency": "AUD"
    },
    "creditCard": {
        "accountType": "CREDIT_CARD",
        "accountToken": "MYCOMPANY-123456789",
        "defaultAccount": true,
        "cardNumber": "424242...242",
        "expiryDateMonth": "01",
        "expiryDateYear": "17",
        "cardScheme": "visa",
        "cardholderName": "Jane Smith",
        "maskedCardNumber4Digits": "424242...4242",
        "links": []
    },
    "links": []
}

Recurring concepts

The following sections discuss recurring payment concepts used in QuickStream.

Recurring payment definition

A recurring payment is a contract between your customer and your business. The contract states that you will take a regular payment amount from their account on a schedule. You can stop a recurring payment to cancel the contract. You can change a recurring payment to change the contract.

Weekends and public holidays

A Recurring Payment will take payments on weekends, public holidays and bank holidays. QuickStream sends payments to Westpac payments systems any day. But bank account payments may not process until the next banking day.

End of month and leap years

A Recurring Payment may be set up to take payments at the end of a month. QuickStream will debit your customer on the closest last day of the next month. For example, a monthly schedule starting 31st January 2017 debits your customer again on 28th February 2017.

Payment schedule types

Recurring offers five payment schedule types.

  1. One off
  2. Continue until further notice
  3. Stop after a set number of payments
  4. Stop after a total amount is reached
  5. Continue until a set date

One off

The One off type will take a single payment. Use this type of schedule when:

  • you want to create a new schedule to take a single "catch-up" payment because:
    • a declined payment on a Recurring Payment
    • an incorrectly set up Recurring Payment
  • your customer requires only 1 payment.

Continue until further notice

This schedule type will continue to take payments until you stop it.

Stop after a set number of payments

This schedule type will take payments until it reaches the Total Number of Payments. To use this schedule type, you must also provide the Total Number of Payments.

For example, 50.00 per month for 4 months will take the payments as follows:

  1. Month 1: 50.00
  2. Month 2: 50.00
  3. Month 3: 50.00
  4. Month 4: 50.00

Stop after a total amount is reached

This schedule type will take payments until the Total Schedule Payment Amount is reached. To use this schedule type, you must also provide the Total Schedule Payment Amount.

The last payment amount may be smaller than the Regular Payment Amount. For example, a schedule of 50.00 per month until the total reaches 175.00 is set up. This schedule takes payments as follows:

  1. Month 1: 50.00
  2. Month 2: 50.00
  3. Month 3: 50.00
  4. Month 4: 25.00

Continue until a set date

This schedule type will take payments until a Schedule End Date. To use this schedule type, you must also provide the Schedule End Date.

For example, a schedule starting on 1st March 2016 for 50.00 per month. When it is set to end on 17th June 2016, the schedule takes payments as follows:

  1. 1st March 2016: 50.00
  2. 1st April 2016: 50.00
  3. 1st May 2016: 50.00
  4. 1st June 2016: 50.00

Frequencies

Recurring offers 7 frequencies:

  1. Daily (test only)
  2. Weekly
  3. Fortnightly
  4. Monthly
  5. Quarterly
  6. Six Monthly
  7. Yearly

Daily

A Recurring Payment with a frequency of Daily will take a payment each calendar day from the start date.

For example, a schedule of 50.00 per day until it reaches 175.00 is set up. This schedule takes payments as follows:

  1. Day 1: 50.00
  2. Day 2: 50.00
  3. Day 3: 50.00
  4. Day 4: 25.00

Weekly

Recurring Payments with a Weekly frequency takes payments on the same day number on each calendar week from the start date.

For example, a schedule of 50.00 per week starting on 1st January 2016 until it reaches 175.00 is set up. This schedule will take payments on the following schedule:

  1. 1st January 2016: 50.00
  2. 8th January 2016: 50.00
  3. 15th January 2016: 50.00
  4. 22nd January 2016: 25.00

Fortnightly

A Recurring Payment with a frequency of Fortnightly will take a payment on the same day number every 2 calendar weeks from the start date.

For example, a schedule of 50.00 per fortnight starting on 1st January 2016 until it reaches 175.00 is set up. This schedule takes payments as follows:

  1. 1st January 2016: 50.00
  2. 15th January 2016: 50.00
  3. 29th January 2016: 50.00
  4. 12th February 2016: 25.00

Monthly

A Recurring Payment with a frequency of Monthly will take a payment on the same day number every calendar month from the start date.

For example, a schedule of 50.00 per month starting on 30th January 2016 until it reaches 175.00 is set up. This schedule takes payments as follows:

  1. 30th January 2016: 50.00
  2. 29th February 2016: 50.00
  3. 30th March 2016: 50.00
  4. 30th April 2016: 50.00

Quarterly

A Recurring Payment with a frequency of Quarterly will take a payment on the same day every 3 calendar months from the start date.

For example, a schedule of 50.00 per quarter starting on 31st January 2016 until 1st January 2017 is set up. This schedule takes payments as follows:

  1. 31st January 2016: 50.00
  2. 30th April 2016: 50.00
  3. 31st July 2016: 50.00
  4. 31st October 2016: 50.00

Six Monthly

A Recurring Payment with a frequency of Six Monthly will take a payment on the same day every 6 calendar months from the start date.

For example, a schedule of 50.00 per six-months starting on 31st January 2016 until 1st July 2017 is set up. This schedule takes payments as follows:

  1. 31st January 2016: 50.00
  2. 31st July 2016: 50.00
  3. 31st January 2017: 50.00

Yearly

A Recurring Payment with a frequency of Yearly will take a payment on the same day every calendar year from the start date.

For example, a schedule of 50.00 per year starting on the 1st January 2016 until 30th December 2019 is set up. This schedule takes payments as follows:

  1. 1st January 2016: 50.00
  2. 1st January 2017: 50.00
  3. 1st January 2018: 50.00
  4. 1st January 2019: 50.00

Credit card surcharges

Credit card surcharges can be set up for different credit card schemes. The surcharge is set up as a percentage of the transaction amount.

For example, if VISA has a surcharge of 0.2%, then a payment of 10.00 will have its surcharge calculated as:

  • Principal Amount: 10.00
  • Surcharge Amount: 0.02
  • Total Amount: 10.02

The total amount of the transaction will be 10.02. The amount taken from the customer will be 10.02. This amount would be credited to your merchant account.

Yet the surcharge amount is not used to determine when to stop a payment schedule.

For example, 50.00 per month until a total of 175.00 is reached will take 3 payments of 50.00 and 1 payment of 25.00. A 0.2% surcharge also set up. Each payment will have a surcharge calculated on-top of those payments:

  • Month 1: Principal amount is 50.00, Surcharge amount is 0.10, Total amount is 50.10
  • Month 2: Principal amount is 50.00, Surcharge amount is 0.10, Total amount is 50.10
  • Month 3: Principal amount is 50.00, Surcharge amount is 0.10, Total amount is 50.10
  • Month 4: Principal amount is 25.00, Surcharge amount is 0.05, Total amount is 25.05

The total schedule amount is 175.00. The total amount of money taken from the customer is 175.35.

Recurring payments are attempted at 03:00 AEST on calendar days

Transactions are attempted at 03:00 AEST each calendar day.