Pin Payments API

Live and test APIs

Our API is available on two hosts:

• api.pinpayments.com (live)
• test-api.pinpayments.com (test)

The live API allows you to create real charges against your customers’ cards and transfer funds to bank accounts. The test API helps you do development and integration testing: it never creates real charges or bank transfers. Never send real card details to the test API; use our test cards instead.

Each host has its own set of API keys, which can be found in your account settings.

You can also use your dashboard to view and create transactions on both the live and test systems.

Transport Layer Security

You must use HTTPS—that is, HTTP over Transport Layer Security (TLS)—for all API calls. We recommend using TLS 1.2.

Authentication

Requests to the Pin Payments API must be authenticated using HTTP basic access authentication, with your API key as the username and an empty string as the password.

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

curl https://test-api.pinpayments.com/1/charges -u abc123:

If authentication fails, you’ll receive a response with a 401 status code and a JSON body like this:

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

Keys

Your account has two types of keys: publishable and secret. You can find your keys on the API Keys page of your dashboard.

Your secret keys have the ability to use all of the API. This means they can create charges, refunds, and bank transfers. On the live API, these operations have real-world effects, so keep your secret keys for the live API confidential.

Your publishable keys only have the ability to store payment card details (with the cards API) and bank account details (with the bank accounts API). They do not have the ability to create charges, refunds, or bank transfers. They are therefore safer to send to your customers’ computers—to their web browsers or mobile devices, for example. These are the keys you use with Hosted Fields to create secure payment forms in the browser.

Parameters

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

If you use percent encoding you must use square brackets to denote nested parameter keys. For example, the JSON object {"outer":{"inner":"value"}} would be represented as outer[inner]=value.

Except for those marked optional, all parameters are required.

Response format

Response bodies always use the application/json content type. (Some API responses will not have bodies, however.)

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. a list of charges).

{
  "response": {
    "key": "value"
  }
}

Changes to API Responses

Additional fields are added to API responses from time to time. These additions are made without prior announcement, and are considered a safe operation.

Despite this, there are ways of consuming an API where the addition of fields can cause problems. We recommend avoiding designs that rely on field ordering, field indexes, or offsets in API responses.

The ordering and number of fields in API responses is not fixed. Changes to the ordering will break integrations which assume a fixed field order.

Fields will never be removed from API Responses without prior announcement.

Errors

If an API request results in an error, a non-2xx 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.

Universal errors

The following errors may occur on any of our API endpoints:

Pagination

When a paginated collection is returned, there is a pagination property that describes the total size of the collection and the current page number.

{
  "pagination": {
    "count":  1,
    "per_page": 25,
    "current": 1
  }
}

To request the next page of a resource collection, pass a page parameter with the incremented page value.

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.

JSONP

Some APIs provide JSONP 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, percent-encoded, in the query string.

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

$.ajax({
  url: "https://api.pinpayments.com/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
  }
});