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, the existing value will not be modified.
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",
        "cardType": "CREDIT",
        "maskedCardNumber4Digits": "424242...4242",
        "links": []
    },
    "links": []
}

Recurring concepts

See Recurring payment schedules for more information about the concepts of recurring payment schedules.