Charge credit cards in multiple currencies.
Always free to use for testing. Try it now →

Pin Payments API

Endpoints

The API has two endpoint host names:

  • api.pin.net.au (live)
  • test-api.pin.net.au (test)

The live host is for processing live transactions, whereas the test host can be used for integration testing and development.

Each endpoint requires a different set of API keys, which can be found in your account settings.

You can also use the dashboard to switch between the two endpoints, and to view and create transactions.

SSL

SSL is required for all API calls.

Authentication

Calls to the Pin Payments API must be authenticated using HTTP basic authentication, with your API key as the username, and a blank string as the password.

For example, if your test secret key was abc123, you would use the following CURL command to fetch your charges:

curl https://test-api.pin.net.au/1/charges -u abc123:

If authentication fails you will receive a 401 response containing:

{
  "error": "unauthenticated",
  "error_description": "Not authorised. (Check API Key)."
}

Keys

Your account has two types of keys:

  • publishable
  • secret

You can find your keys on the account settings page of the dashboard.

Your secret key can be used with all of the API, and must be kept secure and secret at all times. You use your secret key from your server to create charges and refunds.

Your publishable key can be used from insecure locations (such as browsers or mobile apps) to create cards with the cards API. This is the key you use with Pin.js to create secure payment forms in the browser.

Parameters

You can specify parameters using either the JSON content-type (application/json) or the url form encoded content-type (application/x-www-form-urlencoded).

If you use url form encoding you must use square brackets to denote nested parameter keys. e.g. {"outer":{"inner":"val"}} becomes outer[inner]=val

Except for those marked optional, all parameters are required.

Response Format

All responses are returned as application/json, and successful responses have a top-level key, response, containing the data representing the resource.

The value of response is either an object (e.g. a single charge) or an array (e.g. an array of charges).

{
  "response": {
    "key": "val"
  }
}

Errors

If an API request results in an error a non-20x status code will be returned, along with a JSON object containing error and error_description keys.

{
  "error": "an_error_code",
  "error_description": "A description of the error."
}

Some error responses may contain extra information. See each API’s error examples for details and examples.

Long-running requests

Most API requests should complete in under a second, but some (such as creating a charge) may take between 5 and 90 seconds to complete.

You should design your user experience and software to take these long-running requests into account, or else a user may accidentally submit duplicate payments. For example, show a message to the user (such as “Processing payment…”) with an animation to help them understand a charge is in progress, and prevent the payment form from being submitted multiple times.

JSON-P

Some APIs provide JSON-P support to allow for easier cross-domain HTTP requests in the web browser.

You must specify a callback parameter with the callback function name, and you can optionally use the _method parameter to specify the HTTP method.

All parameters must be passed, URL-encoded, in the query string.

An example, using jQuery.ajax to call the cards API:

$.ajax({
  url: "https://api.pin.net.au/1/cards.json?callback=?",
  dataType: "jsonp",
  data: {
    _method: 'POST',
    publishable_api_key: 'your publishable api key',
    // Other API parameters go here
  },
  success: function(response) {
    // Response handling goes here
  }
});