Transactions API

Transactions include payments, refunds and preauths. Using this API you can:

• process payments for a card, bank account or PayTo Agreement.
• perform pre-auth transactions using a card account.
• void a transaction to cancel it prior to settlement.
• refund a card, bank account or PayTo payment.
• search and get details of transactions, regardless of how they were originally processed
• download CSV transaction reports for a settlement date.

Besides this API, QuickStream has other ways to take payments.

Get

Use this resource to get the details of a transaction. You can take the following actions on a transaction:

• List refunds of a transaction.
• List retries of a transaction.
• Void a transaction to cancel it when voidable is true.
• Partially or fully refund a transaction when refundable is true.

Request

GET /transactions/{receiptNumber}

Use your Secret API key to access this resource.

Path parameters

Request body

None.

Response

If successful, this method returns a Transaction Response Model in the response body.

Transaction response

{
  "links": [],
  "receiptNumber": "1234567890",
  "transactionType": "PAYMENT",
  "status": "Approved",
  "responseCode": "08",
  "responseDescription": "Honour with identification",
  "summaryCode": "0",
  "fraudGuardResult": null,
  "customerReferenceNumber": "CUSTOMER1",
  "paymentReferenceNumber": "INVOICE1",
  "comment": "Credit card payment for Jane Smith.",
  "source": "RESTAPI",
  "settlementDate": "2017-01-01",
  "transactionTime": "2017-01-01T10:26:36+1000",
  "refundable": false,
  "voidable": true,
  "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"
  },
  "merchantAccount": {
    "merchantId": "12345678",
    "merchantName": "My Westpac Account",
    "settlementBsb": "032-002",
    "settlementAccountNumber": "1234576",
    "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"
  },
  "metadata": {
    "extraInformation": "123456789",
    "moreInformation": "testData"
  }
}

HTTP status codes

See HTTP Status Codes for more.

List

List recent transactions

List up to your 20 most recent transactions on the current settlement date across your businesses. Provide supplierBusinessCode to list filter those transactions for that business.

Request

GET /transactions?supplierBusinessCode={code}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

The most recent transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List by reference number

List transactions by reference number. Use this resource to find transactions by Receipt, Customer Reference, Payment Reference Number or PayTo End-To-End ID.

Request

GET /transactions/for-reference-number?referenceNumber={string}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List by settlement date

Use this resource to list transactions by settlement date. Settlement is the process of paying you for transactions which have been processed. The Settlement Date is the day on which a transaction was considered to have been processed.

See Transaction Settlement for more.

Request

GET /transactions/for-settlement-date?settlementDate={date}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List by account token

Use this resource to list transactions taken for an Account Token.

Credit card and bank accounts are registered for customers. The unique identifier for a customer's credit card or bank account is a called an account token. Use an account token to take payments for those accounts. Use the Customers API to manage their account tokens.

Request

GET /transactions/for-account-token?accountToken={string}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List by credit card

Use this resource to list transactions taken using a credit card. Provide the first 6 and last 3 digits of the credit card number to search.

Request

GET /transactions/for-credit-card?firstSix={number}&lastThree={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List by bank account

Use this resource to list transactions taken using an Australian bank account. Provide the BSB and Account Number of the payment bank account to search.

Request

GET /transactions/for-bank-account?bsb={string}&accountNumber={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

HTTP status codes

See HTTP Status Codes for more.

List by New Zealand bank account

Use this resource to list transactions taken using an New Zealand bank account. Provide the Bank Code and Branch Code and Account Number of the payment bank account to search.

Request

GET /transactions/for-nz-bank-account?bankCode={number}&branchCode={number}&accountNumber={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

HTTP status codes

See HTTP Status Codes for more.

List suspended transactions

Use this resource to list transactions suspended by Fraud Guard. A transaction is suspended when Fraud Guard has deemed it suspicious based on the rules you have configured in QuickStream. Fraud Guard sets the transaction response code to 34 - Suspected Fraud.

Sign in to QuickStream to complete or cancel a transaction.

Request

GET /transactions/suspended?supplierBusinessCode={code}&month={YYYY-MM}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

HTTP status codes

See HTTP Status Codes for more.

List refunds of a transaction

Use this resource to list refunds of a transaction. A transaction may be refunded for the full amount, or a partial amount. The transactions returned by this resource make up the total amount of this transaction refunded to your customer.

Request

GET /transactions/{receiptNumber}/refunds

Use your Secret API key to access this resource.

Path parameters

Request body

None.

Response

This is a paginated resource. The most recent refund transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List retries of a transaction

Use this resource to list the retries of a failed transaction.

Transactions that have been soft-declined by the account holder's financial institution can be retried and may be successful in the future. A failed transaction may be retried manually or automatically by configuring a schedule.

When a transaction is retried, a new transaction is attempted. This resource lists the retry attempts of a transaction.

Request

GET /transactions/{receiptNumber}/retries

Use your Secret API key to access this resource.

Path parameters

Request body

None.

Response

This is a paginated resource. The most recent retry transaction is first.

HTTP status codes

See HTTP Status Codes for more.

List returned transactions

Use this resource to list Australian bank account transactions that have been returned on a certain date. A returned transaction is one that has been declined by the customer's bank. See Bank account transaction settlement for more information.

Request

GET /transactions/returns?date={YYYY-MM-DD}&supplierBusinessCode={code}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

HTTP status codes

See HTTP Status Codes for more.

List open pre-authorisations

Use this resource to list initial pre-authorisation or a re-authorisation transactions that have not been captured. You can capture against an initial pre-authorisation or a re-authorisation transaction.

Request

GET /transactions/open-preauths?month={YYYY-MM}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Request body

None.

Response

The most recent open pre-authorisation for the month is first.

HTTP status codes

See HTTP Status Codes for more.

Take payment

Use this resource to take card or bank account payments. You can provide account details directly, using a single-use-token, a tokenised card or bank account, or a PayTo Agreement Token.

Request

POST /transactions

Use your Secret API key to access this resource.

{
    "transactionType" : "PAYMENT",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1",
    "storedCredentialData": {
      "entryMode" : "MANUAL"
    }
}

{
    "transactionType": "PAYMENT",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "RECURRING",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage" : "RECURRING"
    }
}

{
    "transactionType": "PAYMENT",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "RECURRING",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage" : "STANDING_ORDER"
    }
}

{
    "transactionType" : "PAYMENT",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1",
    "storedCredentialData": {
      "entryMode" : "MANUAL"
    }
}

{
    "transactionType" : "PAYMENT",
    "bankAccount": {
        "accountName": "Jane Smith",
        "bsb": "032-002",
        "accountNumber": "123465"
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}

{
    "transactionType" : "PAYMENT",
    "payToData": {
        "endToEndId": "INV-123456790",
        "remittanceInformation1": "PAYMENT TO CUSTOMERA",
        "finalPayment": false,
        "agreementToken": "CUST123456789"
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}

{
    "transactionType" : "PAYMENT",
    "payToData": {
        "endToEndId": "INV-123456790",
        "remittanceInformation1": "ECOM PAYMENT TO CUSTOMERA",
        "payToAgreement" : {
            "supplierBusinessCode": "MYBUSINESS",
            "paymentDetails": {
                "purpose": "RETL",
                "description": "Your license renewal payment."
            },
            "payerDetails": {
                "payerType": "PERS",
                "payerId": "PS19400650001",
                "payerName": "FIRSTNAME SURNAME",
                "payerReference": "PY19000890013",
                "payIdType": "EMAL",
                "payId": "FIRSTNAME.SURNAME@MYCUSTOMER.COM.AU"
            }
        }
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}

Request body

You must handle errors and avoid duplicate transactions.

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Void payment

Use this resource to void a transaction.

If you void a transaction, it will not appear on your customer's statement or form part of your settlement total. To determine if a transaction can be voided, get the transaction details and use the voidable field.

Request

POST /transactions/{receiptNumber}/void

Use your Secret API key to access this resource.

Path parameters

Request body

None.

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Refund payment

Use this resource to refund a payment.

To determine if a payment can be refunded, get the transaction details and use the refundable field. The refund will credit the bank account or credit card used on the payment. You can never refund more than the payment amount, and you may only refund the full amount for PayTo payments.

You can list the refunds of a transactions.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Refund a transaction

{
    "originalReceiptNumber": "1204957934",
    "transactionType" : "REFUND",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "REFUND1",
    "currency" : "AUD",
    "comment" : "Refund a payment for Jane Smith."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Pre-authorisations

Pre-authorisation

Use this resource to pre-authorise a card payment. Later, capture the pre-authorisation to charge the card. Approved pre-authorisation transactions that have not yet been captured are listed in QuickStream Portal.

See Mastercard and Visa pre-authorisation for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions.

Fraud Guard is initiated on pre-authorisation. Pre-authorisations available for capture have already passed fraud guard validation.

To process a single-use-token pre-authorisation:

{
    "transactionType" : "PREAUTH",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1",
    "storedCredentialData": {
      "entryMode" : "MANUAL"
    }
}

To process a pre-authorisation using a customer's default tokenised account:

{
    "transactionType": "PREAUTH",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "MAIL",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage": "UNSCHEDULED_MIT"
    }
}

To process a pre-authorisation using a specified tokenised account:

{
    "transactionType": "PREAUTH",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 20.00,
    "currency": "AUD",
    "eci": "MAIL",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage": "UNSCHEDULED_MIT"
    }
}

To process a direct pre-authorisation:

{
    "transactionType" : "PREAUTH",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 30.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1",
    "storedCredentialData": {
      "entryMode" : "MANUAL"
    }
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Capture pre-authorisation

Use this resource to capture a pre-authorisation. You can capture a pre-authorisation only once, for an amount up to double the pre-authorised amount.

Use List open pre-authorisations to find initial or a re-authorisation pre-authorisations that have not been captured. You can capture against an initial or a re-authorisation pre-authorisation.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Capture a pre-authorisation

{
    "originalReceiptNumber": "1204957935",
    "transactionType": "CAPTURE",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CAPTUREPREAUTH1",
    "currency": "AUD",
    "comment" : "Capturing a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Cancel a pre-authorisation

Use this resource to partially or fully cancel a pre-authorisation. You must perform the cancellation against the original successful Visa/Mastercard pre-authorisation transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

To perform a full cancellation of a pre-authorisation you must:

• send cancellationType = FULL
• send the full amount of the original pre-authorisation in principalAmount.

To perform a partial cancellation of a pre-authorisation you must:

• send cancellationType = PARTIAL
• send the partial amount of the outstanding balance that you wish to cancel of the original pre-authorisation in principalAmount.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Full cancellation of a pre-authorisation

{
    "originalReceiptNumber": "1204957975",
    "transactionType" : "PREAUTH_CANCELLATION",
    "cancellationType" : "FULL",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CANCELPREAUTH1",
    "currency" : "AUD",
    "comment" : "Fully cancelling a pre-authorisation."
}

Partial cancellation of a pre-authorisation

{
    "originalReceiptNumber": "1204957976",
    "transactionType" : "PREAUTH_CANCELLATION",
    "cancellationType" : "PARTIAL",
    "principalAmount": 1.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CANCELPREAUTH2",
    "currency" : "AUD",
    "comment" : "Partially cancelling a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Incremental pre-authorisation

Use this resource to top-up the original amount of a pre-authorisation. You must perform the incremental pre-authorisation transaction against the original successful Visa/Mastercard pre-authorisation transaction.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Incremental pre-authorisation (aka Top-Up)

{
    "originalReceiptNumber": "1204957977",
    "transactionType" : "PREAUTH",
    "authorisationType" : "INCREMENTAL",
    "principalAmount": 2.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "INCREMEMTALPREAUTH1",
    "currency" : "AUD",
    "comment" : "Top-up a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Extension pre-authorisation

Use this resource to extend an original Mastercard pre-authorisation to the maximum validity period supported by the card scheme. You must perform the extension transaction against the original successful Mastercard pre-authorisation transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Extension pre-authorisation

{
    "originalReceiptNumber": "1204957978",
    "transactionType" : "PREAUTH",
    "authorisationType" : "EXTENSION",
    "principalAmount": 0.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "EXTENSIONPREAUTH1",
    "currency" : "AUD",
    "comment" : "Extend a Mastercard pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Re-authorisation pre-authorisation

Use this resource to re-authorise an original Visa pre-authorisation that has expired after the validity period supported by the card scheme.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Re-authorisation pre-authorisation

{
    "originalReceiptNumber": "1204957979",
    "transactionType" : "PREAUTH",
    "authorisationType" : "REAUTHORISATION",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "REAUTHORISATIONPREAUTH1",
    "currency" : "AUD",
    "comment" : "Re-authorise a Visa pre-authorisation after it expired."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Account verification

Use this resource to perform an account verification transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

To process a single-use-token account verification:

{
    "transactionType" : "ACCOUNT_VERIFICATION",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

To process an account verification using a customer's default tokenised account:

{
    "transactionType": "ACCOUNT_VERIFICATION",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency": "AUD",
    "eci": "MAIL",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage": "UNSCHEDULED_MIT"
    }
}

To process an account verification using a specified tokenised account:

{
    "transactionType": "ACCOUNT_VERIFICATION",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency": "AUD",
    "eci": "MAIL",
    "storedCredentialData": {
      "entryMode" : "STORED_CREDENTIAL",
      "usage": "UNSCHEDULED_MIT"
    }
}

To process a direct account verification:

{
    "transactionType" : "ACCOUNT_VERIFICATION",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYSUPPLIER",
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1",
    "storedCredentialData": {
      "entryMode" : "MANUAL"
    }
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Download CSV report

Use this resource to download a CSV report of transactions for a settlement date.

Request

GET /transactions/csv

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Headers

Request body

None.

Response

If successful, this method returns a 202 when the report is generated. A subsequent request resulting in a 200 HTTP status code will download the CSV report.

HTTP status codes

See HTTP Status Codes for more.

Transaction report formats

The following transaction report formats are available:

• CSV transaction report version 2 - The preferred format.
• CSV transaction report version 1 - Legacy format.

The reports are plain text using UTF-8 character encoding. All records except the last are separated by the CR LF end-of-line marker. Fields may be enclosed in double quotes. If double quotes enclose a field, then a double quote appearing inside a field is escaped by preceding it with another double quote.

Refer to the CSV transaction report file format.

Request models

Credit card request model

Credit card refund request model

PayTo data request model

Bank account request model

New Zealand bank account request model

Stored credential data request model

Stored credential transactions

A stored credential is card data that is stored by a merchant or its agent to process future purchases on behalf of the cardholder. This generally consists of the card number, expiry date and cardholder name. There are different data requirements for an initial transaction vs subsequent transactions. The parameters that merchants must send for Visa and Mastercard cards are outlined in the table below.

MPGS data request model

Metadata model

Metadata may be used to store extra information about a transaction. It is represented as an object with up to 20 key/value string pairs. Data in a request body not conforming to the following format will result in a 422 Unprocessable Entity response.

Example metadata object

{
    "metadata": {
      "serialCode": "18777-231-2A",
      "sequenceNumber": "005",
      "customerPackage": "Basic (BAPK)"
    }
}

Response models

Transaction response model

Example credit card transaction response

{
  "receiptNumber": "1234567890",
  "transactionType": "PAYMENT",
  "status": "Approved",
  "responseCode": "08",
  "responseDescription": "Honour with identification",
  "summaryCode": "0",
  "fraudGuardResult": null,
  "customerReferenceNumber": "CUSTOMER1",
  "paymentReferenceNumber": "INVOICE1",
  "comment": "Credit card payment for Jane Smith.",
  "source": "RESTAPI",
  "settlementDate": "2017-01-01",
  "transactionTime": "2017-01-01T10:26:36+1000",
  "refundable": false,
  "voidable": true,
  "supplierBusinessCode": "MYBUSINESS",
  "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"
  },
  "merchantAccount": {
    "merchantId": "12345678",
    "merchantName": "My Westpac Account",
    "settlementBsb": "032-002",
    "settlementAccountNumber": "1234576",
    "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"
  },
  "metadata": {
    "extraInformation": "123456789",
    "moreInformation": "testData"
  },
  "links": [],
  "debtRepayment": false
}

Transaction status

See Response Codes for more.

Credit card model

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

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

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

Merchant account model

Example merchant accounts response

{
   "merchantId":"12345678",
   "merchantName":"My Westpac Account",
   "settlementBsb":"032-002",
   "settlementAccountNumber":"123465",
   "settlementSurchargeBsb": "032-002",
   "settlementSurchargeAccountNumber": "1234576",
   "displayName":"Your Company 032-002 123465 (12345678)",
   "acquiringInstitution": "WBC",
   "currency": "AUD"
}

Direct entry account model

Example Australian Direct Entry Accounts response

{
  "accountName": "My Bank Account",
  "displayName": "My Bank Account 032-002 123465 (411111)",
  "currency": "AUD",
  "directEntryUserId": "411111",
  "directEntryUserName": "My Company",
  "settlementBsb": "032-002",
  "settlementAccountNumber": "123465"
}

To change the remitterName:

1. Sign-in to QuickStream Portal.
2. Click on Administration -> Business Settings.
3. Search for your business.
4. Click on View Settlement Accounts linked to this business.

New Zealand direct entry account model

Example New Zealand direct entry account response

{
  "nzAccountName": "My Bank Account",
  "displayName": "My Bank Account 010001-0000002-00 (NZ Account)",
  "currency": "NZD",
  "debitUserId": null,
  "nzBankCode": "01",
  "nzBranchCode": "0001",
  "nzAccountNumber": "0000002",
  "nzAccountSuffix": "00"
}

PayTo data model

PayTo Payer account model

PayTo Payee account model

Processing transactions

There are several ways to specify the account used to perform transactions:

• Process transaction using a single-use-token - for accepting one-time transactions through a webpage or application. The easiest way to make these requests is to use Trusted Frame.
• Process transaction using tokenised account - for accepting transactions from an account that has been registered for a customer previously.
• Process transaction using account details - for accepting one-time transactions through your own server. Using this type of request will mean credit card data may be passing through your system. As a result, there may be extra PCI DSS considerations for your environment.

You should avoid processing duplicate transactions.

If you are an Aggregator or Staged Digital Wallet Operator you may provide soft-descriptors in the Transaction Request Model.

Avoid duplicate transactions

To avoid processing duplicate transactions:

• send a unique Idempotency-Key.
• if you receive a network error, resend the request with the same Idempotency-Key.
• if you receive 500 Internal Server Error, contact Technical Support.
• if you receive 503 Service Unavailable, the payment has not been processed. Wait 20 seconds and resend the request with a new idempotency key. Contact Technical Support if you continue to experience problems.

Process transaction using a single-use-token

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

To process a one-time credit card or bank account transaction, first generate a single-use-token and then include it in the Transaction Request Model singleUseTokenId field.

You can use single-use-tokens to process:

• Payments.
• Pre-authorisations.
• Account verifications.

Process transaction using a tokenised account

To process a transaction using a tokenised account, you will need a customer with a registered account.

The payment can be made by including one of the two fields below in the request body:

• the customerId representing a customer that has an enabled default tokenised account.
• the accountToken representing an enabled tokenised account.

You can use tokenized accounts to process:

• Payments.
• Pre-authorisations.
• Account verifications.

Process transaction using account details

To process a transaction using account details directly in the request, include a Credit Card Request Model or Bank Account Request Model in the Transaction Request Model creditCard or bankAccount fields.

You can use account details to process:

• Payments.
• Pre-authorisations.
• Account verifications.

Process transaction using PayTo Agreement Token

To process a transaction using a PayTo Agreement Token, you will need a customer with a Payto Agreement.

The payment can be made by including the agreementToken representing an active PayTo Agreement.

You may also provide additional information in the paytoData request object.

Electronic Commerce Indicator

The Electronic Commerce Indicator (ECI) is used by acquirers / issuers to determine the type of transaction being processed, representing the source of the transaction request. When using an ECI of INTERNET a CVN should be provided.

Soft descriptors for aggregators

Soft-descriptors are informational fields that Aggregators must collect for each transaction about a sub-merchant. These merchant descriptor fields allow some control over the cardholder narrative for each transaction. The fields below can be provided in the request body containing details of your sub-merchant. If you provide one field, you must provide all fields.

Transaction settlement

See Transaction Processing and Settlement.

Response codes

See Response Codes.

Test account numbers

To help with the testing process we provide a list of account numbers for you to use. See Test Account Numbers.