REST API v3 Reference

REST API v3 Reference

Overview

This describes the resources that make up the official Paychoice REST API v3. If you have any problems or requests please contact support.

Examples on this page use cURL, a free command line tool for getting or sending data using a URL syntax. All examples will need to be altered to use the correct  Schema

 

API client libraries are available on Paychoice’s GitHub page.

Schema

All API access is over HTTPS, and accessed from secure.paychoice.com.au for production or sandbox.paychoice.com.au for testing. All data is sent and received as JSON. Time stamps are in ISO 8601 format and returned in UTC format. Each request should be encoded as JSON with a Content-Type of ‘application/x-www-form-urlencoded’.

Environment Schema Domain
Live secure.paychoice.com.au
Testing sandbox.paychoice.com.au

Parameters

A number of API operations take optional parameters. All required parameters which are not completed will result in a HTTP status code of 400 Bad request with an error object explaining which parameter was at fault.

 

Errors

Errors can be detected by checking the returning HTTP status code. If the status code is not 200, then some form of error has generally occurred. Full details of what has happened can be revealed by checking the response body which will return the error object.

Code Description
200 OK Request was successfully performed
400 Bad Request Request was missing a parameter or contained malformed data, see JSON response for more info
402 Payment Required The charge request was not approved, see JSON response for more info
409 Conflict The charge reference was already in use, see JSON response for more info
410 Gone Occurs when the resource is no longer available, eg. when validating a card token
500 Internal Server Error An error has occurred on the Paychoice server
504 Gateway Timeout Occurs when a transaction takes longer to process than expected, see JSON response for more info

Charge Status

You can check to see if a charge operation has been approved by checking the status. The status is included within the charge object.

Status_Code Status Description
0 Approved The transaction has been successful.
1 Approved with errors The transaction has been successful but needs to be manually checked as an abnormality has been encountered
5 Dishonoured The transaction has not been successful. The error fields should be checked as to why the dishonour has occurred.
6 Error The transaction has not been successful. The error fields should be checked as to why the dishonour has occurred.
9 Processing The transaction is still being processed. You should check back at a later date or let the Payment Notification API notify you of the transaction result. You will regularly see this status when charging bank accounts.
99 Voided The transaction has been voided.

AJAX

All client side calls will be blocked. You may use paychoice.js to call the API to store credit cards. Server side and native code are the only methods available which can access the full extent of the REST API.

JSONP

You can send a ?callback parameter for storing credit cards to the POST /token operation to have the results wrapped in a JSON function enabling the use of JSONP. This is typically used when browsers want to embed content in web pages by and are attempting to get around older browser issues.

Javascript handler code written to process the callback would like this:

function foo(response) {
  console.log(response.object_type);
}

Testing

All testing must be done within the testing environment. Any testing which is conducted outside of this environment will incur fees & charges.

Testing Responses

To test how your system handles different charge responses from the gateway you can pass through the desired error code in the amount parameter for the charge. The decimal value within the amount will return the matching error code, error description and status for the charge. See credit card error codes or bank account error codes for a complete list of error codes.

Test Credit Cards

Use the following credit card numbers for testing.

Issuer Card Number
American Express 378282246310005
Diners Club 30569309025904
MasterCard 5555555555554444
Visa 4111111111111111

Test CVV

For the testing server, the first three characters of the CVV value determine the result, as shown
here.

CVV Value Passes Validation
000-300 Yes
301-999 No

Basic

Example
curl https://{schema}/api/v3/ 
 -u "{username}:{password}"

OAuth 2.0

Paychoice supports the OAuth 2.0 protocol. Your application can make API requests on your users behalf without requiring their user credentials or API keys once your application has been granted access by the user.

When a user visits your site and wants to connect with Paychoice, you’ll send them to your applications authorisation page hosted on the Paychoice website. The user will then be asked if they wish to grant your site permission to connect to their account. Afterwards, we will redirect them back to your pre-recorded return URL with an authorization code or an error (if the authorization was denied).

The authorization code can be traded for an access_token by making a request to our OAuth token endpoint. An access_token can be used instead of a username and password and is safe to store within any application.

For more information about OAuth 2.0 visit the OAuth website

OAuth 2.0 Flow

The OAuth 2.0 workflow consists of 3 parts:

  1. Authorisation Code – Gaining approval from the merchant
  2. Access Token – Exchanging the authorisation code for the access token
  3. Calling the API – Calling API operations
  4. Refresh Token – Creating a new access token

OAuth 2.0 Authorisation Code

An OAuth 2.0 authorisation code is used in exchange for an access token which will be later used to call the API. To get the authorisation code a merchant will need to approve the use of the application with their account. You can take a look at what the authorisation page looks like using our sample app.

Once the merchant has typed in their account details and authorised the application, a response will be sent to the redirect_uri as specified when the application was registered. If the user approves the access request, then the response contains an authorization code and the state parameter (if included in the request). If the user does not approve the request the response contains an error message.

Request
Parameter Description
client_id The applications client_id which is assigned to you by Paychoice.
response_type This should always be set to code. Other options in the future will be available.
scope This should always be set to read_write. Other options in the future will be available.
state (optional) The state value will be passed back to you when a merchant approves or denies authorisation.
Example Request
https://{schema}/api/oauth2/authorize?response_type=code&client_id={client_id}&scope=read_write
&state={state}
Response
Parameter Description
code The authorisation code for the user.
error An error description describing if any errors have occurred.
scope The scope which has been granted by the user.
state (optional) The state value which was originally passed to the Paychoice OAuth 2.0 authorize page.
Example Response
http://{registered_url}?code=xxxxxxxxxxx&scope=Read_Write&state=&error=

OAuth 2.0 Access Token

After the your application receives the authorization code, it may exchange the authorization code for an access token and a refresh token. The access_token is used when calling any API operation through the bearer authentication scheme.

Parameter Description
client_id The applications client_id which is assigned to you by Paychoice.
grant_type This should always be set to authorization_code when you are using an authorisation code.
client_secret This should always be set to read_write. Other options in the future will be available.
code The authorisation code which was gained previously.
Example Request
curl https://{schema}/api/oauth2/token
 -d "grant_type: authorization_code"
 -d "client_id: {client_id}"
 -d "client_secret: {client_secret}"
 -d "code: {code}"
Example Successful Response
{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "refresh_token": "yyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "token": "bearer"
}
Example Error Response
{
  "error": "invalid_code",
  "error_description": "Invalid code parameter provided"
}

OAuth 2.0 Refresh Token

In some cases, your application may have it’s access token revoked. To obtain a new access token, POST the refresh token to the authorization server with your application details. We will reissue your application with a new access_token and refresh_token. Refresh tokens may only be used once.

Example Request
curl https://{schema}/api/oauth2/token
 -d "grant_type: refresh_token"
 -d "client_id: {client_id}"
 -d "client_secret: {client_secret}"
 -d "code: {code}"
Example Response
{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "refresh_token": "yyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "token": "bearer"
}

Calling the API

After your application has successfully obtained an access token, your application can access any REST API operation by including an Authorization: Bearer HTTP header it in. The bearer authentication scheme is a drop in replacement for the basic authentication scheme.

Request Example
curl https://{schema}/api/v3/ 
 -H "Authorization: bearer {access_token}"

Charges

Resource Description
GET /api/v3/charge Retrieves the list of charges the merchant has made
GET /api/v3/charge/{charge::id} Retrieves the specific charge the merchant has made using the charges id
POST /api/v3/charge Makes a new charge against a credit card or token

Create a Charge against credit card

Resource Information
Authentication OAuth 2.0
Basic
HTTP Methods POST
Resource /api/v3/charge/
Response Object charge object

Creates a new charge against a credit card or card token

Note: To test how your system handles different charge responses from the gateway you can pass through the desired error code in the amount parameter. Refer to Testing for more information.
Parameter Description
currency The currencies ISO code. Use AUD for Australia.
amount The amount in dollars to charge
reference Your reference number for the transaction, needs to be unique, typically this would be your invoice number
card[name] The name on the front of the credit card
card[number] The primary access number (PAN) on the front of the credit card
card[expiry_month] The 2 digit expiry month on the front of the credit card
card[expiry_year] The 2 digit expiry year on the front of the credit card
card[cvv] The CVV/CVC/CSC/CID listed on the back of the credit card, dash ‘-‘ if not available
card_token The credit card token id
Example Request
curl https://{schema}/api/v3/charge/
 -u "{username}:{password}"
 -d "currency=AUD"
 -d "amount=5.00"
 -d "reference=Invoice 4325"
 -d "card[name]=John Smith"
 -d "card[number]=4111-1111-1111-1111"
 -d "card[expiry_month]=12"
 -d "card[expiry_year]=16"
 -d "card[cvv]=123"
Example Response
{
  "charge": {
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "Invoice 4325",
    "status": "Approved",
    "status_code": "0"
  },
  "object_type": "charge"
}

Create a Charge against bank account

Resource Information
Authentication OAuth 2.0
Basic
HTTP Methods POST
Resource /api/v3/charge/
Response Object charge object

Creates a new charge against a bank account.

Note: To test how your system handles different charge responses from the gateway you can pass through the desired error code in the amount parameter. Refer to Testing for more information.
Parameter Description
currency The currencies ISO code. Use AUD for Australia.
amount The amount in dollars to charge
reference Your reference number for the transaction, needs to be unique, typically this would be your invoice number.
bank[name] The name of the bank account owner
bank[bsb] The bank account bank state branch number
bank[number] The bank account number
bank_token The bank account token id
Example Request
curl https://{schema}/api/v3/charge/
 -u "{username}:{password}"
 -d "currency=AUD"
 -d "amount=5.00"
 -d "reference=Invoice 4325"
 -d "bank[name]=John Smith"
 -d "bank[bsb]=123-456"
 -d "bank[number]=123456"
Example Response
{
  "charge": {
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "",
    "error_code": "",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "Invoice 4325",
    "status": "Processing",
    "status_code": "9"
  },
  "object_type": "charge"
}

List Charges

Resource Information
Authentication OAuth 2.0
Basic
HTTP Methods GET
Resource /api/v3/charge/
Response Object charge list object

Retrieves a list of charges which has been made.

Parameter Description
page[number] (optional) The page number which to jump to. Default = 0.
page[items] (optional) The number of items to retrieve per page. Default = 100
Example Request
curl https://{schema}/api/v3/charge/
 -u "{username}:{password}" -G
 -d "page[number]=2"
 -d "page[items]=10"
Example Response
{
  "charge_list": [{
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "Invoice 4325",
    "status": "Approved",
    "status_code": "0"
  }, 
  ...
  ],
  "object_type": "charge_list"
}

Retrieve a Charge

Resource Information
Authentication OAuth 2.0
Basic
HTTP Methods GET
Resource /api/v3/charge/{charge::id}
Response Object charge object

Retrieves a specific charge using the charge id.

Example Request
curl https://{schema}/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0
 -u "{username}:{password}" -G
Example Response
{
  "charge": {
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "Invoice 4325",
    "status": "Approved",
    "status_code": "0"
  },
  "object_type": "charge"
}

Tokens

Credit card and bank tokens

When you want to be able to store credit card or bank account information on your server without holding sensitive data, you can use the token endpoint as a replacement. Paychoice will hold all the sensitive information securely and returns a token back which can be used for charges later.

Tokens will expire after they have been used the first time unless they are stored against a customer. If you ever need to validate a token and see if it is still usable, use the GET /api/v3/token/{card::token} or /api/v3/bank_token/{bank::token} resource.

Resource Description
GET /api/v3/token/{card::token} Retrieves a credit cards details using the specified card token
POST /api/v3/token Stores a credit card and makes a new token for use against charging the card at a later date
DELETE /api/v3/token Removes stored credit card token
GET /api/v3/bank_token/{bank::token} Retrieves a bank account details using the specified bank token
POST /api/v3/bank_token/ Stores bank account details and makes a new token for future charges

Retrieve Credit Card

Resource Information
Authentication Public API Key
OAuth 2.0
Basic
HTTP Methods GET
Resource /api/v3/token/{card::token}
Response Object card object

Retrieves a credit cards details using the specified card token. To obtain a token for a credit card you will need to use the store credit card method first.

If the credit card has been removed you will receive a HTTP status code of 410 Gone.

Warning: Using the public API key will not return a response body for security reasons. You will only receive the response body if any other authentication method is used.

Parameter Description
key (optional) Your public API key. This does not need to be included if you are using any other authentication method.
Example Request
curl https://{schema}/api/v3/token/ffe98527-add1-4048-9cdf-cc03da0e84a8
 -u "{username}:{password}"
Example Response
{
  "card": {
    "card_name": "John Citizen",
    "card_type": "Visa",
    "expiry_month": "12",
    "expiry_year": "14",
    "link": {
      "href": "/api/v3/token/ffe98527-add1-4048-9cdf-cc03da0e84a8",
      "rel": "self"
    },
    "masked_number": "411111XXXXXX1111",
    "token": "ffe98527-add1-4048-9cdf-cc03da0e84a8"
  },
  "object_type": "card"
}

Store Credit Card

Resource Information
Authentication Public API Key
OAuth 2.0
Basic
HTTP Methods POST
JSONP GET
Resource /api/v3/token
Response Object card object

Stores a credit card and makes a new token for use against charging the card at a later date

Parameter Description
key (optional) Your public API key. This does not need to be included if you are using any other authentication method.
card[name] The name on the credit card
card[number] The number on the credit card
card[cvv] The CVC/CVV/CVV2 number on the back of the credit card
card[expiry_month] The expiry month expressed in up to 2 digits
card[expiry_year] The expiry year expressed in 2 digits
durable (optional) True/false value which marks the token as available for more than a single use
Example Request
curl https://{schema}/api/v3/token
 -X POST
 -d "key={public API key}"
 -d "card[name]=John Citizen"
 -d "card[number]=4111111111111111"
 -d "card[cvv]=123"
 -d "card[expiry_month]=12"
 -d "card[expiry_year]=14"
Example Response
{
  "card": {
    "card_name": "John Citizen",
    "card_type": "Visa",
    "expiry_month": "12",
    "expiry_year": "14",
    "link": {
      "href": "/api/v3/token/ffe98527-add1-4048-9cdf-cc03da0e84a8",
      "rel": "self"
    },
    "masked_number": "411111XXXXXX1111",
    "token": "ffe98527-add1-4048-9cdf-cc03da0e84a8"
  },
  "object_type": "card"
}

Remove Credit Card Token

Resource Information
Authentication Public API Key
OAuth 2.0
Basic
HTTP Methods DELETE
Resource /api/v3/token/{card::token}
Response Object card object

Removes stored credit card token, returns empty card object when operation succeed

Parameter Description
key (optional) Your public API key. This does not need to be included if you are using any other authentication method.
Example Request
curl https://{schema}/api/v3/token/056d2637-eb63-48d3-948f-9fcd31b88fd5
 -X DELETE
 -d "key={public API key}"
Example Response
{
  "card": {},
  "object_type": "card"
}

Retrieve Bank Account

Resource Information
Authentication Public API Key
OAuth 2.0
Basic
HTTP Methods GET
Resource /api/v3/token/{bank::token}
Response Object bank object

Retrieves bank account details using the specified bank token To obtain a token for a bank account you will need to use the store bank account method first.

If the bank account has been removed you will receive a HTTP status code of 410 Gone.

Warning: Using the public API key will not return a response body for security reasons. You will only receive the response body if any other authentication method is used.

Parameter Description
key (optional) Your public API key. This does not need to be included if you are using any other authentication method.
Example Request
curl https://{schema}/api/v3/bank_token/ffe98527-add1-4048-9cdf-cc03da0e84a8
 -u "{username}:{password}"
Example Response
{
  "bank": {
    "name": "John Citizen",
    "bsb": "112944",
    "number": "144413443",
    "link": {
      "href": "/api/v3/bank_token/c8d0f8cf-02d5-4a44-8659-46e47a6ef68b",
      "rel": "self"
    },
    "bank_token": "c8d0f8cf-02d5-4a44-8659-46e47a6ef68b"
  },
  "object_type": "bank"
}

Store Bank Account

Resource Information
Authentication Public API Key
OAuth 2.0
Basic
HTTP Methods POST
JSONP GET
Resource /api/v3/bank_token
Response Object bank object

Stores a bank account and makes a new token for use against charging the bank account at a later date

Parameter Description
key (optional) Your public API key. This does not need to be included if you are using any other authentication method.
bank[name] The name of the bank account owner
bank[bsb] The bank account bank state branch number
bank[number] The bank account number
Example Request
curl https://{schema}/api/v3/bank_token
 -X POST
 -d "key={public API key}"
 -d "bank[name]=John Citizen"
 -d "bank[bsb]=123123"
 -d "bank[number]=123123123"
Example Response
{
  "bank": {
    "bsb": "123123",
    "bank_token": "c8d0f8cf-02d5-4a44-8659-46e47a6ef68b"
    "link": {
      "href": "/api/v3/bank_token/c8d0f8cf-02d5-4a44-8659-46e47a6ef68b",
      "rel": "self"
    },
	"name": "John Citizen",
	"number": "123123123"
  },
  "object_type": "bank"
}

Refund

Refunds a transaction that has been approved against the charge id. Refunds can be partial or full amount of the original charge.

Resource Information
Authentication OAuth 2.0
Basic
HTTP Methods POST
Resource /api/v3/refund
Response Object refund object
Resource Description
POST /api/v3/refund Refunds an Charge that has been approved

Refund Transaction

Parameter Description
amount The amount to refund, which can be any amount up to the original charge amount
charge_id The transaction ‘id’ value returned from charge operation
reference Unique reference number for the transaction, typically this would be your invoice number
Example Request
curl https://{schema}/api/v3/refund
 -X POST
 -d "amount=5"
 -d "charge_id=27d487cc-4a73-4687-baf8-0ddb50d219b9"
 -d "reference=RefundforInvoice-234"
Example Response
{
  "refund": {
    "status": "Approved",
    "status_code": 0,
    "amount": 5,
    "created": "2015-04-19T11:56:38.1675Z",
    "currency": "AUD",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "d59b7176-1e84-45ce-982e-538ad8c17c58",
    "link": {
      "href": "/api/v3/refund/d59b7176-1e84-45ce-982e-538ad8c17c58",
      "rel": "self"
    },
    "reference": "RefundforInvoice-234"
    },
    "object_type": "refund"
}

Errors

{
  "error": {
    "message": "{the error message}",
    "param": "{the parameter which the message refers to}"
  },
  "object_type": "error"
}

Charge

{
  "charge": {
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "Invoice 4325",
    "status": "Approved",
    "status_code": "0"
  },
  "object_type": "charge"
}

Charge List

{
  "charge_list": [{
    "amount": "5",
    "created": "2012-12-06T06:27:34.0173352Z",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "f279074f-79af-47d1-961f-ea3f35e71ec0",
    "link": {
        "href": "/api/v3/charge/f279074f-79af-47d1-961f-ea3f35e71ec0",
        "rel": "self"
    },
    "reference": "cd38dcc9-16bf-4589-9b94-9fd67d1f947a",
    "status": "Approved",
    "status_code": "0"
  }, 
  ...
  ],
  "object_type": "charge_list"
}

Card

{
  "card": {
    "card_name": "John Citizen",
    "card_type": "Visa",
    "expiry_month": "12",
    "expiry_year": "14",
    "link": {
      "href": "/api/v3/token/ffe98527-add1-4048-9cdf-cc03da0e84a8",
      "rel": "self"
    },
    "masked_number": "411111XXXXXX1111",
    "token": "ffe98527-add1-4048-9cdf-cc03da0e84a8"
  },
  "object_type": "card"
}

Bank

{
  "bank": {
    "name": "John Citizen",
    "bsb": "112944",
    "number": "144413443",
    "link": {
      "href": "/api/v3/bank_token/c8d0f8cf-02d5-4a44-8659-46e47a6ef68b",
      "rel": "self"
    },
    "bank_token": "c8d0f8cf-02d5-4a44-8659-46e47a6ef68b"
  },
  "object_type": "bank"
}

Refund

{
  "refund": {
    "status": "Approved",
    "status_code": 0,
    "amount": 5,
    "created": "2015-04-19T11:56:38.1675Z",
    "currency": "AUD",
    "error": "Transaction Approved",
    "error_code": "0",
    "id": "d59b7176-1e84-45ce-982e-538ad8c17c58",
    "link": {
      "href": "/api/v3/refund/d59b7176-1e84-45ce-982e-538ad8c17c58",
      "rel": "self"
    },
    "reference": "RefundforInvoice-234"
    },
    "object_type": "refund"
}
(*) Required Fields