Skip to main content

Single-use-tokens API

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

Single-use-tokens can be used to:

  1. take a payment.
  2. register an account for a customer.
  3. register an account without a customer.

Single-use-tokens can only be used once for the above actions, and will expire after 10 minutes.

Single-use-tokens can be used to perform 3D Secure Authentication without being consumed. The token is then consumed by the actions listed above.

Generate token

Use this resource to generate a single-use-token using a credit card or bank account.

This resource is most commonly used by the Trusted Frame.

Request

POST /single-use-tokens

Use your Publishable API key to access this resource.

Request body
Field Format Data
supplierBusinessCode string The business to be used for validation of other fields. This value will not be checked when using the token to make payments or register accounts. Accepted values can be obtained via the Businesses API.
accountType string One of: CREDIT_CARD, DIRECT_DEBIT, DIRECT_DEBIT_NZ.
cardholderName string Optional. Name printed on the card. For CREDIT_CARD only.
cardNumber string Digits printed on the card. For CREDIT_CARD only.
expiryDateMonth string Two digit expiry month. For CREDIT_CARD only.
expiryDateYear string Four digit expiry year. For CREDIT_CARD only.
cvn string Optional. Card Verification Number. Also known as Security Code, CVV2 and CVC2. The three or four digit security code. For CREDIT_CARD only.
accountName string Name of account holder. For DIRECT_DEBIT only.
bsb string The bank-state-branch holding their account. For DIRECT_DEBIT only.
accountNumber string The account number at that branch. For DIRECT_DEBIT only.
nzAccountName string Name of account holder. For DIRECT_DEBIT_NZ only.
nzBankCode string The bank code holding their account. For DIRECT_DEBIT_NZ only.
nzBranchCode string The branch of the bank holding their account. For DIRECT_DEBIT_NZ only.
nzAccountNumber string The account number at that branch. For DIRECT_DEBIT_NZ only.
nzAccountSuffix string The account suffix. For DIRECT_DEBIT_NZ only.
threeDS2 boolean Optional. true indicates to QuickStream that 3D Secure authentication should be attempted.
browserProfile Browser Profile Required when threeDS2=true. The cardholder's browser information.
Browser Profile model

All fields are required when threeDS2=true.

Field Format Data
browserJavaEnabled boolean The navigator.javaEnabled value indicating if the cardholder's browser is able to execute Java.
browserLanguage string The navigator.language value representing language of the cardholder's browser, as defined in IETF BCP 47. Max length of 8 digits.
browserScreenHeight string The screen.height value representing the total height of the cardholder's screen in pixels. Max length of 6 digits.
browserColorDepth string The screen.colorDepth value representing the colour depth of the cardholder's screen in bits per pixel. Values are 1,4,8,15,16,24,32,48.
browserScreenWidth string The screen.width value representing the total width of the cardholder's screen in pixels. Max length of 6 digits.
browserTZ string The getTimezoneOffset() value representing the time-zone offset in between UTC and the local time of the cardholder's browser in minutes. Max length of 5 characters.
Example requests

To generate a single-use-token for a card account from fully PCI-DSS compliant software:

{
    "supplierBusinessCode": "MYSUPPLIER",
    "accountType" : "CREDIT_CARD",
    "cardholderName" : "Jane Smith",
    "cardNumber" : "4242424242424242",
    "expiryDateMonth": "12",
    "expiryDateYear": "2027",
    "cvn": "123"
}

To generate a single-use-token for an Australian bank account: 

{
    "supplierBusinessCode": "MYSUPPLIER",
    "accountType" : "DIRECT_DEBIT",
    "accountName" : "Jane Smith",
    "bsb" : "032-000",
    "accountNumber": "123410"
}

To generate a single-use-token for a New Zealand bank account 

{
    "supplierBusinessCode": "MYSUPPLIER",
    "accountType" : "DIRECT_DEBIT_NZ",
    "nzAccountName" : "Jane Smith",
    "nzBankCode" : "15",
    "nzBranchCode": "01",
    "nzAccountNumber": "123416",
    "nzAccountSuffix": "01"
}

To generate a 3D Secure single-use-token for a card account from fully PCI DSS compliant software: 

{
    "accountType" : "CREDIT_CARD",
    "cardholderName" : "Amira Spenar",
    "cardNumber" : "4242424242424242",
    "expiryDateMonth": "12",
    "expiryDateYear": "2027",
    "cvn": "123",
    "supplierBusinessCode": "MYSUPPLIER",
    "threeDS2": true,
    "browserProfile": {
        "browserJavaEnabled": true,
        "browserLanguage": "en",
        "browserColorDepth": "1",
        "browserScreenHeight": "1000",
        "browserScreenWidth": "2000",
        "browserTZ": "60"
    }
}

Response

If you send valid fields a Single-use-token model is returned:

  • a singleUseTokenId is returned in the response,
  • the masked credit card or bank account details and surcharge percentage are returned in the response for you to use in a confirmation step,
  • the credit card or bank account details are stored in QuickStream for 10 minutes,
  • you should send the singleUseTokenId in a request to take a payment or register an account.
Single use token model
Field Format Data
links Array of Links Links to related resources and documentation.
singleUseTokenId string The single-use-token.
accountType string CREDIT_CARD, DIRECT_DEBIT, DIRECT_DEBIT_NZ, APPLE_PAY, GOOGLE_PAY.
creditCard Credit Card For credit card account types, masked account information and surcharge percent.
bankAccount Bank Account For Australian bank account payments, masked account information.
nzBankAccount New Zealand Bank Account For New Zealand bank account payments, masked account information.
Credit card model
Field Format Description
cardNumber string Masked credit card number displaying the first 6 and last 3 digits.
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.
surchargePercentage string Percentage added to payments for the credit card type.
maskedCardNumber4Digits string Masked credit card number displaying the first 6 and last 4 digits.
threeDS2AuthRequired boolean true indicates that you must perform a 3D Secure Authenication call prior to taking a payment or tokenising the card.
threeDS2 object 3D Secure browser information.
threeDS2Status string A status indicating the state of the 3D Secure authentication flow.
Bank account model
Field Format Description
accountName string Name of account holder.
bsb string The masked bank-state-branch holding their account.
accountNumber string The masked account number at that branch.
New Zealand bank account model
Field Format Description
nzAccountName string Name of account holder.
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.
HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED You may have used a Secret API Key instead of your Publishable API Key, or your key has expired. View more.
422 UNPROCESSABLE ENTITY If you send invalid fields, you will receive a 422 Unprocessable Entity response.
429 TOO MANY REQUESTS You may have exceed your token quota. View more.
Example responses
{
  "links": [],
  "singleUseTokenId": "6a8f86e6-dfc0-4306-b07d-c7df137234aa",
  "accountType": "CREDIT_CARD",
  "creditCard": {
    "cardNumber": "424242...242",
    "expiryDateMonth": "01",
    "expiryDateYear": "17",
    "cardScheme": "VISA",
    "cardType": "CREDIT",
    "cardholderName": "Jane Smith",
    "cardType": "CREDIT",
    "maskedCardNumber4Digits": "424242...4242",
    "surchargePercentage": "0.400"
  }
}

Example Apple Pay response body:

{
  "links": [],
  "singleUseTokenId": "6a8f86e6-dfc0-4306-b07d-c7df137234aa",
  "accountType": "APPLE_PAY"
}

Example Google Pay response body:

{
  "links": [],
  "singleUseTokenId": "6a8f86e6-dfc0-4306-b07d-c7df137234aa",
  "accountType": "GOOGLE_PAY"
}

3D Secure Authentication

Authentication is the process of confirming that the person making an e-commerce transaction is entitled to use the payment card.

When you generate a single use token and the response indicates creditCard.threeDS2AuthRequired=true, your next step is to authenticate.

Request

POST /single-use-tokens/{singleUseTokenId}/three-ds2-authentication

Use your Secret API key to access this resource.

Request body

To authenticate the card stored in a single-use token using 3D Secure, send these fields:

You should send an Idempotency-Key to ensure authentication requests are not duplicated if there is a network problem.

Authentication Purpose

Send these fields when authenticating a card.

Field Format Data
messageCategory string

Required. How you will use the single-use token.

01 Payment authentication. If you will use the token to conduct a payment.
02 Non-payment authentication. If you will use the token to store the card details.
threeDSRequestorAuthenticationInd string

Required. The reason for the authentication request.

01 Payment transaction
02 Recurring transaction
03 Instalment transaction
04 Add card
05 Maintain card
06 Cardholder verification as part of EMV token ID&V
Purchase Information

If you will immediately conduct a payment or a recurring series of payments, send these fields when authenticating a card.

Field Format Data
principalAmount string Required for payment, recurring and instalment transactions. Purchase amount before any surcharge is added by QuickStream.
currency string Required for payment, recurring and instalment transactions. AUD
recurringExpiry string Required for recurring and instalment transactions. Date after which no further payments shall be performed. Format YYYYMMDD.
recurringFrequency string Required for recurring and instalment transactions. The minimum number of days between authorisations. e.g. 28. Max 9999.
purchaseInstalData string Required for instalment transactions. Required if you and Cardholder have agreed to instalment payments. The maximum number of authorisations permitted for instalment payments. Max 999.
Merchant Risk Indicator

Information about the specific purchase by the cardholder.

Field Format Data
deliveryEmailAddress string Optional. For electronic delivery, the email address to which the merchandise will be delivered. Max 254 characters.
deliveryTimeframe string

Optional. Your delivery timeframe.

01 Electronic Delivery
02 Same day shipping
03 Overnight shipping
04 Two-day or more shipping
giftCardAmount string Optional. For prepaid or gift card purchases, the purchase amount total of prepaid or gift cards in whole dollars (e.g. AUD 123.45 is 123). Max 15 characters.
giftCardCount string Optional. For prepaid or gift card purchases, the total count of individual prepaid or gift cards/codes purchased. (e.g. 2 is 02). Exactly 2 digits.
giftCardCurr string Optional. For prepaid or gift card purchases, the ISO-4217 three-digit currency code of the gift card. E.g. 036 for AUD.
preOrderDate string Optional. For a pre-ordered purchase, the expected date that the merchandise will be available. Format YYYYMMDD.
preOrderPurchaseInd string

Optional. Indicates whether the cardholder is placing an order for merchandise with a future availability or release date.

01 Merchandise available
02 Future availability
reorderItemsInd string

Optional. Indicates whether the cardholder is reordering previously purchased merchandise.

01 First time ordered
02 Reordered
shipIndicator string

Optional. Indicates the shipping method chosen for the transaction.

You must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not your general business.

If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.

01 Ship to cardholder's billing address
02 Ship to another verified address you hold on file
03 Ship to address that is different than the cardholder's billing address
04 Ship to Store / Pick-up at local store (Store address shall be populated in shipping address fields)
05 Digital goods (includes online services, electronic gift cards and redemption codes)
06 Travel and Event tickets, not shipped
07 Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)
Cardholder Contact Details

Use international format for phone numbers. e.g. +61499999999.

Field Format Data
email string Optional. The email address associated with the account that is either entered by the cardholder, or that you have on file. Max 254 characters.
homePhone string Optional. The home phone number provided by the cardholder. Max 15 characters.
mobilePhone string Optional. The mobile phone number provided by the cardholder. Max 15 characters.
workPhone string Optional. The work phone number provided by the cardholder. Max 15 characters.
Billing Address

These fields contain the billing address associated with the card. The billing address is required if you will use the token to conduct a payment, and recommended if you will use the token to store the card details.

Field Format Data
billAddrLine1 string Optional. First line of the street address or equivalent local portion. Max 50 characters.
billAddrLine2 string Optional. Second line of the street address or equivalent local portion. Max 50 characters.
billAddrLine3 string Optional. Third line of the street address or equivalent local portion. Max 50 characters.
billAddrCity string Optional. The city of the billing address. Max 50 characters.
billAddrPostCode string Optional. ZIP or other postal code of the billing address. Max 16 characters.
billAddrState string Optional. The state or province. Max 3 characters. Use the ISO 3166-2 country subdivision code. e.g. NSW.
billAddrCountry string Optional. Use the ISO 3166-1 numeric three-digit country code. e.g. 036.
Shipping Address

Send these fields if you will ship physical goods to the cardholder:

Field Format Data
addrMatch string Optional. Y is Shipping Address matches Billing Address, otherwise N.
shipAddrLine1 string Optional. First line of the street address or equivalent local portion. Max 50 characters.
shipAddrLine2 string Optional. Second line of the street address or equivalent local portion. Max 50 characters.
shipAddrLine3 string Optional. Third line of the street address or equivalent local portion. Max 50 characters.
shipAddrCity string Optional. The city of the shipping address. Max 50 characters.
shipAddrPostCode string Optional. ZIP or other postal code of the shipping address. Max 16 characters.
shipAddrState string Optional. The state or province. Max 3 characters. Use the ISO 3166-2 country subdivision code. e.g. NSW.
shipAddrCountry string Optional. Use the ISO 3166-1 numeric three-digit country code. e.g. 036.
Cardholder Account Information

These fields contain optional information about the cardholder account on your website. Fields used to define a time period can be included as either the specific date, or an approximate indicator for when the action occurred. You can use either format.

If the cardholder has not signed in to your website, send these fields:

Field Format Data
chAccAgeInd string

Optional. The length of time that the cardholder has had the account with you.

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
paymentAccInd string

Optional. The length of time that the payment account was enrolled in the cardholder's account with you.

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days

If the cardholder has signed in to your website, send these fields:

Field Format Data
acctID string Optional. Cardholder Account Identifier. Additional information about the account optionally provided by you. Max 64 characters.
chAccAgeInd string

Optional. Indicates the length of time that the cardholder has had the account with you.

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
chAccChange string Optional. The date that the cardholder's account with you was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Format YYYYMMDD.
chAccChangeInd string

Optional. The length of time since the cardholder's account information with you was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

01 Changed during this transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days
chAccDate string Optional. The date that the cardholder opened the account with you. Format YYYYMMDD.
chAccPwChange string Optional. The date that cardholder's account with you had a password change or account reset. Format YYYYMMDD.
chAccPwChangeInd string

Optional. Indicates the length of time since the cardholder's account with you had a password change or account reset.

01 No change
02 Changed during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
nbPurchaseAccount string Optional. The number of purchases with this cardholder account during the previous six months. Max 9999.
paymentAccAge string Optional. The date that the payment account was enrolled in the cardholder's account with you. Format YYYYMMDD.
paymentAccInd string

Optional. Indicates the length of time that the payment account was enrolled in the cardholder's account with you.

01 No account (guest check-out)
02 Created during this transaction
03 Less than 30 days
04 30-60 days
05 More than 60 days
provisionAttemptsDay string Optional. The number of Add Card attempts in the last 24 hours. Max 999.
shipAddressUsage string Optional. The date when the shipping address used for this transaction was first used with you. Format YYYYMMDD.
shipAddressUsageInd string

Optional. Indicates when the shipping address used for this transaction was first used with you.

01 This transaction
02 Less than 30 days
03 30-60 days
04 More than 60 days
shipNameIndicator string

Optional. Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.

01 Account Name identical to Shipping Name
02 Account Name different to Shipping Name
suspiciousAccActivity string

Optional. Indicates whether you have experienced suspicious activity (including previous fraud) on the cardholder account.

01 No suspicious activity has been observed
02 Suspicious activity has been observed
txnActivityDay string Optional. The number of transactions (successful and abandoned) for this cardholder account across all payment accounts in the previous 24 hours. Max 999.
txnActivityYear string Optional. The number of transactions (successful and abandoned) for this cardholder account across all payment accounts in the previous year. Max 999.

Response

If successful, this method returns a 3D Secure Authentication Response Model in the response body.

3D Secure Authentication Response Model

The 3D Secure authentication response indicates the outcome of the authentication.

Field Format Description
transStatus string

Use the transStatus to choose what to do next.

A Frictionless Flow
C Challenge Flow
N Authentication Failed
R Authentication Failed
U Authentication Failed
Y Frictionless Flow
Frictionless Flow (A or Y)

The Frictionless Flow does not require further cardholder interaction to achieve a successful authentication and complete the 3D Secure authentication process.

If you receive a A or Y response, you must send a request with threeDS2=true to:

Challenge Flow (C)

Further cardholder interaction is required to complete the authentication.

If you receive a C response, you must display a web page containing a challenge iFrame. To do this, call the javascript function quickstreamapi.creditCards.createChallengeFrame.

After the challenge has been attempted, you will receive an updated transStatus or javascript callback to allow you to continue.

Authentication Failed (N, R or U)

If you receive a N or R or U response, you must display a web page indicating that authentication has failed.

Do not take a payment or register an account.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded. Use transStatus to determine the next step.
401 UNAUTHORIZED You may have used a Secret API Key instead of your Publishable API Key, or your key has expired. View more.
404 NOT FOUND The singleUseTokenId provided in the path is invalid or has expired.
422 UNPROCESSABLE ENTITY If you send invalid fields, you will receive a 422 Unprocessable Entity response.
429 TOO MANY REQUESTS You may have exceed your token quota. View more.
503 FORBIDDEN 3DS2 not allowed for community - Your QuickStream facility is not enabled for 3D Secure. To enable it you must contact your Westpac representative.

Example request and response

{
    "messageCategory": "01",
    "threeDSRequestorAuthenticationInd": "01",
    "principalAmount": "10.00",
    "currency": "AUD",
    "recurringExpiry": "20240926",
    "recurringFrequency": "31",
    "purchaseInstalData": "6",
    "deliveryEmailAddress": "customer@example.com.au",
    "deliveryTimeframe": "02",
    "giftCardAmount": "124",
    "giftCardCount": "02",
    "giftCardCurr": "036",
    "preOrderDate": "20210926",
    "preOrderPurchaseInd": "02",
    "reorderItemsInd": "02",
    "shipIndicator": "02",
    "email": "customer@example.com.au",
    "homePhone": "+61499999999",
    "mobilePhone": "+61499999999",
    "workPhone": "+61499999999",
    "billAddrLine1": "Shop 11",
    "billAddrLine2": "Level 2",
    "billAddrLine3": "New Village",
    "billAddrCity": "Newcastle",
    "billAddrPostCode": "2000",
    "billAddrState": "NSW",
    "billAddrCountry": "036",
    "addrMatch": "Y",
    "shipAddrLine1": "Shop 11",
    "shipAddrLine2": "Level 2",
    "shipAddrLine3": "New Vilage",
    "shipAddrCity": "Newcastle",
    "shipAddrPostCode": "2000",
    "shipAddrState": "NSW",
    "shipAddrCountry": "036",
    "acctID": "CUST12345678",
    "chAccAgeInd": "01",
    "chAccChange": "20220926",
    "chAccChangeInd": "01",
    "chAccDate": "20220926",
    "chAccPwChange": "20220926",
    "chAccPwChangeInd": "01",
    "nbPurchaseAccount": "2",
    "paymentAccAge": "20220926",
    "paymentAccInd": "01",
    "shipAddressUsage": "20220926",
    "shipAddressUsageInd": "03",
    "provisionAttemptsDay": "2",
    "shipNameIndicator": "02",
    "suspiciousAccActivity": "02",
    "txnActivityDay": "2",
    "txnActivityYear": "61"
}
{
  "transStatus": "Y"
}
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.