Accounts API

Accounts API

Accounts store the details of cards or bank accounts to be used for payment.

Use this resource to retrieve and modify existing accounts. To register new accounts, see Register account. All accounts registered against a customer can be listed using List accounts.

Get

Get the details of an account.

Request

GET /accounts/{accountToken}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
accountToken string The unique identifier for this account.

Request body

None.

Response

If successful, this method returns the 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.
404 NOT FOUND The accountToken path parameter may be incorrect. 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.
creditCard Credit Card Request The credit card account details. See Direct registrations.
bankAccount Bank Account Request The bank account details. See Direct registrations.

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.

Credit card request model

Field Format Required Description
cardholderName string Optional Name printed on the card.
cardNumber string Required Digits printed on the card.
expiryDateMonth string Required Two digit expiry month.
expiryDateYear string Required Four digit expiry year.

To make a direct credit card registration:

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

Bank account request model

Field Format Required Description
accountName string Required Name of account holder.
bsb string Required The bank-state-branch holding their account.
accountNumber string Required The account number at that branch.

To make a direct Australian bank account registration:

{
    "bankAccount": {
        "accountName" : "Jane Smith",
        "bsb" : "032-000",
        "accountNumber": "123410"
    }
}

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

Update

Make this account the default account for the owning customer, or update the account name or credit card expiry date.

Request

PATCH /accounts/{accountToken}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
accountToken string The unique identifier for this account.

Request body

Parameter Name Format Description
defaultAccount boolean Optional. 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.
cardholderName string Optional. Name printed on the card. For CREDIT_CARD only.
expiryDateMonth string Optional. Two digit expiry month. For CREDIT_CARD only.
expiryDateYear string Optional. Four digit expiry year. For CREDIT_CARD only.
accountName string Optional. Name of account holder. For DIRECT_DEBIT only.
nzAccountName string Optional. Name of account holder. For DIRECT_DEBIT_NZ only.

Response

If successful, this method returns the updated 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.
404 NOT FOUND The accountToken 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

Disable

Disable an account to remove the ability to take new payments or start recurring payment schedules. A disabled account will no longer be usable for payments or able to be retrieved or modified through List accounts, Get account or Update account.

Request

DELETE /accounts/{accountToken}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
accountToken string The unique identifier for this account.

Request body

None.

Response

If successful, this method will return an empty response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
204 NO CONTENT The account was disabled successfully.
404 NOT FOUND The accountToken path parameter may be incorrect. View more.

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.
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 last 4 digits.
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",
    "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.
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",
    "links": []
}