Web Application Payment Integrations¶

The integration provides third party payment integrators (in particular ordering platforms, although potentially any web based platform could work) with the ability to charge a Tidy/Aston customer via a combination of Javascript SDK and a HTTP API. The javascript library provides functions required to communicate with Tidy mobile apps (Android & iOS) in a unified manner.

Using the javascript API requires the inclusion of the tidy.js script in the web application. See below for more information. This script only needs to be included in the steps requiring checkout/purchase, and retrieving customer information. A minified version tidy.min.js is also provided.

Prerequisites¶

The following items are required from the integrating partner's platform to be suitable for this integration:

Must provide a web (browser) based user interface for the customer to place their order.
Must provode a guest checkout flow (customers are not required to sign up to order).
- Note: it is also possible for Tidy to initialise a session, then redirect to the web application passing in a session ID or token as a query string parameter. More on this is discussed here.

Overview¶

Components¶

The web application needs to integrate in 2 places:

With the Tidy mobile application using the javascript library.
With the Aston payments API using HTTP.

Components

Basic Payment Flow¶

The following represents the payment flow at a high level from the perspective of a partner web application.

Your web application first uses the Javascript Tidy.payment() method to retrieve a customer-approved single-use token (nonce). This nonce (token) can then be used by your back-end servers to call our HTTP API and charge the customer.

Note

The nonce (token) is for a restricted to be used for a pre-approved amount, at a pre-approved merchant, is short lived, and single-use only.

Simplified Flow

Authentication / Security¶

There are 3 types of authentication to be considered for this integration:

Customer authentication to approve the payment and provide contact details for the order.
Application authentication, being an approved OAuth 2 client ID and secret.
Merchant authentication to approve your application in processing payments on behalf of the merchant.

Customer¶

The tidy.js library provides customer authentication automatically. All that needs to be done is include the library.

The Tidy application requires the user to interact and approve a payment, then uses the customer's access token to pre-approve the payment. A nonce for this payment is then returned to your web application.

Note

Because the customer is required to interact to authorise this payment there is the change to reject. In this case an error is returned. An error may also occur if the user has insufficient funds, an expired card, etc.

You do not need to persist any credentials or tokens for the customer side of a transaction. A nonce should be transient and discarded straight after use. A nonce is associated with a unique transaction ID. If you need to persist anything for reference you can fetch the transaction ID using the nonce with our API.

You may also fetch the customer's contact details required for their order using the javscript API methods. Typically these will be used to pre-fill the fields of a "guest check-out".

Important: in order to provide seamless order and payment process within a Tidy mobile application, a customer should not have to re-enter their name, email and phone or re-authenticate.

Application¶

Each application providing an integration requies a valid OAuth client ID and secret. At present only LOKE can generate these. Please contact LOKE if you require them.

Note

client credentials are unique to each environment. Credentials for our sandbox environment will not work in our production environment.

You will need to store your client credentials globally at a per-environment scope. You do not need different client credentials for each of your merchants.

Merchant¶

Your application will want to use the customer supplied nonce to charge the customer on behalf of a merchant - one of your clients.

In order to get access to charge a customer for this merchant you'll need to request permissions. This is done through the standard OAuth web authentication flow you'll be familiar with for connecting services like Google and Facebook.

Tip

Salesforce have a good overview of the flow here.

This process will yield a token with permissions for your client to this merchant. If you have an "integrations" or "connections" page already, this is a good place to add it, otherwise find an appropriate place in your merchant's settings.

The token received at the end of this process should be persisted for reuse (ie: the merchant should only have to go through this process once). You should also have a "disconnect" process to discard and forget the connection.

Note

Most ordering platforms have multiple "stores" or "sites" for each of their clients. In our system each "store" is considered a merchant. A group of merchants is called an organisation. You can request access to either a merchant (single site) or organisation (group of sites).

This is discussed in more details in the Back End (Merchant) Connection appendix below.

Refunds¶

There may be a need to refund a customer in a few situations, typically:

The merchant is unable to fulfill an order (out of stock or too busy) and has to refund.
Your back-end is unable to communicate to the store's on-site point of sale or tablet.

When this happens it is possible to refund the transaction by calling the refund HTTP endpoint.

Testing and Development¶

Because of the nature of this application (multiple integration points and mediums, only works when run inside webview), debugging can be a challenge.

For this reason we have provided sandbox.js. When included alongside tidy.js it emulates the mobile app and customer to make debugging in a browser possible.

Usage¶

To use this Sandbox method simply include the sandbox script BEFORE tidy.js, eg:

<script src="https://static.mytidyapp.com/tidywebsdk/current/sandbox.js"></script>
<script src="https://static.mytidyapp.com/tidywebsdk/current/tidy.js"></script>

Note

sandbox.js only works in our sandbox environment since it uses a hard-coded customer and card.

Note

sandbox.js isn't required to use our sandbox environment, however the only other option is to use our sandbox mobile app which makes this harder to debug.

Sample / Example¶

Want to see an example? The following page demonstrates how to use the sandbox environment and script (open up the browser inspector to check out the HTTP requests):

http://static.mytidyapp.com/tidywebsdk/current/test/sandbox.html

Appendix¶

Back End (Merchant) Connection¶

If you've ever added an integration to Slack, Xero, or something similar then you should be pretty familiar with expected connection process here. You might already have an integrations or connections section within your app. If so, that's the place for this to go. If not, you know your app best - pick the best place in your settings or configuration area.

Basic flow:

Merchant user logs in to your app and heads to settings->integrations or wherever the most appropriate configuration area is in you app.
Merchant user clicks "connect Aston Club" or "add Aston Club"
Web browser loads Aston Club's /authorize/organization URL (see the API > Authorization section below for more details)
User logs in with their Aston Club merchant login
User clicks the "Approve" button and is redirected back to your app
Your app receives the approval code via the URL and you can exchange this for a token
Your app now lists the Aston Club integration as "connected" or similar
You should also implement a disconnect function so that the merchant can remove the integration if they desire

Javascript SDK Location¶

Minified Version: https://static.mytidyapp.com/tidywebsdk/current/tidy.min.js
Debug Version: https://static.mytidyapp.com/tidywebsdk/current/tidy.js

Note: current always contains the latest version. You may specify also specify the version to protect against breaking changes, eg:

https://static.mytidyapp.com/tidywebsdk/v0.1.3/tidy.min.js

Note: Ideally you will only want to include these scripts under the right conditions. You may wish to selectively load these scripts only when accessed via a unique query string or URL parameter.

Javascript SDK Methods¶

The Tidy javascript library will provide a number of helper functions (getters) that assist in pre-populating fields to speed up an order, plus the payment method that handles setting up a transaction, and returning a payment nonce.

getFirstName() : string - get the user's first name
getLastName() : string - get the user's last name
getEmail() : string - get the user's email address
getGender() : string - get the user's gender
getPhone() : string - get the user's phone number in E.164 format (NOTE: may be null)
payment(order: Order, callback: NonceCallback) : void - request the user to pay for an order. Will callback with a nonce if successful.
complete(message: ?string) : void - calling complete prompts the containing activity to show a "Close" button indicating to the user that the process has ended. Optionally message can be provided for additional user feedback.
close() : void - calling close indicates to Tidy that the dialog or activity is complete. The application will close the dialog/activity without prompting.

An Order has the following type definition:

{
    orderStoreId: String,   // the third party store ID of the store to be charged for this order.
                                                  // NOTE: This will only work if the store-merchant mapping has been set up correctly.
  orderRef: ?String,            // optional reference ID (order ID, check ID, invoice ID). Only used for metadata.
  title: ?String,           // optional title of the order. will be displayed to the user in the prompt
  total: Integer,           // total amount of the order INCLUSIVE OF TAX in CENTS.
  tax: ?Integer,                // total amount of tax included in the order in CENTS. (Optional)
  items: [
    { // Note: items are just used for metadata - they are not verified against the total
      name: String,         // display or item name
      quantity: Integer, // quantity
      amount: Integer,  // total amount in cents (qty * item amount)
      tax: ?Integer         // tax included in above amount in cents (Optional)
    }
  ]
}

The NonceCallback has the following signature (node-style callback):

function(err: Error, {nonce: string}) : void ... where err is null when the operation was successful

HTTP API¶

URLs¶

Production: https://api.astonclub.com.au
Sandbox: https://sandbox.astonclub.com.au

Authorization¶

To use the API you will need a token obtained from the Auth Service.

To get this use the OAuth 2 code based flow to request an organization token as described here.

You will need to request the following scopes: aston-api:transaction.read and aston-api:transaction.submit.

Before you can do this you will need to get in touch with Aston Club support to have valid client credentials (a client ID and secret) created for you.

Get details about a pre-approved Transaction¶

THIS OPTIONAL STEP IS PERFORMED BY THE INTEGRATOR/PARTNER AND CAN BE USED TO CONFIRM THE DETAILS OF THE TRANSACTION THIS NONCE IS TIED TO.

GET /v5/nonces/{nonce}

Returns a nonce with a transaction:

{
  nonce: '237842378478234',
  transaction: {
    id: "56676c170a34466597769f59",
    createdAt: "2015-12-08T23:47:35.354Z",
    updatedAt: "2015-12-08T23:48:04.441Z",
    completedAt: "2015-12-08T23:48:03.543Z",
    merchant: {
      id: "53e427ca5691c9cfe27d0002",
      name: "WebPOS Terminal"
    },
    client: {
      id: "tidy-caffe-tazza"
    },
    total: 995, // (cents)
    tax: 0, // (cents)
    customer: {
      id: "561c45f05fcca89e6d696898",
      firstName: "Anthony",
      lastName: "Foster",
      photo: "https://profiles-aston.s3.amazonaws.com/photos/561c45f05fcca89e6d696898_0.9264673094730824.jpg"
    },
    items: [
      {
        name: "Beer",
        quantity: 2,
        amount: 995 // (cents)
      }
    ]
  }
}

Charge a Pre-approved Transaction¶

Note

THIS MANDATORY STEP IS PERFORMED BY THE INTEGRATOR/PARTNER AND CAN BE USED TO SUBMIT AND SETTLE THE TRANSACTION.

Warning

UNLESS THIS STEP IS PERFORMED THE CUSTOMER WILL NOT BE CHARGED.*

In this step a partner/thirdparty finalises a transaction that has been initialised by a customer. Requires authentication with a merchant/organization token. The back end of the third party app should do this while receiving the order.

POST /v5/transactions

{
  nonce: 'asoifahsifahoi2@&#Y@&*T*2eurn9732',   // the nonce will be used to locate the order. nonces cannot be used multiple times.
  submit: true,
  total: 20,                    // details such as total and merchant ID are only used for confirmation purposes. (cents)
  tax : 182,                // ... if all details do not match then the transaction will be rejected. (cents)
  merchantId: '34567890' // optional: verifies the transaction is for the specified merchant ID
}

Returns a transaction:

{
  id: "56676c170a34466597769f59",
  createdAt: "2015-12-08T23:47:35.354Z",
  updatedAt: "2015-12-08T23:48:04.441Z",
  completedAt: "2015-12-08T23:48:03.543Z",
  merchant: {
    id: "53e427ca5691c9cfe27d0002",
    name: "WebPOS Terminal"
  },
  client: {
    id: "tidy-caffe-tazza"
  },
  total: 995, // (cents)
  tax: 0, // (cents)
  customer: {
    id: "561c45f05fcca89e6d696898",
    firstName: "Anthony",
    lastName: "Foster",
    photo: "https://profiles-aston.s3.amazonaws.com/photos/561c45f05fcca89e6d696898_0.9264673094730824.jpg"
  },
  items: [
    {
      name: "Beer",
      quantity: 2,
      amount: 995 // (cents)
    }
  ]
}

Refund a Transaction.¶

POST /v5/transaction/{transactionId}/refund

No body data is required. If the transaction already has a refund associated with it, then the response will be a 400 error with the code ALREADY_REFUNDED.

Complete Payment Flow¶

This integration type is typical for pre-ordering integrations. The following diagram summarises the flow for pre-ordering in Tidy.

Complete Flow