Skip to main content

Customers API

QuickStream uses customers to store account and payment information and contact details. Usually, a customer in QuickStream represents a person making payments to your facility. Use this resource to:

  1. Search and retrieve customers.
  2. Create or update a customer.
  3. Enable or disable a customer.
  4. List enabled accounts for a customer.
  5. Register a credit card or bank account.
  6. List or create recurring payments for a customer.
  7. List a customer's transactions.

Get

Get the identification, contact and address details of a customer.

Request

GET /customers/{customerId}

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

If successful, this method returns the Customer 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 customerId path parameter may be incorrect. View more.

Search for customers in your QuickStream facility by customer number, name or email address.

When no search parameters are supplied, this will list all customers. The list is sorted by customerId.

Request

GET /customers

Use your Secret API key to access this resource.

Query parameters
Parameter Name Format Description
customerNumber string Optional. Search for customer with matching customer number. This field must match exactly.
customerName string Optional. Filter the customers by name. This field can be a partial match.
emailAddress string Optional. Filter the customers by email address. This field can be a partial match.
Request body

None.

Response

This is a paginated resource. The list is sorted by customerId.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Customer Model A paginated list of customers.
HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.

Create

Create a customer for your facility. This customer can then be be used to register an account, and then to take a payment or create a recurring payment.

Request

POST /customers

Use your Secret API key to access this resource.

Request body
Field Format Description
customerNumber string Your unique reference for this customer. Any lower case characters will be converted to upper case.
customerName string A name for the customer.
supplierBusinessCode string This field is only relevant for customers registered against businesses. The business that the customer is to be registered against.
phoneNumber string Optional. Contact number for customer.
emailAddress string Optional. Contact email address for customer.
preferredNotificationMedium string Optional. This customer's preference for receiving notifications. One of EMAIL, SMS, EMAILANDSMS, or NONE. The corresponding contact details for the chosen preference are required if this is supplied.
address Address Model Optional. The address of the customer.

For example:

{
    "customerNumber" : "JOHN_SMITH",
    "customerName" : "John Smith",
    "phoneNumber" : "0400000000",
    "preferredNotificationMedium" : "SMS",
    "address" : {
        "street1" : "1 Main Street",
        "city" : "Sydney",
        "state" : "NSW",
        "postcode":"2000",
        "country" : "AU"
    }
}

Response

If successful, this method returns the created Customer 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 customer model is returned in the response body.
409 CONFLICT The server can not process the request as it has conflicted with another request. See Idempotent Requests.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more

Update

Update the details and status of a customer. A customer can either be ENABLED or DISABLED. DISABLED customers have limited functionality, and cannot make new payments.

Request

PUT /customers/{customerId}

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
customerNumber string Your unique reference for this customer. Any lower case characters will be converted to upper case.
customerName string A name for the customer.
enabled string The current status of the customer. One of true or false.
phoneNumber string Optional. Contact number for customer.
emailAddress string Optional. Contact email address for customer.
preferredNotificationMedium string Optional. This customer's preference for receiving notifications. One of EMAIL, SMS, EMAILANDSMS, or NONE. The corresponding contact details for the chosen preference are required if this is supplied.
address Address Model Optional. The address of the customer.

For example:

{
    "customerNumber" : "JOHN_SMITH",
    "customerName" : "John Smith",
    "enabled" : "true",
    "phoneNumber" : "0499999999",
    "emailAddress" : "johnsmith@example.com",
    "preferredNotificationMedium" : "EMAILANDSMS",
    "address" : {
        "street1" : "2 Main Street",
        "city" : "Sydney",
        "state" : "NSW",
        "postcode":"2000",
        "country" : "AU"
    }
}

Response

If successful, this method returns the updated Customer 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 customerId path parameter may be incorrect. View more.

Update status

Update the customer's status. A customer can either be ENABLED or DISABLED.

DISABLED customers have limited functionality, and cannot make new payments.

Request

PATCH /customers/{customerId}

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
enabled boolean If true, this customer will be enabled. If false, the customer will be disabled.

Response

If successful, this method returns the updated Customer 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 customerId 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 accounts

List all enabled credit card and bank accounts for the customer referenced by the path parameter.

Request

GET /customers/{customerId}/accounts

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 to show the most recently registered accounts first.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Customer Account Model A paginated list of customer accounts.
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.

Register account

Use this resource to register a new credit card or bank account for the customer referenced by the path parameter. This account can then be used to take a payment or create a recurring payment.

The created account will have a unique identifier called the account token, which can be used for payments. If the account details match an existing account for the customer, that account will be updated and returned instead.

There are several different ways to register an account:

Request

POST /customers/{customerId}/accounts

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

Include one of the following fields in the request body:

Field Format Description
singleUseTokenId string A token issued by QuickStream which holds credit card or bank account details. See Single-Use-Tokens API.
receiptNumber string The unique identifier for the transaction linked to the credit card or bank account details. See Receipt number registrations.
bankAccount Bank Account Request The bank account details. See Direct registrations.
creditCard Card Account Request The card account details. See also Direct registrations.

If you are using EMV 3D Secure, also include the following field:

Field Format Description
threeDS2 boolean Optional. true if you have implemented EMV 3D Secure and are tokenising a card account using a single-use-token.

If you are using Scheme Tokenisation, also include the following field:

Field Format Description
schemeTokenisation Scheme Tokenisation Request Model You must have Scheme Tokenisation activated on your facility to use this field.
Single-use-token registrations

Single-use-tokens allow you to avoid sending credit card or bank account details to your server.

To register a credit card or bank account via this method, first generate a single-use-token and then include it in the request body.

To register an account using a single-use-token:

{
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22"
}
Receipt number registrations

Registering accounts from transactions allows you to store account details for re-use in subsequent transactions. Receipt numbers are returned whenever a transaction is processed using QuickStream. See Take payments.

A possible use of this method is to take an initial payment using a single-use-token including the card CVN, then use the receiptNumber from the response to register the account against a new or existing customer to be used later.

To register an account via this method, include the receiptNumber of a transaction in a request body. The registered account will take its details from the credit card or bank account used to make the transaction.

To register an account using a receipt number:

{
    "receiptNumber": "123456789"
}
Direct registrations

To register an account using account details directly in the request, include one of creditCard, bankAccount, or nzBankAccount in the request body with the fields specified below.

To make a direct card registration:

{
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022"
    }
}

Response

If successful, this method returns the registered Customer Account 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 and the updated existing customer account model is returned in the response body.
201 CREATED The request has succeeded and the newly created customer account 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

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

List payment history

List all transactions made by the customer.

Request

GET /customers/{customerId}/transactions

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 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 customerId path parameter may be incorrect. View more.

Customer model

Field Format Description
customerId string Uniquely identifies the customer. This value is generated by QuickStream when a customer is created.
customerNumber string Your reference for this customer.
supplierBusinessCode string This field is only relevant for customers registered against businesses. The business that the customer is registered against.
customerName string A name for the customer.
status string Current status of customer. One of ENABLED or DISABLED. DISABLED customers will not be able to make new payments.
phoneNumber string Contact number for customer.
emailAddress string Contact email address for customer.
preferredNotificationMedium string This customer's preference for receiving notifications. One of EMAIL, SMS, EMAILANDSMS, or NONE.
address Address Model Address of customer.
links Array of Links Links to related documents and resources.

Example customer response

{
    "customerId" : "12345678",
    "customerNumber" : "JOHN_SMITH",
    "customerName" : "John Smith",
    "status" : "ENABLED",
    "phoneNumber" : "0400000000",
    "emailAddress": null,
    "preferredNotificationMedium" : null,
    "address" : {
        "street1" : "1 Main Street",
        "city" : "Sydney",
        "state" : "NSW",
        "postcode":"2000",
        "country" : "AU"
    },
    "links":[]
}

Address model

Field Format Description
street1 string Line 1 of the address.
street2 string Line 2 of the address.
street3 string Line 3 of the address.
city string The city or suburb.
state string The state code.
postcode string The postal or zip code.
country string The two character ISO country code.

For example:

{
    "street1": "Level 1, Shop 13",
    "street2": "York Street",
    "city": "Devonport",
    "state": "TAS",
    "postcode": "2100",
    "country": "AU"
}

Customer account model

A customer account is one of:

Credit card model

Field Format Description
accountType string CREDIT_CARD
accountToken string The account token. See Register Account for more.
defaultAccount boolean If true, this account will be used for the owning customer where an account token is not specified. This includes taking payments by customerId and creating recurring payments without an accountToken.
cardNumber string Masked credit card number displaying the first 6 and last 3 digits.
For scheme tokenised accounts, this would display the last 3 digits in the following format: xxxxxx...242.
expiryDateMonth string Two digit expiry month.
expiryDateYear string Two digit expiry year.
cardScheme string The card scheme. VISA, MASTERCARD, AMEX, DINERS, JCB, or UNIONPAY.
cardType string The card type. CREDIT, DEBIT. Note: This is only for VISA and MASTERCARD. Other card types may be added in the future.
cardholderName string The name printed on the card.
maskedCardNumber4Digits string Masked credit card number displaying the first 6 and last 4 digits.
For scheme tokenised accounts, this would display the last 4 digits in the following format: xxxxxx...4242.
panType string
  • FPAN (default) - the card number from a physical card. Also known as "Funding PAN".
  • DPAN - a digitised card number from a wallet provider or scheme tokenisation service. Also known as "Digital PAN".
walletProvider string Specifies the wallet provider from which the card details were obtained, if applicable. APPLE_PAY, GOOGLE_PAY
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
links Array of Links Links to related documents and resources.

Example credit card response


{
    "accountType": "CREDIT_CARD",
    "accountToken": "MYCOMPANY-123456789",
    "defaultAccount": true,
    "cardNumber": "424242...242",
    "expiryDateMonth": "01",
    "expiryDateYear": "17",
    "cardScheme": "VISA",
    "cardType": "CREDIT",
    "cardholderName": "Jane Smith",
    "maskedCardNumber4Digits": "424242...4242",
    "panType": "FPAN",
    "customerId" : 123456789,
    "links": []
}

Bank account model

Field Format Description
accountType string DIRECT_DEBIT
accountToken string The account token. See Register Account for more.
defaultAccount boolean If true, this account will be used for the owning customer where an account token is not specified. This includes taking payments by customerId and creating recurring payments without an accountToken.
accountName string Name of account holder.
displayName string The bank account display name.
currency string AUD
bsb string The bank-state-branch holding their account.
accountNumber string The account number at that branch.
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
links Array of Links Links to related documents and resources.

Example bank account response

{
    "accountType": "DIRECT_DEBIT",
    "accountToken": "MYCOMPANY-123456780",
    "defaultAccount": true,
    "accountName": "Jane's Bank Account",
    "displayName": "Jane's Bank Account",
    "currency": "AUD",
    "bsb": "032-000",
    "accountNumber": "123465",
    "customerId" : 123456789,
    "links": []
}

New Zealand bank account model

Field Format Description
accountType string DIRECT_DEBIT_NZ
accountToken string The account token. See Register Account for more.
defaultAccount boolean If true, this account will be used for the owning customer where an account token is not specified. This includes taking payments by customerId and creating recurring payments without an accountToken.
nzAccountName string Name of account holder.
displayName string The bank account display name.
currency string NZD
nzBankCode string The bank holding their account.
nzBranchCode string The branch holding their account.
nzAccountNumber string The account number at that branch.
nzAccountSuffix string The type of account.
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
links Array of Links Links to related documents and resources.

Example New Zealand bank account response

{
    "accountType": "DIRECT_DEBIT_NZ",
    "accountToken": "MYCOMPANY-123456780",
    "defaultAccount": true,
    "nzAccountName": "Jane's Bank Account",
    "displayName": "Jane's Bank Account",
    "currency": "NZD",
    "nzBankCode": "01",
    "nzBranchCode": "0001",
    "nzAccountNumber": "0000001",
    "nzAccountSuffix": "00",
    "links": []
}

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": []
}
Westpac Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.