Third Party Payment Integrations (Web Apps)

The integration provides third party payment integrators with the ability to charge a Tidy/Aston customer via a Javascript library. The javascript library provides functions required to communicate with the mobile apps (Android & iOS) in a unified manner.

Please note that this document covers some API endpoints that are used by the Javascript API for completeness. You do not need to call these APIs (in fact you can't without a customer token), but they should give you a better understanding of the entire process.

Overview

There are 2 parts to the integration:

Back End (Merchant) Connection:

If you've ever added an integration (connection/app/etc) to Slack or Xero then you should be pretty familiar with the process. 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.

The basic flow should be something like:

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

Front End (Customer) Interface:

NOTE: the use case we are trying to fill here is seamless payment process within a Tidy mobile application. In order to do this they should ideally not have to re-enter their name, email and phone. As such these details are provided via the javascript interface. Typically this means that you app must provide a "guest check-out" process and pre-populate contact fields.

This processes is unique, but somewhat similar to web based payment processors. Instead of making HTTP API requests your app should call Javascript methods on the provided library.

When your app is running inside a Tidy mobile application these methods will interact with the native mobile applications to process the transaction. Tidy will return a valid nonce (token) if the customer approves the transaction.

Your app can then send this nonce to your backend where you should have access to your stored merchant token. You can then use the pair of tokens to process the transaction and get some money$$$. The pair of tokens is required to represent authority to process the transaction the the behalf of both the customer and the merchant.

In summary, the process should be like:

  1. Customer starts your app inside Tidy
  2. The adds items to their cart or similar and checks out
  3. The customers name and contact details are automatically populated
  4. The customer should only see one payment option "Your Account" or "In App". Please don't use "Aston Club" as the payment method name. Aston Club is not a consumer brand like PayPal. Listing this as the option typically confuses customers.
  5. The customer clicks pay now.
  6. Tidy mobile prompts the customer to confirm the payment in a native dialog.
  7. The customer clicks OK.
  8. Tidy mobile returns a nonce to your app.
  9. Your app posts back to your server with the nonce.
  10. You app makes a transaction request using both the nonce and merchant token to charge the customer for the merchant.
  11. Success!

Components

Components

Simplified Payment Flow

The following represents the payment flow at a high level from the perspective of a web application (pre-ordering web app) run within a WebView in Tidy mobile.

Simplified Flow

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

Refund Flow

It is also possible to refund a transaction. This can be done by simply calling the refund endpoint from the third party's back end to Aston Club API.

Details of this are discussed below.

Identifying Tidy Mobile Users

Since the "Pay with Aston Club" should only be shown for Tidy Mobile users, there needs to be some way for Tidy customers.

  • Option 1: querystring parameter - Tidy can launch the web application with a specific querystring parameter to help identify requests coming from a Tidy mobile application
  • Option 2: alternative URL - Tidy can launch an alternative URL to help identify requests coming from a Tidy mobile application
  • Option 3: javascript library method tidy.isTidyAvailable() - If this method returns true the browser is a web view in a Tidy mobile application. Note: this will require the web application to always include tidy.js. The other methods allow the web application to selectively include tidy.js only if required.

Tidy Javascript Interface and Library

Tidy Loyalty mobile applications provide a Javascript interface that enable web applications such as pre-order systems to accept payments from a Tidy customer. This provides the following benefits:

  1. A faster order flow - customers do not need to register or log in, the necessary credentials can already be provided by Tidy.
  2. Easy payment - Tidy customers can pay using their stored payment methods including Credit Cards and PayPal.

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

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

Sandbox / Testing

The production/release version requires the web application to be run inside a special web view contained in Tidy Mobile.

To make development easier we also provide a Sandbox version that enables development in a normal web browser against our sandbox environment. 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: at present sandbox.js also requires jQuery.

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 similar pattern.

Javascript Library 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) : string - 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:

{
    merchantId: String,       // the Aston ID of the merchant to be charged for this order.
                                                    // This is REQUIRED unless an orderStoreId is provided.
    orderStoreId: ?String,  // the third party store ID of the store to be charged for this order.
                                                  // 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: Decimal,             // total amount of the order INCLUSIVE OF TAX in DOLLARS.
    tax: Decimal,               // total amount of tax included in the order IN DOLLARS. (Optional)
    items: [
        {
            name: String,           // display or item name
            quantity: Integer,          // quantity
            amount: Decimal,    // total amount in cents (qty * item amount)
            tax: Decimal            // 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

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)
        }
      ]
    }
}

Settle a Pre-approved Transaction

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

IMPORTANT: 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
}

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

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