Single-Use-Tokens API

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.

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

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 and Custom Form.

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 CREDIT_CARD, DIRECT_DEBIT or 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.

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

{
    "supplierBusinessCode": "MYSUPPLIER",
    "accountType" : "CREDIT_CARD",
    "cardholderName" : "Jane Smith",
    "cardNumber" : "4242424242424242",
    "expiryDateMonth": "12",
    "expiryDateYear": "2022",
    "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"
}

Response

If successful, the following is returned in the response body.

Example response body

{
  "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",
    "maskedCardNumber4Digits": "424242...4242",
    "surchargePercentage": "0.400"
  }
}

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 or DIRECT_DEBIT_NZ.
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.

Credit card model

Field Format Description
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.
surchargePercentage string Percentage added to payments for the credit card type.
maskedCardNumber4Digits string Masked credit card number displaying last 4 digits.

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.

If you send valid fields:

  • 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.

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.