NAV
JavaScript cURL

Introduction

Welcome to the QuayPay API Documentation!

Here we aim to document the use of our API endpoints for working with stored cards, charges and user authentication.

We currently offer a JavaScript client library available here to accompany our raw HTTP API and plan to release support for other languages shortly.

Getting Started

These are the basic steps for setting up access and use of the QuayPay payments API on your merchant website:

  1. Register for an Access to receive your application ID and merchant account details
  2. Modify your Application with your authentication settings
  3. Set up Authentication so your users can register and login to QuayPay on your site
  4. Enjoy full use of QuayPay’s Credit Card Storage and other features

Applications

An application object holds configuration and authentication settings defining how the QuayPay API will be used.

After signing up for developer access, you are provided with an application ID used to retreive and set these attributes.

Attributes

Attribute Type Description
id String
login_method String The method of displaying the login page to the end user.
login_providers Array The authentication providers allowed for users to authenticate against the application.
live Boolean Whether the gateway is currently accepting live or test payments.
redirect_uri String Where to redirect users after successfully authenticating via login providers.
secret String Used to commit requests and authenticate without oAuth.

Retreiving an Application

qp.merchant.getApplications().then(function(response) { console.log(response.data) });
{
    "id": "testappid",
    "login_method": "iframe",
    "login_providers": "['facebook, google, form']",
    "live": false,
    "redirect_uri": "http://merchant.com/logins/oauth.html"
}
curl https://gateway.quaypay.com/api/v2/applications/testappid \
    -H "Authorization: Bearer f3ab55c097727130fdc183529131fadd4b36b7ec23fc968a7d776e56468f7134"

> { 
    application: {
        id: testappid,
        login_method: 'iframe',
        login_providers: ['facebook, google, form'],
        live: false,
        redirect_uri: 'http://merchant.com/logins/oauth.html'
    }
}

The data returned when retreiving an application is dependent on your level of authentication when making the request.

When unathenticated or using a non-merchant account to generate your API token, only the login_method, login_providers and redirect_uri are returned.

When using a merchant account to generate your API token, all fields except the application secret are returned.

Modifying an Application

qp.merchant.updateApplication({id: 'testappid', login_method: 'popup'});

> {
    id: testappid,
    login_method: 'popup',
    ...
}

curl https://gateway.quaypay.com/api/v2/applications/testappid \
    -X PUT \
    -H 'Content-Type: application/json' \ 
    -H "Authorization: Bearer f3ab55c097727130fdc183529131fadd4b36b7ec23fc968a7d776e56468f7134" \
    -d '{ "application": { "login_method": "popup" } }'

> { 
    application: {
        id: testappid,
        login_method: 'popup',
        ...
    }
}

To update your application, pass in an object containing the attrivutes you wish to update and their new values.

The updated application is returned after a successful request is made.

Note that the redirect_uri used MUST use SSL (begin with https://).

Authentication

Using the Client Library

qp.init({
    client_id:"testappid",
    redirect_uri:"http://merchant.com/auth/post_token.html",
    login_providers: [ "facebook", "form" ]
});

Using our JavaScript client library makes authentication very easy, requiring only three parameters:

For the example on the right, when a user attempts to make any unauthorized API request, they are prompted to login to QuayPay via either Facebook or a form based login.

The method used to direct a user to the prompt to login is defined by the application’s login_method attribute. This is set to 'iframe' by default but can also hold the value 'popup' for a popup window.

Once successfully authenticated, the login_method used to display the authentication options is redirected to the redirect_uri with an access token as a url parameter. This access token is then passed back to the client library using postMessage and stored in the browser’s localStorage for future requests.

A copy of the file to place at the redirect_uri path is available here, right click to save the page and place it on your server.

Auth Providers

Merchants have the ability to decide how users authenticate themselves against the QuayPay API. The provideres of this authentication fit into three categories:

QuayPay Form

The classic form registration and login is the default provider for API authentication. By default, these forms are shown in an overlayed iframe allowing the customer to enter their email and password to authenticate.

Third Party Federated Identity

Merchants may allow customers to register and login using third party federated identity providers, generally provided by social networking services such as Facebook or Google. When a user has an existing session with one of these providers, registration and login are generally single-click actions.

QuayPay currently provides access to the authentication services of Facebook and Google but merchants may request support for other providers.

Merchant Federated Identity

Merchants who wish to have users authenticated on QuayPay using their own website’s authentication scheme must support the oAuth2 standard for delegation of access to user resources by QuayPay.

Auth Methods

iFrame

By default, an application’s login_method is set to iframe. This means that the prompt to register or login is displayed in an overlayed iFrame element.

Setting login_method to popup displays the authentication providers in a popup window rather than an iFrame.

Workflows

Charge

qp.charge(5000); // Prompt the current user to add/select a card and charge $50.00

The charge workflow allows for the creation of a charge by prompting the authenticated user to add or select a stored card and confirm a charge on this card.

Use the following details for the example below:

Email: test@test.com
Password: test@test.com

Cards

Get All Cards

qp.getCards().then(function(response) { console.log(response.data) });
{
  "total": 2,
  "results": [
    {
      "id": "72da85b5fd46a356aa356b7d30cd88660bf",
      "brand": "visa",
      "last_four": "4242"
    },
    {
      "id": "216baeb5fd46a356ae9f30cd8454f0bf4e1",
      "brand": "visa",
      "last_four": "8630"
    }
  ]
}

Retrieves all cards associated with the authenticated account.

HTTP Request

GET https://gateway.quaypay.com/api/v2/cards

Return Values

Parameter Type Description
total Number The number of records returned.
results Array An array of cards owned by the user.

Get a Specific Card

qp.getCard('72da85b5fd46a356aa356b7d30cd88660bf').then(function(response) { console.log(response.data) });
{
  "card": {
    "id": "72da85b5fd46a356aa356b7d30cd88660bf",
    "brand": "visa",
    "last_four": "4242"
  }
}

Retrieve a specific card.

HTTP Request

GET https://gateway.quaypay.com/api/v2/cards/:id

Return Values

Parameter Type Description
card Object The card associated with the ID passed in.

Add a Card

qp.addCard({ 
    name: 'Bob Smith',
    number: '4242 4242 4242 4242',
    exp_month: '6',
    exp_year: '2016',
    cvc: '100'
  }).then(function(response) { console.log(response.data) });
{
  "card": {
    "id": "72da85b5fd46a356aa356b7d30cd88660bf",
    "brand": "visa",
    "last_four": "4242"
  }
}

Add a card to the currently authenticated account.

A successful response returns the details of the card, including the ID which can be used to make payments straight away.

HTTP Request

POST https://gateway.quaypay.com/api/v2/cards

Return Values

Parameter Type Description
card Object The card object generated from the provided details.

Delete a Card

qp.deleteCard('72da85b5fd46a356aa356b7d30cd88660bf').then(function(response) { console.log(response.status) });

> 200

Delete a specific card.

Returns status code 200 when a card is deleted successfully.

HTTP Request

DELETE https://gateway.quaypay.com/api/v2/cards/:id

Charges

Get All Charges

qp.getCharges().then(function(response) { console.log(response.data) });
curl https://gateway.quaypay.com/api/v2/charges \
    -H "Authorization: Bearer f3ab55c097727130fdc183529131fadd4b36b7ec23fc968a7d776e56468f7134"
{
  "total": 1,
  "results": [
    {
      "id": "charge_1-11B",
      "amount": "1000",
      "application_id": "testappid",
      "card_id": "72da85b5fd46a356aa356b7d30cd88660bf",
      "committed": true,
      "created_at": 1439170291,
      "live": false,
      "metadata": {},
      "paid": true,
      "points": false,
      "points_used": 0,
      "shipping": {},
      "user_id": "user_1-1J",
      "token": "lxuuqrLprOESO/fVH4c0aA==↵"
    }
  ]
}

Retrieves all charges associated with the authenticated account.

A merchant may retreive all charges associated with their application.

All merchant calls with the client library have the form:

qp.merchant.getCharges()

A customer may retreive all charges associated with their user account.

HTTP Request

GET https://gateway.quaypay.com/api/v2/charges

Return Values

Parameter Type Description
total Number The number of records returned.
results Array The array of charges.

Get a Specific Charge

qp.getCharge('charge_1-11B').then(function(response) { console.log(response.data) });
{
  "charge": {
    "id": "charge_1-11B",
    "amount": "1000",
    "application_id": "testappid",
    "card_id": "72da85b5fd46a356aa356b7d30cd88660bf",
    "committed": true,
    "created_at": 1439170291,
    "live": false,
    "metadata": {},
    "paid": true,
    "points": false,
    "points_used": 0,
    "shipping": {},
    "user_id": "user_1-1J",
    "token": "lxuuqrLprOESO/fVH4c0aA==↵"
  }
}

Retrieve a specific charge.

HTTP Request

GET https://gateway.quaypay.com/api/v2/charges/:id

Return Values

Parameter Type Description
charge Object The charge associated with the ID passed in.

Add a Charge

Passing in a card ID accessible via qp.getCards()

qp.addCharge({ 
    amount: '2000',
    card_id: '72da85b5fd46a356aa356b7d30cd88660bf',
    metadata: {
      product: {
        id: '9851712424',
        quantity: 3
      }
    }
  });

Passing in card details directly

qp.addCharge({ 
    amount: '2000',
    card: {
      name: 'Bob Smith',
      number: '4242 4242 4242 4242',
      exp_month: '6',
      exp_year: '2016',
      cvc: '100'    
    },
    metadata: {
      product_id: '9851712424',
      quantity: 3
    }
  });
{
  "token": "lxuuqrLprOESO/fVH4c0aA==↵"
}

Add a charge using the ID of the customer’s card or passing in the card details directly.

The process of retreiving a customer’s stored cards, displaying those cards and charging the selected card is best handled by the Charge Workflow.

HTTP Request

POST https://gateway.quaypay.com/api/v2/charges

Return Values

Parameter Type Description
token string A token that can be used to commit the charge at any time.

Commit a Charge

Passing in a card ID accessible via qp.getCards()

qp.commitCharge({ 
    token: "lxuuqrLprOESO/fVH4c0aA==↵"
  });
{
  "charge": {
    "id": "charge_1-11B",
    "amount": "2000",
    "application_id": "testappid",
    "card_id": "72da85b5fd46a356aa356b7d30cd88660bf",
    "committed": true,
    "created_at": 1439170291,
    "live": false,
    "metadata": {},
    "paid": true,
    "points": false,
    "points_used": 0,
    "shipping": {},
    "user_id": "user_1-1J",
    "token": "lxuuqrLprOESO/fVH4c0aA==↵"
  }
}

QuayPay uses a two-phase commit to ensure atomicity and validity of all charges.

When a charge is added by a customer, the token returned is used to ‘commit’ that charge. This can be done either on the merchant’s server side using the application secret, or by the authenticated account who created the initial charge.

HTTP Request

POST https://gateway.quaypay.com/api/v2/charges/commit

Return Values

Parameter Type Description
charge Object The charge object generated from the provided details.