NAV Navbar
Logo
shell JavaScript PHP

Introduction

The PayDock platform is designed to be as simple and easy to use as possible.

There are a few different ways to interact with PayDock:

Getting started

You can get up and running using the PayDock API in just a few minutes.

Start by signing up for a sandbox account. This will give you access to the admin portal.

From the admin portal you can add a payment gateway. You’ll need to sign up for a test account with a payment gateway. Choose any one of the following gateways.

Then add a gateway in Gateway –> Add New:

Add Gateway

You can retrieve your API public and secret key from the admin portal in My Account –> API & Settings, which you’ll need to authenticate:

API public key

Once done, jump into one of our Recipes:

Key Concepts

There are a few key concepts that help understand how to get the most out of PayDock’s Platform

Concept Description
one-time token This is a token that represents payment information. This is often generated on client (using Paydock.js or Client SDK). One time tokens expire after 3 hours.
payment source A payment source represents a way of paying for something. This could be credit card details, bank account details or a PayPal account. There can be multiple payment sources associated with a customer.
gateway A gateway is a payment gateway of any type that payments are routed to, eg Braintree, PayPal.
vault The vault is PayDock’s PCI compliant storage vault of payment sources.
vault token A vault token is the reference code for a payment source, eg a credit card and expiry date
subscription A subscription is a scheduled payment plan for a customer.
sandbox A sandbox environment is a place where test API calls can be made without charging customers.
customer An individual who can make payments.
admin portal Web interface to manage your PayDock account

Endpoints

An endpoint is a unique URL that represents an object or collection of objects which serves as the base of all PayDock API interactions.

PayDock provides two different public environments to access. You can access the different environments from the following URLS:

Environment API Admin portal
Sandbox https://api-sandbox.paydock.com https://app-sandbox.paydock.com
Production https://api.paydock.com https://app.paydock.com

To set up API calls, prepend all calls with:

Throughout the documentation URLs are provided relative to these base URLs.

eg GET /v1/gateways for Sandbox, represents

GET https://api-sandbox.paydock.com/v1/gateways

eg GET /v1/gateways for Production, represents

GET https://api.paydock.com/v1/gateways

Authentication

Authenticate with our API is provided by providing either your API Public Key or API Secret Key, depending on how you are using the Paydock platform. These are 40 character strings which you can find in out web app: API public key

Authentication is managed slightly differently depending on how you’re connecting to Paydock.

Connecting to the Paydock from the client side is managed through the Public Key. There are a couple of ways to use the public key:

All other authentication is through the API Secret Key. This is used to secure server side calls:

Response codes / Error codes

"Error appears when no gateway type provided while creating"
{
  "status": 400,
  "error": {
    "message": "No gateway type provided"
  },
  "resource": {
    "type": "gateway",
    "data": null
  }
}

"Error appears when credentials are not correct"
{
  "status": 400,
  "error": {
    "message": {
      "message": "Invalid Transaction Details",
      "http_status_code": 400,
      "errors": [
        {
          "gateway_specific_code": "invalid_credentials",
          "gateway_specific_description": "invalid credentialssss",
          "param_name": null,
          "description": "Invalid Transaction Details"
        }
      ]
    }
  },
  "resource": {
    "type": "gateway",
    "data": null
  }
}

"Error appears when credit card is not provided"
{
  "status": 400,
  "error": {
    "message": "Credit Card Invalid or Expired",
    "details": [
      {
        "gateway_specific_code": "number",
        "gateway_specific_description": "is not a valid card",
        "param_name": "number",
        "description": "Credit Card Invalid or Expired"
      }
    ]
  }
}

"Error appears when some field or fields not valid"
{
  "status": 400,
  "error": {
    "message": "Validation Error",
    "details": [
      "No amount provided"
    ]
  },
  "resource": {
    "type": "charge"
  }
}

"Error appears when provided resource is not correct"
{
  "status": 404,
  "error": {
    "message": "Wrong Api path"
  },
  "resource": {
    "type": "path",
    "data": null
  }
}

"Error appears when some data valid but not exist"
{
  "status": 400,
  "error": {
    "message": "Invalid Transaction Details",
    "details": [
      {
        "gateway_specific_code": "unknown",
        "gateway_specific_description": "unknown error",
        "param_name": null,
        "description": "Invalid Transaction Details"
      }
    ]
  }
}

"Error appears when user does not provide correct credentials"
{
  "status": 403,
  "error": {
    "message": "No user with provided secret key"
  },
  "resource": {
    "type": "user",
    "data": null
  }
}

PayDock’s API follows REST principles on status codes returned from our API.

In addition, the API will generally return a detailed error message and any downstream errors. See the right panel for examples

HTTP code Meaning Description
200 Call successful appears on success GET request
201 Created successfully appears on success POST request while creating new essence
400 Error with sent data data which sent has error, description of each of message see below
403 Error with access current customer does not have permission
404 Error with resource current resource does not exist
500 System error appears when server can’t processing request

PayDock vault

"Example response with vault token"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "__v": 0,
      "created_at": "2017-01-24T23:28:14.045Z",
      "updated_at": "2017-01-24T23:28:14.045Z",
      "status": "active",
      "default_source": "5887e30d28e281756b883f64",
      "reference": "TestUniqueReference",
      "first_name": "Test_first_name",
      "last_name": "Test_last_name",
      "email": "[email protected]",
      "_id": "5887e30c28e281756b883f63",
      "payment_sources": [
        {
          "updated_at": "2017-01-24T23:28:14.045Z",
          "vault_token": "dd634c0c-ea3b-4d82-b7fb-5ef2d2949ff6",
          "gateway_id": "58377235377aea03343240cc",
          "card_name": "Test User",
          "expire_month": 1,
          "expire_year": 2019,
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "ref_token": "53774915",
          "status": "active",
          "created_at": "2017-01-24T23:28:13.826Z",
          "_id": "5887e30d28e281756b883f64",
          "type": "card"
        }
      ],
      "statistics": {
        "total_collected_amount": 0,
        "successful_transactions": 0
      },
      "_service": {
        "default_gateway_id": "58377235377aea03343240cc"
      }
    }
  }
}

PayDock provides a PCI compliant vault for payment details. When the vault is enabled, all payment details are stored in the vault. The vault is enabled or disabled across a whole PayDock account, rather than for individual requests.

When the vault is enabled, any time a payment source is added, this information is stored in the vault. This most commonly happens when a payment source is added to a customer or a new customer is created. This is also visible in the response, which includes the id for the vault token, see example to the right (payment_sources -> vault_token).

Recipes

We are building a number of recipes that cover the most common use cases for the PayDock platform.

Recipes available:

Taking a single payment

The simplest use of the PayDock platform is also the most common: taking a payment. This example shows how to take a credit card payment using the Client SDK and Charges.

The best way to take a payment on PayDock is to:

  1. Generate an iFrame using the Client SDK that collects the payment details from a customer - this will convert the payment details to a one-time token.

  2. A “Charge” call will be submitted to PayDock’s API using the token and payment amount to make the payment.

Set up

You’ll need a page to display a payment form and your PayDock public key (How do I get my public key?).

Generating a one-time token using the Client SDK

<!DOCTYPE html>
<html lang="en">

    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
        <title>Donate to save puppies</title>
        <style>iframe {border: 0;width: 100%;height: 300px;}</style>
    </head>

    <body>

        <div class="container">
            <div class="col-sm-5">
                <h1>Donate to save puppies</h1>
                <form id="donation_form" method="post" action="form.php">
                    <div class="form-group">
                        <label>Donate </label>
                        <select class="form-control" name="donation">
                            <option value="100">$100</option>
                            <option value="50">$50</option>
                        </select>
                    </div>
                    <div class="form-group" id="iframeForm">
                    </div>
                    <input type="hidden" id="payment_source" name="payment_source">
                </form>
            </div>
        </div>

        <script src="https://app.paydock.com/v1/widget.umd.min.js"></script>
        <script>
            var widget = new paydock.HtmlWidget('#iframeForm', 'YOUR_PUBLIC_KEY', 'YOUR_GATEWAY_ID'); // public key, gateway_id here
            widget.setEnv('sandbox');
            widget.onFinishInsert('#payment_source', 'payment_source');

            widget.on('finish', function (data) {
                 document.forms[0].submit();
            });

            widget.load();
        </script>

    </body>
</html>

In this example we’ll use the Client SDK to create a one-time token, which we’ll use to make the payment.

In this case, our payment page lets someone select an amount to donate and provides their credit card details. The payment details on the donation page are collected through the PayDock iFrame, which means that the payment details are never sent to through to your server.

The Client SDK attaches the one time token to the form, then submits the form.

Note: The form will not process the transaction until the backend infrastructure is set up to handle the token.

Taking a payment

<?php
$chargeSvc = new Charges();
$res = $chargeSvc->create(10, "AUD")
    ->withToken($_POST["payment_source"])
    ->call();
?>

Next, to take a payment, use the one-time token to add the charge.

When a customer submits the form to make a donation, this sends the token that represents their payment details to the server.

From there, this token and the amount needs to be sent to PayDock to make a payment.

Note: Toggle PHP in the top right to see an example code snippet on the right

Creating a subscription with PayPal Checkout

Another common use case for the PayDock platform is driving subscriptions through the platform with PayPal into your website.

We’re going to use the PayDock Client SDK to generate a payment form with the PayPal Checkout button that we’re going to create a subscription with.

We’ve set the subscription to end after 12 transactions, however you can change this by referring to our subscription parameters.

Add PayPal Checkout Gateway

First, you must connect the PayPal Checkout gateway to PayDock.

Please refer to our PayPal Checkout integration guide.

Generating a one-time token through PayPal Checkout

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
  <title>Title</title>
</head>

<body>
  <div class="container">
    <div class="col-sm-5">

      <form id="button_form" method="post" action="https://app-1508376871.000webhostapp.com/form.php">

        <div class="form-group">
          <label>Amount</label>
          <select class="form-control" name="amount">
                  <option value="100">$100</option>
                  <option value="50">$50</option>
              </select>
        </div>

        <div class="form-group">
          <label>Interval</label>
          <select class="form-control" name="interval">
                  <option value="day">day</option>
                  <option value="week">week</option>
                  <option value="month">month</option>
                  <option value="year">year</option>
              </select>
        </div>

        <button type="button" id="button">
              <img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" align="left" style="margin-right:7px;">
          </button>

        <input type="hidden" id="payment_source_token" name="payment_source_token" />

      </form>

      <input type="text" name="pst" />

    </div>
  </div>


  <script src="https://app.paydock.com/v1/widget.umd.js"></script>
  <script>
    var button = new paydock.CheckoutButton('#button', 'input public key', 'your paypal checkout gateway id');
    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.onFinishInsert('#payment_source_token', 'payment_source_token');
    button.onFinishInsert('#amount', 'amount');
    button.onFinishInsert('#interval', 'interval');

    button.setMeta({
      brand_name: 'Paydock',
      reference: '15',
      first_name: 'receiver-name',
      last_name: 'receiver-last-name',
      phone: '9379992'
    });

    button.on('finish', function(data) {
      console.log('on:finish', data);
      button_form.submit();
    });
  </script>
</body>

</html>

Use our Client SDK to generate a payment form that redirects the customer towards the external PayPal Checkout proces.

After the customer completes the PayPal Checkout process, we’ll generate a one time token that is used to create a subscription by calling the PayDock API.

The payment details on the donation page are collected through the PayPal Checkout process and then tokenised in PayDock meaning the payment details are never sent to your server.

Note: The form will not process the transaction until the backend infrastructure is set up to handle the token.

Creating the subscription

<?php
$subscriptionSvc = new Subscriptions();
$res = $subscriptionSvc->create(1$_POST["amount"], "AUD")
    ->withToken($_POST["payment_source_token"])
    ->withSchedule($_POST["interval"], 1, null, "2020-01-01")
    ->call();
    //You can change the end conditions - please see https://docs.paydock.com/#add-subscription
?>

Next, use the one-time token to create a subscription.

After a customer submits the form, we’ll call the PayDock API and create a subscription using the payment token generated in the previous step.

Note: Toggle PHP in the top right to see an example code snippet on the right

API Reference

The PayDock API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate URL to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

PayDock users can interact with the service in a number of ways.

Name Description
Charges create and query payments
Customers create and manage customer details, with payment information for future payments
Subscriptions create and manage recurring payments
Notifications notifications are automated messages that are triggered from system events
Tokens manages tokens for payment sources
Gateways create and manage gateways

Charges

A Charge is a one-time payment that can be triggered against any of customer’s connected gateways.

Add charges


curl -X "POST" "https://api-sandbox.paydock.com/v1/charges" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",  \"customer\": \ {\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\", \"email\":\"[email protected]\",\"reference\":\"CustomReferenceOfCustomer\", \"payment_source\":,\ {\"address_line1\":\"Testline1\",\"address_line2\":\"Testline2\",\"address_city\":\"Testcity\",\"address_state\":\"Teststate\",\"address_country\":\"AU\",\"address_postcode\":\"1234\",\"gateway_id\":\"584577f7822c66541628fa69\",\"card_name\":\"Test\",\"card_number\":\"4444333322221111\",\"expire_month\":\"01\",\"expire_year\":\"19\",\"card_ccv\":\"123\"}}"
"Charge with one time token"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
        "amount":"10.00",
        "currency":"AUD",
        "reference": "Custom user reference",
        "description": "Custom user description",
        "token":"b76c51ed-9c00-4997-903d-54842826269a"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Charge with credit card"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
            "amount": "10.00",
            "currency": "AUD",
            "reference":"Custom user reference",
            "description":"Custom user description",
            "customer":{
                "first_name": "Test_first_name",
                "last_name": "Test_last_name",
                "email": "[email protected]",            
                "payment_source": {
                    "address_line1": "Testline1",
                    "address_line2": "Testline2",
                    "address_city": "Testcity",
                    "address_state": "Teststate",
                    "address_country": "AU",
                    "address_postcode": "1234",
                    "gateway_id": "551bb4af43daf16f355ab259",
                    "card_name":"Test User",
                    "card_number":"4200000000000000",
                    "expire_month":"01",
                    "expire_year":"17",
                    "card_ccv":"123"
                }
            }
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Charge with bank account"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
      "amount": "13630",
      "currency": "AUD",
      "reference":"Custom user reference",
      "customer":{
        "first_name": "Promise name",
        "last_name": "Promise last name",
        "email": "[email protected]",
        "payment_source": {
            "gateway_id": "58495c9490cde693374afc0c",
            "type": "bank_account",
            "account_name":"Test User",
            "account_number":"411111111111111",
            "address_postcode": "",
            "account_routing":"123123",
            "account_type": "savings",
            "account_holder_type": "personal",
            "account_bank_name": "Bank of Australia"
          }
        }
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Charge with customer id"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
      "amount":"1350",
      "currency":"AUD",
      "reference": "Custom user reference",
      "description": "Custom user description",
      "customer_id":"5857abb356f0cedd2d90a436"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Charge customer with non-default payment source"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
      "amount":"1350",
      "currency":"AUD",
      "reference": "Custom user reference",
      "description": "Custom user description",
      "customer_id":"5857abb356f0cedd2d90a436",
      "payment_source_id":"58209cc5c2ee2574399de888"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});

curl -X "POST" "https://api-sandbox.paydock.com/v1/charges" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\", \"transfer\" : { \"stripe_transfer_group\" : \"stripe_group_id\", \"items\" : [{ \"amount\" : \"currency\" : \"AUD\", \"destination\" : \"<stripe_account_id>\"}, { \"amount\" : 5,  \"currency\" : \"AUD\", \"destination\" : \"<stripe_account_id>\"  }] }, \"customer\": \ {\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\", \"email\":\"[email protected]\",\"reference\":\"CustomReferenceOfCustomer\", \"payment_source\":,\ {\"address_line1\":\"Testline1\",\"address_line2\":\"Testline2\",\"address_city\":\"Testcity\",\"address_state\":\"Teststate\",\"address_country\":\"AU\",\"address_postcode\":\"1234\",\"gateway_id\":\"584577f7822c66541628fa69\",\"card_name\":\"Test\",\"card_number\":\"4444333322221111\",\"expire_month\":\"01\",\"expire_year\":\"19\",\"card_ccv\":\"123\"}}"
"Charge with credit card with stripe connect details"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges',
    body: {
            "amount": "100.00",
            "currency": "AUD",
            "transfer" : {
                    "stripe_transfer_group" : "stripe_group_id",
                    "items" : [{
                        "amount" : 60,
                        "currency" : "AUD",
                        "destination" : "<stripe_account_id>"
                    }, {
                        "amount" : 20,
                        "currency" : "AUD",
                        "destination" : "<stripe_account_id>"
                    }]
            },
            "token": "b76c51ed-9c00-4997-903d-54842826269a"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Charge with one-time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withToken($tokenId)
    ->call();
?>
"Charge with credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Test Name", "123")
    ->includeCustomerDetails("John", "Smith", "[email protected]", "+61414111111")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Charge with debit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withBankAccount("551bb4af43daf16f355ab259", "test", "012003", "456456")
    ->includeCustomerDetails("John", "Smith", "[email protected]", "+61414111111")
    ->call();
?>
"Charge with existing customer"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withCustomerId("551bb4af43daf16f355ab259")
    ->call();
?>
"Charge with existing customer with non-default payment source"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withCustomerId("551bb4af43daf16f355ab259", "551oo4ns43qns16s355no259")
    ->call();
?>
"Charge with credit card with stripe connect details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->create(100, "AUD")
    ->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Test Name", "123")
    ->includeTransfer("stripe_group_id", [[
                        "amount" => 60,
                        "currency" => "AUD",
                        "destination" => "<stripe_account_id>"
                        ], [
                        "amount" => 20,
                        "currency" => "AUD",
                        "destination" => "<stripe_account_id>"
                    ]])
    ->call();
?>
"Example of response (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "charge",
    "data": {
      "external_id": "ea1210e2-7be9-44b2-a9cb-f1d0c94ae646",
      "__v": 1,
      "_id": "585a65fe0daa499b1553c623",
      "amount": 7750,
      "company_id": "582d930808277de017a2a3f4",
      "created_at": "2016-12-21T11:22:38.520Z",
      "currency": "AUD",
      "reference": "Custom user reference",
      "updated_at": "2016-12-21T11:22:49.322Z",
      "user_id": "582d930808277de017a2a3f3",
      "transactions": [
        {
          "_id": "585a65fe0daa499b1553c624",
          "amount": 7750,
          "created_at": "2016-12-21T11:22:38.516Z",
          "currency": "AUD",
          "status": "complete",
          "type": "sale"
        },
        {
          "_id": "585a65fe0daa499b1553c634",
          "amount": 10,
          "created_at": "2016-12-21T11:22:38.516Z",
          "currency": "AUD",
          "status": "complete",
          "type": "transfer"
       },
       {
          "_id": "585a65fe0daa499b1553c625",
          "amount": 20,
          "created_at": "2016-12-21T11:22:38.516Z",
          "currency": "AUD",
          "status": "complete",
          "type": "transfer"
       }
      ],
      "one_off": true,
      "archived": false,
      "customer": {
        "first_name": "",
        "last_name": "Promise last name",
        "email": "[email protected]",
        "reference": "AUS",
        "payment_source": {
          "type": "card",
          "card_name": "Test User",
          "card_number_last4": "1111",
          "expire_month": 4,
          "expire_year": 2020,
          "address_postcode": "3000",
          "gateway_id": "5853d3974f76d26c24e69165",
          "card_scheme": "visa",
          "gateway_name": "Promise Pay",
          "gateway_type": "PromisePay"
        }
      },
      "status": "complete"
    }
  }
}

POST /v1/charges

You can create a charge using:

For a one time charge, payments are made using a one-time token, credit card or direct debit. Otherwise if you are making a payment for an existing customer, it’s simpler to store the payment source with the customer and make a payment using the customer ID.

You can also use stripe connect through Paydock. You can support this by sending through transfer requests inside the transfer object, or by sending through meta parameters. Paydock fully supports all aspects of Stripe Connect, including Direct Charges, Destination Charges and Charges and transfers.

Field Name Description Details
amount Amount of payment Float, required
currency Currency code, AUD by default String, required
token One-time token with all the payment source information String, required for one-time token
description Manually defined description for payments in payment systems String, optional
reference Manually defined reference for customer in payment systems String, optional
transfer Object, optional
stripe_transfer_group Stripe transfer group Id String, optional
items Stripe transfer items Array, required
amount Amount of a transfer Number, required
currency Currency of a transfer String, required
destination Stripe destination account Id String, required
customer_id Existing customer ID String, required for creating charge with customer_id
customer Object with the customer’s information. Not required for one-time token Object, required unless one-time token or customer_id is used
first_name Customer first name String, optional
last_name Customer last name String, optional
email Customer email String, optional
phone Customer phone in E.164 international notation (Example: +12345678901) String, optional
payment_source_id Payment source ID String, optional for creating charge with non-default payment source
payment_source Object with payment information Object, required
gateway_id Gateway ID String, required
type Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments String, optional
account_name Customer account name. Parameter required when using Direct Debit only String, required for bsb
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String, required for bsb
account_number Number of Customer account. Parameter required when using Direct Debit only String, required for bsb and bank account
account_routing Number of Customer account. BSB/Routing/SWIFT/IBAN Number. String, required for bank account
account_holder_type account type (‘personal’ or ‘business’) String, required for bank account
account_bank_name Name of account bank String, required for bank account
card_name Cardholder name (as on card) String, required for card
card_number Card number Integer, required for card
expire_month Card expiration month mm format String, required for card
expire_year Card expiration year yyyy format String, required for card
card_ccv Card CCV number Integer, optional
address_line1 Customer Address, line 1 String, optional
address_line2 Customer Address, line 2 String, optional
address_state Customer Address, State String, optional
address_country Customer Address, Country Code String, optional
address_city Customer Address, City String, optional
address_postcode Customer Address, Postcade Integer, optional
meta Optional object for stripe connect Object, optional
stripe_direct_account_id ID of an existing, connected stripe account. Use to create Stripe connect Direct Charges String, optional
stripe_application_fee A fee in cents that will be applied to the charge and transferred to the application owner’s Stripe account String, optional
stripe_destination_account_id ID of an existing, connected stripe account. Use to create Stripe connect Destination Charges String, optional
stripe_destination_amount The amount to transfer to the destination account without creating an Application Fee String, optional

See also Required Fields by Gateway

Get charges list

curl -X "GET" "https://api-sandbox.paydock.com/v1/charges" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
    var request = require('request');

    request({
        url: 'https://api.paydock.com/v1/charges',
        method: 'GET',
        headers: {
            'content-type' : 'application/json',
            'x-user-secret-key': 'user_secret_key'
        }
    }, function(error, response, body){
        if(error) {
            console.log(error);
        } else {
            console.log(response.statusCode, body);
        }
    });
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->get()
    ->call();
?>
"Example of response"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "charges",
        "data": [
            {
                "_id": "56f3babec1b4578a24b96813",
                "amount": 22,
                "created_at": "2016-03-24T10:00:30.266Z",
                "currency": "AUD",
                "external_id": "000000031b0c71b8",
                "subscription_id": "56b07e1d56b29f4e25b1e731",
                "updated_at": "2016-03-24T10:00:30.507Z",
                "one_off": false,
                "archived": false,
                "customer": {
                    "customer_id": "56b07d6156b29f4e25b1e72a",
                    "first_name": "TEST_FIRST_NAME",
                    "last_name": "TEST_LAST_NAME",
                    "email": "[email protected]",
                    "reference": "CustomReferenceOfCustomer",
                    "payment_source": {
                        "type": "card",
                        "card_name": "test user",
                        "card_number_last4": "1111",
                        "expire_month": 5,
                        "expire_year": 2017,
                        "address_line1": "test",
                        "address_line2": "test",
                        "address_city": "test",
                        "address_postcode": "1234",
                        "address_state": "nsw",
                        "address_country": "AU",
                        "gateway_id": "56b063f856b29f4e25b1e675"
                    }
                },
                "status": "complete"
            }, {
                "_id": "56f3b33ec1b4578a24b967f3",
                "amount": 53.99,
                "created_at": "2016-03-24T09:28:30.118Z",
                "currency": "AUD",
                "external_id": "000000031b0c371e",
                "subscription_id": "56b1c8314f5344b5279d98f9",
                "updated_at": "2016-03-24T09:28:30.387Z",
                "one_off": false,
                "archived": false,
                "customer": {
                    "customer_id": "56b1c8314f5344b5279d98f7",
                    "first_name": "TEST_NEW",
                    "last_name": "TEST_NEW_2",
                    "email": "[email protected]",
                    "reference": "CustomReferenceOfCustomer",
                    "payment_source": {
                        "type": "card",
                        "card_name": "test user",
                        "card_number_last4": "1111",
                        "expire_month": 5,
                        "expire_year": 2017,
                        "address_line1": "TEST_NEW",
                        "address_line2": "TEST_NEW",
                        "address_city": "TEST_NEW",
                        "address_postcode": "1234",
                        "address_state": "nsw",
                        "address_country": "AU",
                        "gateway_id": "56b063f856b29f4e25b1e675"
                    }
                },
                "status": "complete"
            }
    ],
        "count": 2,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/charges

Returns all charges for the account, limited to 100 records.

Get charges list with parameters

curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/?created_at.from=2017-01-01&created_at.to=2017-01-31" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges/?created_at.from=2017-01-01&created_at.to=2017-01-31',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->get()
    ->withParameters(['created_at.from' => '2017-01-01', 'created_at.to'  => '2018-01-31'])
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "charges",
    "data": [
      {
        "_id": "586cb0b1bce8378c54a8aba7",
        "amount": 10,
        "created_at": "2017-01-04T08:22:09.223Z",
        "currency": "AUD",
        "description": "Custom user description",
        "external_id": "684000-Custom user reference",
        "reference": "Custom user reference",
        "updated_at": "2017-01-04T08:22:11.469Z",
        "one_off": true,
        "archived": false,
        "customer": {
          "first_name": "Test_first_name",
          "last_name": "Test_last_name",
          "email": "[email protected]",
          "reference": "CustomReferenceOfCustomer",
          "payment_source": {
            "card_name": "Test User",
            "card_number_last4": "1111",
            "expire_month": 1,
            "expire_year": 19,
            "address_line1": "Testline1",
            "address_line2": "Testline2",
            "address_city": "Testcity",
            "address_postcode": "1234",
            "address_state": "Teststate",
            "address_country": "AU",
            "gateway_id": "586cb09dbce8378c54a8aba6",
            "card_scheme": "visa",
            "gateway_name": "Nab",
            "gateway_type": "Nab"
          }
        },
        "status": "complete"
      },
      {
        "_id": "586bba1abce8378c54a8ab9b",
        "amount": 10,
        "created_at": "2017-01-03T14:50:02.709Z",
        "currency": "AUD",
        "description": "Custom user description",
        "external_id": "680246-Custom user reference",
        "reference": "Custom user reference",
        "updated_at": "2017-01-03T14:50:04.596Z",
        "one_off": true,
        "archived": false,
        "customer": {
          "first_name": "Test_first_name",
          "last_name": "Test_last_name",
          "email": "[email protected]",
          "reference": "CustomReferenceOfCustomer",
          "payment_source": {
            "card_name": "Test User",
            "card_number_last4": "1111",
            "expire_month": 1,
            "expire_year": 19,
            "address_line1": "Testline1",
            "address_line2": "Testline2",
            "address_city": "Testcity",
            "address_postcode": "1234",
            "address_state": "Teststate",
            "address_country": "AU",
            "gateway_id": "586bba03bce8378c54a8ab9a",
            "card_scheme": "visa",
            "gateway_name": "Nab",
            "gateway_type": "Nab"
          }
        },
        "status": "complete"
      }
    ],
    "count": 2,
    "limit": 100,
    "skip": 0
  }
}

GET /v1/charges/?skip={skip}&limit={limit}&subscription_id={subscription_id}&gateway_id={gateway_id}&company_id={company_id}&created_at.from={created_at.from}&created_at.to={created_at.to}&search={search}&status={status}&archived={archived}&reference={reference}

Retrieving data on existing charges can be driven by number of action parameters set in URI path.

Field Name Description Details
skip Pagination parameter to skip first n transactions from list, default = 0 Number, optional
limit Pagination parameter to limit output to n , default = 100 , maximum value = 1000 Number, optional
subscription_id To only fetch transactions related to particular subscription String, optional
gateway_id ID of a gateway with which charges were created String, optional
company_id ID of a company with which charges were created String, optional
created_at.from Parameter to set range of created transactions date (yyyy-mm-dd) String, optional
created_at.to Parameter to set range of created transactions date ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) String, optional
search Word of phrase Customer want to search in created charges (search works by fields: First, Last names and Emails) String, optional
status Status could be: complete, failed, archived, requested, refund_requested, refunded, inprogress String, optional
archived Set to true to show all the archived charges. Default: false Boolean, optional
reference Charge reference declared on creation. transaction_external_id can also be used to search by reference String, optional

Get single charge

curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->get()
    ->withChargeId("123123123")
    ->call();
?>
"Example of response"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "charge",
    "data": {
      "_id": "585ba834e45b75bc368087b3",
      "created_at": "2016-12-22T10:17:24.504Z",
      "updated_at": "2016-12-22T10:17:41.072Z",
      "company_id": "582d930808277de017a2a3f4",
      "user_id": "582d930808277de017a2a3f3",
      "amount": 17,
      "currency": "AUD",
      "subscription_id": "585ba520e45b75bc368087ab",
      "reference": "Custom reference",
      "description": "Custom description",
      "__v": 1,
      "external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
      "transactions": [
        {
          "created_at": "2016-12-22T10:17:24.495Z",
          "amount": 17,
          "currency": "AUD",
          "_id": "585ba834e45b75bc368087b4",
          "service_logs": [
            {
              "req": {
                "account_id": "70b234c5-3af7-41b5-9992-96a014eab056",
                "amount": 1700,
                "zip": "3000",
                "email": "[email protected]",
                "currency": "AUD",
                "country": "AUS",
                "retain_account": "true"
              },
              "response_body": "{\"charges\":{\"id\":\"ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"name\":\"Charge ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"created_at\":\"2016-12-22T10:17:27.108Z\",\"updated_at\":\"2016-12-22T10:17:33.275Z\",\"state\":\"completed\",\"buyer_fees\":0,\"seller_fees\":0,\"credit_card_fee\":0,\"status\":22500,\"amount\":1700,\"custom_data\":null,\"account_id\":\"70b234c5-3af7-41b5-9992-96a014eab056\",\"account_type\":\"credit card\",\"promisepay_fee\":89,\"currency\":\"AUD\",\"payment_method\":\"charge\",\"buyer_name\":\"Oleg cCdekrigin\",\"buyer_email\":\"[email protected]\",\"buyer_zip\":\"3000\",\"buyer_country\":\"AUS\",\"related\":{\"buyers\":\"950074ce-bf25-4a8f-ac61-d4c3394ea14a\",\"sellers\":\"5fbeeee6fb58c2519703b115cde28573\"},\"links\":{\"self\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"buyers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/buyers\",\"sellers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/sellers\",\"status\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/status\",\"fees\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/fees\",\"transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/transactions\",\"batch_transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/batch_transactions\"}}}",
              "created_at": "2016-12-22T10:17:41.041Z",
              "statusCode": 0,
              "_id": "585ba845e45b75bc368087b5"
            }
          ],
          "status": "complete",
          "type": "sale"
        }
      ],
      "one_off": false,
      "archived": false,
      "customer": {
        "customer_id": "585ba514e45b75bc368087a8",
        "first_name": "Oleg",
        "last_name": "cCdekrigin",
        "email": "[email protected]",
        "phone": "+123451678910",
        "payment_source": {
          "type": "card",
          "card_name": "Test User",
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "expire_month": 10,
          "expire_year": 2020,
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_postcode": "3000",
          "address_state": "Teststate",
          "address_country": "AU",
          "gateway_id": "5853e89c2bd79538605a3fb6"
        }
      },
      "status": "complete"
    }
  }
}

GET /v1/charges/{_id}

Retrieves data on a charge with specified ID.

Field Name Description Details
_id Payment Identifier String, optional

Refund Charge

curl -X "POST" "https://api-sandbox.paydock.com/v1/charges/{_id}/refunds" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/charges/{_id}/refunds',
    method: 'POST',
    body: {"amount":"50"},
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->refund()
    ->withChargeId("123123123")
    ->call();
?>
"Example of response (201)"
{
  "status": 200,
  "error": null,
  "resource": {
      "type": "charge",
      "data": {
          "__v": 3,
          "_id": "55d433f7194516d824af36f6",
          "amount": 100,
          "company_id": "5584018a27b2cf0b1e4f1a6c",
          "created_at": "2015-08-19T07:44:55.874Z",
          "currency": "AUD",
          "external_id": "ch_6p5Q1DvuPkMhgS",
          "updated_at": "2015-08-19T07:45:15.631Z",
          "user_id": "5584018a27b2cf0b1e4f1a6b",
          "transactions": [
              {
                  "_id": "55d433f7194516d824af36f7",
                  "amount": 100,
                  "created_at": "2015-08-19T07:44:55.872Z",
                  "currency": "AUD",
                  "service_logs": [
                      {
                          "req": {
                              "body": {
                                  "amount": 10000,
                                  "currency": "AUD",
                                  "card": {
                                      "number": "************4242",
                                      "exp_month": "05",
                                      "exp_year": "17",
                                      "cvc": "123",
                                      "name": "************",
                                      "address_line1": "TestL1",
                                      "address_line2": "TestL2",
                                      "address_city": "TestCity",
                                      "address_zip": "1234",
                                      "address_state": "TestState",
                                      "address_country": "AU"
                                  }
                              }
                          },
                          "response_body": {
                              "id": "ch_6p5Q1DvuPkMhgS",
                              "object": "charge",
                              "created": 1439970296,
                              "livemode": false,
                              "paid": true,
                              "status": "paid",
                              "amount": 10000,
                              "currency": "aud",
                              "refunded": false,
                              "source": {
                                  "id": "card_6p5QWMz09Em7GV",
                                  "object": "card",
                                  "last4": "4242",
                                  "brand": "Visa",
                                  "funding": "credit",
                                  "exp_month": 5,
                                  "exp_year": 2017,
                                  "fingerprint": "tcKbROx2vZva0RVt",
                                  "country": "US",
                                  "name": "Test Test",
                                  "address_line1": "TestL1",
                                  "address_line2": "TestL2",
                                  "address_city": "TestCity",
                                  "address_state": "TestState",
                                  "address_zip": "1234",
                                  "address_country": "AU",
                                  "cvc_check": "pass",
                                  "address_line1_check": "pass",
                                  "address_zip_check": "pass",
                                  "tokenization_method": null,
                                  "dynamic_last4": null,
                                  "customer": null,
                                  "type": "Visa"
                              },
                              "captured": true,
                              "card": {
                                  "id": "card_6p5QWMz09Em7GV",
                                  "object": "card",
                                  "last4": "4242",
                                  "brand": "Visa",
                                  "funding": "credit",
                                  "exp_month": 5,
                                  "exp_year": 2017,
                                  "fingerprint": "tcKbROx2vZva0RVt",
                                  "country": "US",
                                  "name": "Test Test",
                                  "address_line1": "TestL1",
                                  "address_line2": "TestL2",
                                  "address_city": "TestCity",
                                  "address_state": "TestState",
                                  "address_zip": "1234",
                                  "address_country": "AU",
                                  "cvc_check": "pass",
                                  "address_line1_check": "pass",
                                  "address_zip_check": "pass",
                                  "tokenization_method": null,
                                  "dynamic_last4": null,
                                  "customer": null,
                                  "type": "Visa"
                              },
                              "balance_transaction": "txn_6p5Q4SibwxLFaA",
                              "failure_message": null,
                              "failure_code": null,
                              "amount_refunded": 0,
                              "customer": null,
                              "invoice": null,
                              "description": "",
                              "dispute": null,
                              "statement_descriptor": null,
                              "receipt_email": null,
                              "receipt_number": null,
                              "shipping": null,
                              "destination": null,
                              "application_fee": null,
                              "refunds": [],
                              "statement_description": null,
                              "fee": 239,
                              "fee_details": [
                                  {
                                      "amount": 239,
                                      "currency": "usd",
                                      "type": "stripe_fee",
                                      "description": "Stripe processing fees",
                                      "application": null,
                                      "amount_refunded": 0
                                  }
                              ],
                              "uncaptured": null,
                              "disputed": false
                          },
                          "created_at": "2015-08-19T07:44:56.819Z",
                          "statusCode": 0,
                          "_id": "55d433f8194516d824af36f8"
                      }
                  ],
                  "status": "complete",
                  "type": "sale"
              },
              {
                  "pended_at": "2015-08-20T07:45:15.629Z",
                  "_id": "55d4340a194516d824af36f9",
                  "amount": 50,
                  "created_at": "2015-08-19T07:45:14.406Z",
                  "currency": "AUD",
                  "service_logs": [
                      {
                          "req": {
                              "body": "ch_6p5Q1DvuPkMhgS"
                          },
                          "response_body": {
                              "id": "re_6p5QyNU9KEMqKG",
                              "amount": 5000,
                              "currency": "aud",
                              "created": 1439970315,
                              "object": "refund",
                              "balance_transaction": "txn_6p5Qx6Z61NwhKY",
                              "charge": "ch_6p5Q1DvuPkMhgS",
                              "receipt_number": null,
                              "reason": null
                          },
                          "created_at": "2015-08-19T07:45:15.620Z",
                          "statusCode": 0,
                          "_id": "55d4340b194516d824af36fa"
                      }
                  ],
                  "status": "requested",
                  "type": "refund"
              }
          ],
          "one_off": true,
          "customer": {
              "first_name": "StripeF",
              "last_name": "StripeL",
              "email": "[email protected]",
              "reference": "CustomReferenceOfCustomer",
              "payment_source": {
                  "card_name": "Test Test",
                  "card_number_last4": "4242",
                  "expire_month": 5,
                  "expire_year": 17,
                  "address_line1": "TestL1",
                  "address_line2": "TestL2",
                  "address_city": "TestCity",
                  "address_postcode": "1234",
                  "address_state": "TestState",
                  "address_country": "AU",
                  "gateway_id": "55840a4c27b2cf0b1e4f1a6f",
                  "card_scheme": "visa",
                  "gateway_name": "strp",
                  "gateway_type": "Stripe"
              }
          },
          "status": "refund_requested"
      }
  }
}

POST /v1/charges/{_id}/refunds

POST refund request of specified transaction.

Field Name Description Details
_id Payment Identifier String, required
amount Amount to be refunded (must not exceed original transaction amount) Float, optional

Archive Charge

curl -X "DELETE" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->archive("123123123")
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "charge",
    "data": {
      "_id": "585ba834e45b75bc368087b3",
      "created_at": "2016-12-22T10:17:24.504Z",
      "updated_at": "2016-12-22T10:29:41.100Z",
      "company_id": "582d930808277de017a2a3f4",
      "user_id": "582d930808277de017a2a3f3",
      "amount": 17,
      "currency": "AUD",
      "subscription_id": "585ba520e45b75bc368087ab",
      "reference": "Custom reference",
      "description": "Custom description",
      "__v": 1,
      "external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
      "transactions": [
        {
          "created_at": "2016-12-22T10:17:24.495Z",
          "amount": 17,
          "currency": "AUD",
          "_id": "585ba834e45b75bc368087b4",
          "service_logs": [
            {
              "req": {
                "account_id": "70b234c5-3af7-41b5-9992-96a014eab056",
                "amount": 1700,
                "zip": "3000",
                "email": "[email protected]",
                "currency": "AUD",
                "country": "AUS",
                "retain_account": "true"
              },
              "response_body": "{\"charges\":{\"id\":\"ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"name\":\"Charge ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"created_at\":\"2016-12-22T10:17:27.108Z\",\"updated_at\":\"2016-12-22T10:17:33.275Z\",\"state\":\"completed\",\"buyer_fees\":0,\"seller_fees\":0,\"credit_card_fee\":0,\"status\":22500,\"amount\":1700,\"custom_data\":null,\"account_id\":\"70b234c5-3af7-41b5-9992-96a014eab056\",\"account_type\":\"credit card\",\"promisepay_fee\":89,\"currency\":\"AUD\",\"payment_method\":\"charge\",\"buyer_name\":\"Oleg cCdekrigin\",\"buyer_email\":\"[email protected]\",\"buyer_zip\":\"3000\",\"buyer_country\":\"AUS\",\"related\":{\"buyers\":\"950074ce-bf25-4a8f-ac61-d4c3394ea14a\",\"sellers\":\"5fbeeee6fb58c2519703b115cde28573\"},\"links\":{\"self\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"buyers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/buyers\",\"sellers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/sellers\",\"status\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/status\",\"fees\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/fees\",\"transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/transactions\",\"batch_transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/batch_transactions\"}}}",
              "created_at": "2016-12-22T10:17:41.041Z",
              "statusCode": 0,
              "_id": "585ba845e45b75bc368087b5"
            }
          ],
          "status": "complete",
          "type": "sale"
        }
      ],
      "one_off": false,
      "archived": true,
      "customer": {
        "customer_id": "585ba514e45b75bc368087a8",
        "first_name": "Oleg",
        "last_name": "cCdekrigin",
        "email": "[email protected]",
        "phone": "+123451678910",
        "payment_source": {
          "type": "card",
          "card_name": "Test User",
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "expire_month": 10,
          "expire_year": 2020,
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_postcode": "3000",
          "address_state": "Teststate",
          "address_country": "AU",
          "gateway_id": "5853e89c2bd79538605a3fb6"
        }
      },
      "status": "complete"
    }
  }
}

DELETE /v1/charges/{_id}

Archive Charge to hide it it from charges list. You can still retrieve archived charges, see [Get charges list with parameters

](#get-charges-list-with-parameters)

Field Name Description Details
_id Payment Identifier String, required

Get archived charges list

curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/?archived=true" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/charges/?archived=true',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Charges();
$res = $svc->get()
    ->withFilter(["archived" => "true"])
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "charges",
    "data": [
      {
        "_id": "585ba834e45b75bc368087b3",
        "created_at": "2016-12-22T10:17:24.504Z",
        "updated_at": "2016-12-22T10:29:41.100Z",
        "amount": 17,
        "currency": "AUD",
        "subscription_id": "585ba520e45b75bc368087ab",
        "reference": "Custom reference",
        "description": "Custom description",
        "external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
        "one_off": false,
        "archived": true,
        "customer": {
          "customer_id": "585ba514e45b75bc368087a8",
          "first_name": "Oleg",
          "last_name": "cCdekrigin",
          "email": "[email protected]",
          "phone": "+123451678910",
          "payment_source": {
            "type": "card",
            "card_name": "Test User",
            "card_number_last4": "1111",
            "card_scheme": "visa",
            "expire_month": 10,
            "expire_year": 2020,
            "address_line1": "Testline1",
            "address_line2": "Testline2",
            "address_city": "Testcity",
            "address_postcode": "3000",
            "address_state": "Teststate",
            "address_country": "AU",
            "gateway_id": "5853e89c2bd79538605a3fb6"
          }
        },
        "status": "complete"
      }
    ],
    "count": 1,
    "limit": 100,
    "skip": 0
  }
}

Get archived charges list

GET /v1/charges/?archived=true

Customers

A customer represents an individual who can make payments. Through the use of vaulted tokens, Customers store one or more payment sources, so that payment information doesn’t need to be collected again. Customers can also be associated with Subscriptions and can have Charges added against them.

A customer must have at least one payment source (eg. credit card) that can be used for payment.

Add customer

curl -X "POST" "https://api-sandbox.paydock.com/v1/customers" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"reference\":\"TestUniqueReference\",\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"email\":\"[email protected]\",\"phone\":\"+123451678910\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Testline1\", \"address_line2\":\"[email protected]\", \"address_city\":\"Testcity\", \"address_state\":\"Teststate\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Test User\", \"account_number\":\"1234\", \"account_bsb\":\"123123\"}}"
"Example using one-time token"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers',
    method: 'POST',
    body: {
        "reference": "Custom user reference",
        "token":"b76c51ed-9c00-4997-903d-54842826269a"
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Example using credit card details"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers',
    method: 'POST',
    body: {
        "reference":"TestUniqueReference",
        "first_name": "Test_first_name",
        "last_name": "Test_last_name",
        "email": "[email protected]",
        "phone": "+123451678910",
        "payment_source": {
            "address_line1": "Testline1",
            "address_line2": "Testline2",
            "address_city": "Testcity",
            "address_state": "Teststate",
            "address_country": "AU",
            "address_postcode": "1234",
            "gateway_id": "551bb4af43daf16f355ab259",
            "card_name":"Test User",
            "card_number":"4200000000000000",
            "expire_month":"01",
            "expire_year":"17",
            "card_ccv":"123"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Example using bsb details"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers',
    method: 'POST',
    body: {
        "reference":"TestUniqueReference",
        "first_name": "Test_first_name",
        "last_name": "Test_last_name",
        "email": "[email protected]",
        "phone": "+123451678910",
        "payment_source": {
            "address_line1": "Testline1",
            "address_line2": "Testline2",
            "address_city": "Testcity",
            "address_state": "Teststate",
            "address_country": "AU",
            "address_postcode": "1234",
            "gateway_id": "586bb6f3bce8378c54a8ab99",
            "type": "bsb",
            "account_number": "45679",
            "account_bsb": "123",
            "account_name": "User name"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Example using one-time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc->create("John", "Smith")
    ->withToken($tokenId)
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Example using credit card details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc->create("John", "Smith")
    ->withCreditCard("586bb6f3bce8378c54a8ab99", "4111111111111111", "2020", "10", "Test Name", "123")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Example using debit details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc->create("John", "Smith")
    ->withBankAccount("586bb6f3bce8378c54a8ab99", "test", "012003", "456456")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Example of response (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "__v": 0,
      "created_at": "2016-12-22T10:36:08.171Z",
      "updated_at": "2016-12-22T10:36:08.171Z",
      "status": "active",
      "default_source": "585bac98e45b75bc368087b8",
      "first_name": "Oleg",
      "last_name": "cCdekrigin",
      "email": "[email protected]",
      "phone": "+123451678910",
      "_id": "585bac95e45b75bc368087b7",
      "payment_sources": [
        {
          "updated_at": "2016-12-22T10:36:08.170Z",
          "vault_token": "94344342-a427-4b9f-9476-f64386d5bba9",
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_state": "Teststate",
          "address_country": "AU",
          "address_postcode": "3000",
          "gateway_id": "5853e89c2bd79538605a3fb6",
          "card_name": "Test User",
          "expire_month": 10,
          "expire_year": 2020,
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "ref_token": "754a2e68-32f9-437c-9544-afc6bef2beb8",
          "status": "active",
          "created_at": "2016-12-22T10:36:08.083Z",
          "_id": "585bac98e45b75bc368087b8",
          "type": "card"
        }
      ],
      "statistics": {
        "total_collected_amount": 0,
        "successful_transactions": 0
      },
      "_service": {
        "default_gateway_id": "5853e89c2bd79538605a3fb6"
      }
    }
  }
}
"Example of response with bsb details (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "__v": 0,
      "created_at": "2017-01-10T11:37:51.454Z",
      "updated_at": "2017-01-10T11:37:51.454Z",
      "status": "active",
      "default_source": "5874c78f88146959c9f9a41c",
      "reference": "TestUniqueReference",
      "first_name": "Test_first_name",
      "last_name": "Test_last_name",
      "email": "[email protected]",
      "phone": "+123451678910",
      "_id": "5874c78f88146959c9f9a41b",
      "payment_sources": [
        {
          "updated_at": "2017-01-10T11:37:51.454Z",
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_state": "Teststate",
          "address_country": "AU",
          "address_postcode": "1234",
          "gateway_id": "586bb6f3bce8378c54a8ab99",
          "account_bsb": "123",
          "account_name": "User name",
          "ref_token": "CS-ECF35255704871D4",
          "status": "active",
          "created_at": "2017-01-10T11:37:51.450Z",
          "_id": "5874c78f88146959c9f9a41c",
          "type": "bsb"
        }
      ],
      "statistics": {
        "total_collected_amount": 0,
        "successful_transactions": 0
      },
      "_service": {
        "default_gateway_id": "586bb6f3bce8378c54a8ab99"
      }
    }
  }
}

POST /v1/customers

You can create a customer using:

Field Name Description Details
token One-time token with all payment source information. Required for adding a customer with a one-time token String required, if adding customer with token
first_name Customer first name String, optional
last_name Customer last name String, optional
email Customer email String, optional
phone Customer phone in E.164 international notation (Example: +12345678901) String, optional
reference Customer unique reference. This is customer internal reference number for a customer String, optional
payment_source Object which includes all payment information Object required, if adding customer direct debit or credit
gateway_id Gateway ID String required
type Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments String, optional
account_name Customer account name. Parameter required when using Direct Debit only String required bank account and bsb only
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String required bsb account only
account_routing Account routing number. BSB/Routing/SWIFT/IBAN Number. String required bank account only
account_number Number of customer bank account. Parameter required when using Direct Debit only String required bank account and bsb only
account_holder_type Account type (‘personal’ or ‘business’) String required bank account only
account_bank_name Name of account bank String required bank account only
card_name Cardholder name (as on card) String required card only
card_number Card number Integer required card only
expire_month Card expiration month mm format String required card only
expire_year Card expiration year yyyy format String required card only
card_ccv Card CCV number. Depending on customer gateway and configuration, this may be required Integer, optional
address_line1 Customer Address, line 1 String, optional
address_line2 Customer Address, line 2 String, optional
address_city Customer Address, City String, optional
address_postcode Customer Address, Postcade String, optional
address_state Customer Address, State String, optional
address_country Customer Address, Country Code String, optional
meta Object where can be specified optional information about customer Object, optional
user_id existing user on payment system side (used by Assembly payments). Paydock matches customer on Assembly payments by this id, and adds new payment source String optional

See also Required fields by Gateway

Get customer list

curl -X "GET https://api-sandbox.paydock.com/v1/customers" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->get()
    ->call();
?>
"Example of response"
{  
   "status":201,
   "error":null,
   "resource":{  
      "type":"customer",
      "data":[  
         {  
            "_id":"585bac95e45b75bc368087b7",
            "created_at":"2016-12-22T10:36:08.171Z",
            "updated_at":"2016-12-22T10:36:08.171Z",
            "status":"active",
            "_source_ip_address":"::1",
            "default_source":"585bac98e45b75bc368087b8",
            "company_id":"582d930808277de017a2a3f4",
            "user_id":"582d930808277de017a2a3f3",
            "first_name":"Oleg",
            "last_name":"cCdekrigin",
            "email":"[email protected]",
            "phone":"+123451678910",
            "payment_sources":[  
               {  
                  "updated_at":"2016-12-22T10:36:08.170Z",
                  "vault_token":"94344342-a427-4b9f-9476-f64386d5bba9",
                  "address_line1":"Testline1",
                  "address_line2":"Testline2",
                  "address_city":"Testcity",
                  "address_state":"Teststate",
                  "address_country":"AU",
                  "address_postcode":"3000",
                  "gateway_id":"5853e89c2bd79538605a3fb6",
                  "card_name":"Test User",
                  "expire_month":10,
                  "expire_year":2020,
                  "card_number_last4":"1111",
                  "card_scheme":"visa",
                  "ref_token":"754a2e68-32f9-437c-9544-afc6bef2beb8",
                  "status":"active",
                  "created_at":"2016-12-22T10:36:08.083Z",
                  "_id":"585bac98e45b75bc368087b8",
                  "type":"card"
               }
            ],
            "archived":false,
            "statistics":{  
               "total_collected_amount":0,
               "successful_transactions":0
            }
         }
      ]
   }
}

GET /v1/customers

Returns all customers for the account, limited to 100 records.

Get customer list with parameters

curl -X "GET https://api-sandbox.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->get()
    ->withParameters(["search" => "test", "sortkey" => "firstname"])
    ->call();
?>
"Example of response (200)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "customers",
        "data": [
            {
                "created_at": "2015-08-26T05:45:21.293Z",
                "updated_at": "2015-08-26T05:45:32.587Z",
                "status": "active",
                "default_source": "55dd5271036a2d542c1efbfc",
                "first_name": "test2",
                "last_name": "test2",
                "email": "[email protected]",
                "_id": "55dd5270036a2d542c1efbfb",
                "__v": 0,
                "payment_sources": [
                    {
                        "updated_at": "2015-08-26T05:45:32.586Z",
                        "address_line1": "test2",
                        "address_line2": "test2",
                        "address_city": "test2",
                        "address_state": "test2",
                        "address_country": "AU",
                        "address_postcode": "1233",
                        "gateway_id": "55840a4c27b2cf0b1e4f1a6f",
                        "card_name": "test2 test2",
                        "expire_month": 5,
                        "expire_year": 2017,
                        "card_number_last4": "4242",
                        "card_scheme": "visa",
                        "ref_token": "cus_6rg5sC4wp2My8I",
                        "status": "active",
                        "created_at": "2015-08-26T05:45:21.290Z",
                        "_id": "55dd5271036a2d542c1efbfc",
                        "type": "card"
                    }
                ],
                "statistics": {
                    "total_collected_amount": 0,
                    "successful_transactions": 0
                }
            },
            {
                "created_at": "2015-08-25T13:58:57.498Z",
                "updated_at": "2015-08-25T13:59:16.884Z",
                "status": "active",
                "default_source": "55dc74a16379cd122541764e",
                "first_name": "test",
                "last_name": "test",
                "email": "[email protected]",
                "_id": "55dc74a06379cd122541764d",
                "__v": 0,
                "payment_sources": [
                    {
                        "updated_at": "2015-08-25T13:59:16.884Z",
                        "address_line1": "test",
                        "address_line2": "test",
                        "address_city": "test",
                        "address_state": "test",
                        "address_country": "AU",
                        "address_postcode": "1234",
                        "gateway_id": "55840a4c27b2cf0b1e4f1a6f",
                        "card_name": "test test",
                        "expire_month": 5,
                        "expire_year": 2017,
                        "card_number_last4": "4242",
                        "card_scheme": "visa",
                        "ref_token": "cus_6rQooHxT3HF3p6",
                        "status": "active",
                        "created_at": "2015-08-25T13:58:57.476Z",
                        "_id": "55dc74a16379cd122541764e",
                        "type": "card"
                    }
                ],
                "statistics": {
                    "total_collected_amount": 0,
                    "successful_transactions": 0
                }
            }
        ],
        "count": 2,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&payment_source_id={id}&id={id}&reference={reference}&archived={true/false}

Retrieving data on existing customers can be driven by number of action parameters set in URI path.

Field Name Description Details
skip Pagination parameter to skip first n customers from list, default = 0 Number, optional
limit Pagination parameter to limit output to n , default = 100 , maximum value = 1000 Number, optional
search Text search parameter (search in fields firstname, lastname, email) String, optional
sortkey Sorting key parameter i.e. firstname, lastname, email, startdate, ASC direction by default String, optional
sortdirection Sorting order direction parameter (ASC by default, only value that affects is DESC) String, optional
gateway_id ID of a gateway with which customers default payments source was created String, optional
payment_source_id ID of a stored customers payment_source String, optional
id ID of particular customer String, optional
reference Reference of particular customer String, optional
archived Set to true to show all the archived (deleted) customers. Default: false Boolean, optional

Response:

Field Name Description Details
type Type of returned resource String
data Returned data Array
query_token Token which contains query data used for further queries String
count Pagination param. Count of all users Integer
limit Pagination param. Limit of users Integer
skip Pagination param. Skip users from start Integer

Get customer payment sources by query token

curl -X "GET https://api-sandbox.paydock.com/v1/customers/payment_sources?query_token={query_token}&public_key={public_key}" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/customers/payment_sources?query_token={query_token}&public_key={public_key}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->get()
    ->withParameters(["id" => "55dc74a06379cd122541764d"])
    ->call();
?>
"Example of response"

{
    "status": 200,
    "error": null,
    "resource": {
        "type": "payment_sources",
        "data": [
            {
                "_id": "59c0c403a6976f1037df4f6b",
                "card_number_last4": "1111",
                "card_scheme": "visa",
                "type": "card",
                "gateway_id": "58377235377aea03343240cc",
                "customer_id": "59c0c402a6976f1037df4f6a",
                "primary": true
            }
        ],
        "count": 1,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/customers/payment_sources?query_token={query_token}&public_key={public_key}

Get payment sources of customers by query_token generated from getCustomers with params endpoint

Field Name Description Details
query_token token that represents a customer String
public_key public key from your Paydock account String

Get single customer

curl -X "GET https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->get()
    ->withCustomerId("59c0c402a6976f1037df4f6a")
    ->call();
?>
"Example of response"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "_id": "585ba514e45b75bc368087a8",
      "created_at": "2016-12-22T10:04:06.418Z",
      "updated_at": "2016-12-22T10:04:06.418Z",
      "status": "active",
      "default_source": "585ba516e45b75bc368087a9",
      "first_name": "Oleg",
      "last_name": "cCdekrigin",
      "email": "[email protected]",
      "phone": "+123451678910",
      "__v": 0,
      "payment_sources": [
        {
          "updated_at": "2016-12-22T10:04:06.417Z",
          "vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_state": "Teststate",
          "address_country": "AU",
          "address_postcode": "3000",
          "gateway_id": "5853e89c2bd79538605a3fb6",
          "card_name": "Test User",
          "expire_month": 10,
          "expire_year": 2020,
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "ref_token": "70b234c5-3af7-41b5-9992-96a014eab056",
          "status": "active",
          "created_at": "2016-12-22T10:04:06.370Z",
          "_id": "585ba516e45b75bc368087a9",
          "type": "card"
        }
      ],
      "statistics": {
        "currency": {
          "AUD": {
            "count": 2,
            "total_amount": 27
          }
        },
        "total_collected_amount": 27,   
        "successful_transactions": 2
      },
      "_service": {
        "default_gateway_id": "5853e89c2bd79538605a3fb6"
      }
    }
  }
}

GET /v1/customers/{_id}

Retrieves data on the customer with specified ID.

Field Name Description Details
_id ID of particular customer you want to get full information String, required

Update customer

"add a new payment source from a one time token"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"token\":\"6a40af93-7410-4383-907f-b9d7b2594cd0\",\"reference\":\"Custom edit reference new\",\"default_source\":\"56418767811923162676983c\"}"
"add a new payment source from a one time token"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers/{_id}',
    method: 'POST',
    body: {
        "token":"6a40af93-7410-4383-907f-b9d7b2594cd0",
        "reference":"Custom edit reference new",
        "default_source":"56418767811923162676983c"
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"add a new payment source from a one time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "John", "Smith", "[email protected]", "+61414123123")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->withToken("6a40af93-7410-4383-907f-b9d7b2594cd0")
    ->call();
?>
"add a new credit card"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"reference\":\"TestUniqueReference\",\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"email\":\"[email protected]\",\"phone\":\"+123451678910\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Testline1\", \"address_line2\":\"[email protected]\", \"address_city\":\"Testcity\", \"address_state\":\"Teststate\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"card_name\":\"Test UserEdit\",\"card_number\":\"4987654321098769\",\"expire_month\": \"02\",\"expire_year\":\"19\",\"card_ccv\":\"223\"}}"
"add a new credit card"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers/{_id}',
    method: 'POST',
    body: {
        "reference":"TestUniqueReference",
        "first_name": "TestFirstNameEdit",
        "last_name": "TestLastNameEdit",
        "email": "[email protected]",
        "default_source":"5565b4c5648a0df61455a689"
        "payment_source": {
            "address_line1": "TestAddrLine1Edit",
            "address_line2": "TestAddrLine2Edit",
            "address_city": "TestCityEdit",
            "address_state": "TestStateEdit",
            "address_country": "AU",
            "address_postcode": "2234",
            "gateway_id": "55534a8ba28d339a100e741c",
            "card_name":"Test UserEdit",
            "card_number":"4987654321098769",
            "expire_month": "02",
            "expire_year":"19",
            "card_ccv":"223"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"add a new credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "John", "Smith", "[email protected]", "+61414123123")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->withCreditCard("55534a8ba28d339a100e741c", "4111111111111111", "2020", "10", "Test Name", "123")
    ->call();
?>
"add a new bank account"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"reference\":\"TestUniqueReference\",\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"email\":\"[email protected]\",\"phone\":\"+123451678910\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Testline1\", \"address_line2\":\"[email protected]\", \"address_city\":\"Testcity\", \"address_state\":\"Teststate\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Test User\", \"account_number\":\"1234\", \"account_bsb\":\"123123\"}}"
"add a new bank account"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers/{_id}',
    method: 'POST',
    body: {
        "reference":"TestUniqueReference",
        "first_name": "TestFirstNameEdit",
        "last_name": "TestLastNameEdit",
        "email": "[email protected]",
        "default_source":"5565b4c5648a0df61455a689",
        "payment_source": {
            "gateway_id": "586bb6f3bce8378c54a8ab99",
            "type": "bsb",
            "account_number": "456778",
            "account_bsb": "123",
            "account_name": "User name edited"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"add a new bank account"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "John", "Smith", "[email protected]", "+61414123123")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->withBankAccount(586bb6f3bce8378c54a8ab99, "test", "012003", "456456")
    ->call();
?>
"convert token from another payment gateway"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"payment_source\":\ {\"gateway_id\":\"551bb4af43daf16f355ab259\", \"vault_token\":\"dd193f39-519d-41b2-8396-097d9e76eec0\"}}"
"convert token from another payment gateway"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/customers/{_id}',
    method: 'POST',
    body: {
        "payment_source": {
            "gateway_id": "586bb6f3bce8378c54a8ab99",
            "vault_token": "dd193f39-519d-41b2-8396-097d9e76eec0"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"convert token from another payment gateway"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8")
    ->withVaultToken("586bb6f3bce8378c54a8ab99", "dd193f39-519d-41b2-8396-097d9e76eec0")
    ->call();
?>
"Example of response using bsb details"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "customer",
        "data": {
            "_id": "5565b4c5648a0df61455a688",
            "created_at": "2015-05-27T12:12:53.525Z",
            "updated_at": "2015-05-27T13:26:22.401Z",
            "status": "active",
            "default_source": "5565b4c5648a0df61455a689",
            "reference":"TestUniqueReference",
            "first_name": "TestFirstNameEdit",
            "last_name": "TestLastNameEdit",
            "email": "[email protected]",
            "__v": 2,
            "payment_sources": [
                {
                    "updated_at": "2015-05-27T13:26:22.403Z",
                    "address_line1": "Ttests1",
                    "address_line2": "Ttest2",
                    "address_city": "Testcity2",
                    "address_state": "Teststate2",
                    "address_country": "AU",
                    "address_postcode": "2234",
                    "gateway_id": "55534a8ba28d339a100e741c",
                    "account_number": "456778",
                    "account_bsb": "123",
                    "account_name": "User name edited",
                    "ref_token": "746767",
                    "status": "active",
                    "created_at": "2015-05-27T12:12:53.523Z",
                    "_id": "5565b4c5648a0df61455a689",
                    "type": "bsb"
                }
            ],
            "statistics": {
                "total_collected_amount": 0,
                "successful_transactions": 0
            }
        }
    }
}
"Example of response using credit card details"

{
    "status": 200,
    "error": null,
    "resource": {
        "type": "customer",
        "data": {
            "_id": "5565b4c5648a0df61455a688",
            "created_at": "2015-05-27T12:12:53.525Z",
            "updated_at": "2015-05-27T13:26:22.401Z",
            "status": "active",
            "default_source": "5565b4c5648a0df61455a689",
            "reference":"TestUniqueReference",
            "first_name": "TestFirstNameEdit",
            "last_name": "TestLastNameEdit",
            "email": "[email protected]",
            "__v": 2,
            "payment_sources": [
                {
                    "updated_at": "2015-05-27T13:26:22.403Z",
                    "address_line1": "Ttests1",
                    "address_line2": "Ttest2",
                    "address_city": "Testcity2",
                    "address_state": "Teststate2",
                    "address_country": "AU",
                    "address_postcode": "2234",
                    "gateway_id": "55534a8ba28d339a100e741c",
                    "card_name": "Test User2",
                    "expire_month": 5,
                    "expire_year": 2017,
                    "card_number_last4": "8769",
                    "card_scheme": "visa",
                    "ref_token": "746767",
                    "status": "active",
                    "created_at": "2015-05-27T12:12:53.523Z",
                    "_id": "5565b4c5648a0df61455a689",
                    "type": "card"
                }
            ],
            "statistics": {
                "total_collected_amount": 0,
                "successful_transactions": 0
            }
        }
    }
}

POST /v1/customers/{_id}

You can use this API to update customer information (eg email address) or add more payment sources to a customer.

Similar to creating or adding a customer or creating a charge, you can add a payment source using:

Field Name Description Details
token One-time token with all payment source information, required only for updating customer with one-time token Object, required if adding payment source using token
reference Customer unique reference String, optional
first_name Customer first name String, optional
last_name Customer last name String, optional
email Customer email String, optional
default_source Default Payments Source ID. If changing payment customer information, new payment source becomes default. To change default payment source, please set this value to existing payments source String, optional
payment_source Object with payment information Object, required
address_city Customer Address, City String, required
account_name Customer account name. Parameter required when using Direct Debit only String, required for bsb or bank account only
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String, required for bsb only
account_number Number of Customer account. Parameter required when using Direct Debit only String, required bank account and bsb only
account_routing Number of Customer account. BSB/Routing/SWIFT/IBAN Number. String, required bank account onlyuired
account_holder_type Account type (‘personal’ or ‘business’) String, required bank account only
account_bank_name Name of account bank String, required bank account only
card_name Cardholder name (as on card) String, required card only
card_number Card number Integer, required card only
expire_month Card expiration month mm format Integer, required card only
expire_year Card expiration year yyyy format Integer, required card only
card_ccv Card CCV number Integer, required card only
gateway_id Gateway ID. For adding new payment source by transferring token from another gateway, add the new gateway ID you want the token to be attributed to here String, required
vault_token Payment vault token id of existing payment source String, required for adding payment source by conversion from another gateway
address_line1 Customer Address, line 1 String, optional
address_line2 Customer Address, line 2 String, optional
address_postcode Customer Address, Postcade Integer, optional
address_state Customer Address, State String, optional
address_country Customer Address, Country Code String, optional
type Type of payment. Use ‘bsb’ to post with bsb account and ‘card’ for payments with credit cards. Use ‘bank_account’ for using bank account credentials. Parameter required when using Direct Debit String, optional

When adding a new payment source by converting a vault token from another gateway: You will see a new payment source added and the “default_source” field for the customer changed to the new payment source

Archive customer

curl -X "DELETE https://api-sandbox.paydock.com/v1/customers/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/customers/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$customerSvc = new Customers();
$res = $customerSvc$svc->archive("585ba514e45b75bc368087a8")
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "_id": "585ba514e45b75bc368087a8",
      "created_at": "2016-12-22T10:04:06.418Z",
      "updated_at": "2016-12-22T10:42:20.199Z",
      "status": "active",
      "default_source": "585ba516e45b75bc368087a9",
      "first_name": "Oleg",
      "last_name": "cCdekrigin",
      "email": "[email protected]",
      "phone": "+123451678910",
      "__v": 0,
      "payment_sources": [
        {
          "updated_at": "2016-12-22T10:42:20.198Z",
          "vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
          "address_line1": "Testline1",
          "address_line2": "Testline2",
          "address_city": "Testcity",
          "address_state": "Teststate",
          "address_country": "AU",
          "address_postcode": "3000",
          "gateway_id": "5853e89c2bd79538605a3fb6",
          "card_name": "Test User",
          "expire_month": 10,
          "expire_year": 2020,
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "ref_token": "70b234c5-3af7-41b5-9992-96a014eab056",
          "status": "active",
          "created_at": "2016-12-22T10:04:06.370Z",
          "_id": "585ba516e45b75bc368087a9",
          "type": "card"
        }
      ],
      "statistics": {
        "currency": {
          "AUD": {
            "count": 2,
            "total_amount": 27
          }
        },
        "total_collected_amount": 27,
        "successful_transactions": 2
      },
      "_service": {
        "default_gateway_id": "5853e89c2bd79538605a3fb6"
      }
    }
  }
}

DELETE /v1/customers/{_id}

Customer with specified id will be archived. You can retrieve archived customers using Get customer list with parameters

Field Name Description Details
_id Customer unique id String, required

Subscriptions

Add Subscription

curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"},\"customer\":\{\"first_name\": \"Test_first_name\",\"last_name": "Test_last_name\",\"email": "[email protected]\",\"reference": "CustomReference\",\"payment_source\": {\"address_line1\": \"Testline1\",\"address_line2\": \"Testline2\",\"address_city\": \"Testcity\",\"address_state\": \"Teststate\",\"address_country\": \"AU\",\"address_postcode\": \"1234\",\"gateway_id\": \"55925037556cc23c1ed3773e\",\"card_name\":\"Test User\",\"card_number\":\"4200000000000000\",\"expire_month\":\"01\",\"expire_year\":\"17\",\"card_ccv\":\"123\"}}}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/subscriptions',
    body: {
          "amount": "10.00",
          "currency": "AUD",
          "reference": "Custom user reference",
          "description": "Custom user description",
          "customer": {
              "first_name": "Test_first_name",
              "last_name": "Test_last_name",
              "email": "[email protected]",
              "reference": "CustomReference",
              "payment_source": {
                  "address_line1": "Testline1",
                  "address_line2": "Testline2",
                  "address_city": "Testcity",
                  "address_state": "Teststate",
                  "address_country": "AU",
                  "address_postcode": "1234",
                  "gateway_id": "55925037556cc23c1ed3773e",
                  "card_name": "Test User",
                  "card_number": "4200000000000000",
                  "expire_month": "01",
                  "expire_year": "17",
                  "card_ccv": "123"
              }
          },
          "schedule": {
            "frequency": "1",
            "interval": "day",
            "start_date": "2015-07-20",
            "end_date": "2016-07-25T07:35:11Z"
          }
    },
    method: 'POST',
    headers: {
        'content-type': 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Add with credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
    ->withCreditCard(self::creditGateway, "4111111111111111", "2020", "10", "Test Name", "123")
    ->withSchedule("month", 1)
    ->call();
?>
"Example of response (201)"
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "__v": 0,
            "created_at": "2015-07-24T11:27:44.504Z",
            "updated_at": "2015-07-24T11:27:44.504Z",
            "amount": 10,
            "description": "Custom user description",
            "reference": "Custom user reference",
            "status": "active",
            "_id": "55b2213073065f9423a45d78",
            "archived": false,
            "_service": {
                "customer_default_gateway_id": "55925037556cc23c1ed3773e",
                "tags": "test_first_name test_last_name [email protected]"
            },
            "customer": {
                "customer_id": "55b2212f73065f9423a45d76",
                "first_name": "Test_first_name",
                "last_name": "Test_last_name",
                "email": "[email protected]",
                "reference": "CustomReference"
            },
            "statistics": {
                "total_collected_amount": 0,
                "successful_transactions": 0
            },
            "schedule": {
                "interval": "day",
                "start_date": "2015-07-24T11:27:43.743Z",
                "end_date": "2016-07-25T00:00:00.000Z",
                "next_assessment": "2015-07-24T11:27:43.743Z",
                "first_assessment": "2015-07-24T11:27:43.743Z",
                "status": "inprogress",
                "locked": false,
                "completed_count": 0,
                "retry_count": 0,
                "frequency": 1
            },
            "currency": "AUD"
        }
    }
}

POST /v1/subscriptions

Subscriptions are recurring billing events. These can be set up to take scheduled payments from a customer without having to re-enter the billing details.

In order to charge for a recurring subscription, it can be added with:

Subscriptions can run on different intervals (ie daily, weekly, monthly etc) and frequencies (ie ‘every X days’). You can also control the start date for a subscription.

Subscriptions can also be configured to end after:

If a subscription is created without a customer ID, a new customer will be created and the customer ID will be returned in the response.

There are a number of different statuses for a subscription:

Field Name Description Details
amount Amount of payment Float, required
currency Currency code, AUD by default String, optional
customer_id ID of PayDock customer Object, required adding subscription with customer id
token One-time token with all payment source information String, required adding subscription using one time token
reference Manually defined reference for payments in payment systems String, optional
description Manually defined description for payments in payment systems String, optional
customer Object with customers information Object, required using customer information
first_name Customer first name String, optional
last_name Customer last name String, optional
email Customer email String, optional
phone Customer phone in E.164 international notation (Example: +12345678901) String, optional
reference Manually defined reference for customer in payment systems String, optional
payment_source Object with payment information Object, required, if no customer provided
gateway_id Gateway ID String, required if no customer provided
type Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use 'bank_account’ for using direct debit payments. 'bsb’ can also be used for direct debit payment. String, optional
account_name Customer account name. Parameter required when using Direct Debit only String, required for bsb
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String, required for bsb
account_number Number of Customer account. Parameter required when using Direct Debit only String, required for bsb and bank account
account_routing Number of Customer account. BSB/Routing/SWIFT/IBAN Number. String, required for bank account
account_holder_type Account type ('personal’ or ‘business’) String, required for bank account
account_bank_name Name of account bank String, required for bank account
card_name Card holder name String, optional
card_number Card number Integer, required for card
expire_month Card expiration month mm format String, required for card
expire_year Card expiration year yyyy format String, required for card
card_ccv Card CCV number Integer, optional
address_line1 Customer Address, line 1 String, optional
address_line2 Customer Address, line 2 String, optional
address_city Customer Address, City String, optional
address_state Customer Address, State String, optional
address_country Customer Address, Country Code String, optional
address_postcode Customer Address, Postcode Integer, optional
schedule Object with subscription schedule information Object, required
interval Assessment interval one-off, week, month, year, day String, required
frequency Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) Integer, required
start_date Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) Date, optional
end_date End date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) Date, optional
end_amount_after Total amount of all successful transactions (equals or exceeds) Float, optional
end_amount_before Total amount of all successful transactions (not to exceed) Float, optional
end_amount_total Total amount to be paid with subscription (equals). NOTE: If last payment of subscription schedule will be less then $ 1.00, some gateways may respond with error and subscription status will become ‘failed’. Float, optional
end_transactions Total count of all successful transactions Integer, optional
meta Optional object for stripe connect Object, optional
stripe_direct_account_id ID of an existing, connected stripe account. Use to create Stripe connect Direct Charges String, optional
stripe_application_fee A fee in cents that will be applied to the charge and transferred to the application owner’s Stripe account String, optional
stripe_destination_account_id ID of an existing, connected stripe account. Use to create Stripe connect Destination Charges String, optional
stripe_destination_amount The amount to transfer to the destination account without creating an Application Fee String, optional

See also Required fields by Gateway

Add subscription using Customer ID

curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"customer_id\":\"b76c51ed9c004997903d54842826269a\"}"
"add with customer id"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
    ->withCustomerId("b76c51ed9c004997903d54842826269a")
    ->withSchedule("month", 1)
    ->call();
?>
"Example of adding subscription using customer id"

var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/subscriptions',
    body: {
        "amount":"10.00",
        "currency":"AUD",
        "reference": "Custom user reference",
        "description": "Custom user description",
        "customer_id":"b76c51ed9c004997903d54842826269a",
        "schedule": {
            "frequency":1,
            "interval":"day",
            "start_date":"2016-11-05",
            "end_date":"2018-07-24T11:51:30.211Z"
        }
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Example of response (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "subscription",
    "data": {
      "__v": 0,
      "created_at": "2016-11-07T15:34:44.837Z",
      "updated_at": "2016-11-07T15:34:44.837Z",
      "amount": 10,
      "description": "Custom user description",
      "reference": "Custom user reference",
      "payment_source_id": "58209cc5c2ee2574399de888",
      "status": "active",
      "_id": "58209f14c2ee2574399de88c",
      "archived": false,
      "_service": {
        "customer_default_gateway_id": "581c753a8f51564723663fe7",
        "tags": "test_first_name test_last_name [email protected]"
      },
      "customer": {
        "customer_id": "58209cc3c2ee2574399de887",
        "first_name": "Test_first_name",
        "last_name": "Test_last_name",
        "email": "[email protected]",
        "reference": "CustomReferenceOfCustomer"
      },
      "statistics": {
        "total_collected_amount": 0,
        "successful_transactions": 0
      },
      "schedule": {
        "interval": "day",
        "start_date": "2016-11-07T15:34:44.827Z",
        "end_date": "2017-07-25T00:00:00.000Z",
        "next_assessment": "2016-11-07T15:34:44.827Z",
        "next_assessment_planned": "2016-11-07T15:34:44.827Z",
        "first_assessment": "2016-11-07T15:34:44.827Z",
        "status": "inprogress",
        "locked": false,
        "completed_count": 0,
        "retry_count": 0,
        "frequency": 1
      },
      "currency": "AUD"
    }
  }
}

Charges can be added to a company only if there is a Billing Plan assigned to it. Customers can add a subscription through using the Customer ID.

Add subscription with one-time token

curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
      -H "x-user-secret-key: x-user-secret-key" \
      -H "Content-Type: application/json" \
      -d "{\"schedule\": \ {\"frequency\":\1\,\"interval\":\"month\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"amount\":\"10.00\", \"currency\":\"AUD\", \"reference\":\"Custom subscription reference\", \"description\":\"Custom subscription description\", \"token\":\"b76c51ed-9c00-4997-903d-54842826269a\"}\"
"add with token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
    ->withToken("b76c51ed-9c00-4997-903d-54842826269a")
    ->withSchedule("month", 1)
    ->call();
?>
"Example of adding subscription using one time token"

var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/subscriptions',
    body: {
        "amount":"10.00",
        "currency":"AUD",
        "reference": "Custom subscription reference",
        "description": "Custom subscription description",
        "token":"b76c51ed-9c00-4997-903d-54842826269a",
        "schedule":{
            "interval":"month",
            "frequency":"1",
            "start_date":"2015-11-10",
            "end_date":"2016-01-10"
        }
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Example of response (201)"
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "__v": 0,
            "created_at": "2015-11-10T11:27:44.504Z",
            "updated_at": "2015-11-10T11:27:44.504Z",
            "amount": 10,
            "description": "Custom subscription description",
            "reference": "Custom subscription reference",
            "status": "active",
            "_id": "55b2213073065f9423a45d78",
            "archived": false,
            "_service": {
                "customer_default_gateway_id": "551bb4af43daf16f355ab259",
                "tags": "test_first_name test_last_name [email protected]"
            },
            "customer": {
                "customer_id": "55b2212f73065f9423a45d76",
                "first_name": "Test_first_name",
                "last_name": "Test_last_name",
                "email": "[email protected]"
            },
            "statistics": {
                "total_collected_amount": 0,
                "successful_transactions": 0
            },
            "schedule": {
                "interval": "month",
                "start_date": "2015-11-10T11:27:43.743Z",
                "end_date": "2016-01-10T00:00:00.000Z",
                "next_assessment": "2015-12-10T11:27:43.743Z",
                "first_assessment": "2015-11-10T11:27:43.743Z",
                "status": "inprogress",
                "locked": false,
                "completed_count": 0,
                "retry_count": 0,
                "frequency": 1
            },
            "currency": "AUD"
        }
    }
}

Subscriptions can be added to a company only if there is a Billing Plan assigned to it. Customers can use a Credit Card or Direct Debit information directly, or by creating a one-time token. One-time tokens are created on the customer side, using PayDock.js or by creating a token on the API side. Also, one-time tokens can created using iFrame. A result of the iFrame process is that the Customer will get a webhook with the “payment_source” value. Parameter “payment_source” is used as a “token” in future examples.

Update subscription details

curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"interval\":\"year\",\"start_date\":\"2015-07-20\"}"
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/subscriptions/{_id}',
    body: {
      "amount": "17",
      "currency": "AUD",
      "reference":"Custom reference",
      "description":"Custom description"
      "schedule":{
           "interval":"year",
           "start_date":"2015-08-01"
      }
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->update(200)
    ->withSchedule("month", 2)
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "_id": "55b2213073065f9423a45d78",
            "amount": 167,
            "company_id": "559241db556cc23c1ed3770b",
            "created_at": "2015-07-24T11:27:44.504Z",
            "description": "Custom description",
            "reference": "Custom reference",
            "status": "active",
            "updated_at": "2015-07-24T11:31:34.697Z",
            "user_id": "559241db556cc23c1ed3770a",
            "archived": false,
            "customer": {
                "customer_id": "55b2212f73065f9423a45d76",
                "first_name": "Test_first_name",
                "last_name": "Test_last_name",
                "email": "[email protected]"
            },
            "statistics": {
                "total_collected_amount": 10,
                "successful_transactions": 1
            },
            "schedule": {
                "end_date": "2016-07-25T00:00:00.000Z",
                "first_assessment": "2015-08-01T00:00:00.000Z",
                "interval": "year",
                "last_assessment": "2015-07-24T11:28:02.480Z",
                "next_assessment": "2015-08-01T00:00:00.000Z",
                "start_date": "2015-08-01T00:00:00.000Z",
                "status": "complete",
                "locked": false,
                "completed_count": 1,
                "retry_count": 0,
                "frequency": 1
            },
            "currency": "AUD",
            "gateway_type": "Pin",
            "gateway_name": "Pin label",
            "gateway_mode": "test"
        }
    }
}

POST /v1/subscriptions/{_id}

Updates an existing subscription to adjust payment schedule or end conditions.

Field Name Description Details
_id Payment Identifier String, required
amount Amount of payment Float, required
currency Currency code, AUD by default String, optional
description Manually defined description for payments in payment systems String, optional
reference Manually defined reference for payments in payment systems String, optional
payment_source_id The payment source to be used to pay for the subscription, generally use a payment source retrieved from a customer String, optional
schedule Object with subscription schedule information Object, required
interval Assessment interval week, month, year, day String, required
frequency Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) Integer, required
start_date Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) Date, required
end_date End date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) Date, required
end_amount_after Total amount of all successful transactions (equals or exceeds) Float, optional
end_amount_before Total amount of all successful transactions (not to exceed) Float, optional
end_amount_total Total amount to be paid with subscription (equals) Float, optional
end_transactions Total count of all successful transactions Integer, optional

Get subscription list

curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/subscriptions',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->get()
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "subscriptions",
        "data": [{
                "_id": "56d84e98815b245d242b4996",
                "amount": 10.70,
                "company_id": "56a5e4e6489dc5402557d9b7",
                "created_at": "2016-03-03T14:47:52.834Z",
                "status": "expired",
                "updated_at": "2016-03-03T14:48:00.579Z",
                "user_id": "56a5e4e6489dc5402557d9b6",
                "archived": false,
                "customer": {
                    "customer_id": "56d84e97815b245d242b4991",
                    "first_name": "TEST_NEW_SUB55",
                    "last_name": "Number",
                    "email": "[email protected]",
                    "reference": "CustomReference"
                },
                "statistics": {
                    "total_collected_amount": 10.59,
                    "successful_transactions": 1
                },
                "schedule": {
                    "end_amount_total": 10.70,
                    "first_assessment": "2016-03-03T14:47:51.739Z",
                    "interval": "day",
                    "last_assessment": "2016-03-03T14:48:00.576Z",
                    "next_assessment": "2016-03-03T14:47:51.739Z",
                    "start_date": "2016-03-03T14:47:51.739Z",
                    "status": "complete",
                    "locked": false,
                    "completed_count": 1,
                    "retry_count": 0,
                    "frequency": 1
                },
                "currency": "AUD",
                "gateway_type": "Stripe",
                "gateway_name": "strp",
                "gateway_mode": "test"
            }, {
                "_id": "56d84e7b815b245d242b494b",
                "amount": 12.00,
                "company_id": "56a5e4e6489dc5402557d9b7",
                "created_at": "2016-03-03T14:47:23.051Z",
                "status": "expired",
                "updated_at": "2016-03-03T14:47:30.590Z",
                "user_id": "56a5e4e6489dc5402557d9b6",
                "archived": false,
                "customer": {
                    "customer_id": "56d84e79815b245d242b4949",
                    "first_name": "TEST_NEW_SUB55",
                    "last_name": "Number",
                    "email": "[email protected]"
                },
                "statistics": {
                    "total_collected_amount": 10.59,
                    "successful_transactions": 1
                },
                "schedule": {
                    "end_amount_total": 12.00,
                    "first_assessment": "2016-03-03T14:47:21.805Z",
                    "interval": "day",
                    "last_assessment": "2016-03-03T14:47:30.588Z",
                    "next_assessment": "2016-03-03T14:47:21.805Z",
                    "start_date": "2016-03-03T14:47:21.805Z",
                    "status": "complete",
                    "locked": false,
                    "completed_count": 1,
                    "retry_count": 0,
                    "frequency": 1
                },
                "currency": "AUD",
                "gateway_type": "Stripe",
                "gateway_name": "strp",
                "gateway_mode": "test"
            }],
        "count": 2,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/subscriptions

Returns all subscriptions for the account, limited to 100 records.

Get subscription list with parameters

curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}',
    body: {
          "amount": "17",
          "currency": "AUD",
          "reference":"Custom reference",
          "description":"Custom description"
          "schedule":{
            "interval":"year",
            "start_date":"2015-08-01"
          }
        }
    },
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->get()
    ->withParameters(["search" => "test", "sortkey" => "firstname"])
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "subscriptions",
        "data": [
            {
                "_id": "55a62eb88d7127722432c69d",
                "amount": 10,
                "company_id": "559241db556cc23c1ed3770b",
                "created_at": "2015-07-15T09:58:16.269Z",
                "status": "active",
                "updated_at": "2015-07-15T10:01:30.978Z",
                "user_id": "559241db556cc23c1ed3770a",
                "archived": false,
                "customer": {
                    "customer_id": "55a62eb48d7127722432c69b",
                    "first_name": "Test",
                    "last_name": "Test",
                    "email": "[email protected]",
                    "reference": "CustomReference"
                },
                "statistics": {
                    "total_collected_amount": 10,
                    "successful_transactions": 1
                },
                "schedule": {
                    "first_assessment": "2015-07-15T09:58:12.441Z",
                    "interval": "day",
                    "last_assessment": "2015-07-15T09:58:19.120Z",
                    "next_assessment": "2015-07-16T09:58:12.441Z",
                    "start_date": "2015-07-15T09:58:12.441Z",
                    "status": "complete",
                    "locked": false,
                    "completed_count": 1,
                    "retry_count": 0,
                    "frequency": 1
                },
                "currency": "AUD",
                "gateway_type": "Ezidebit",
                "gateway_name": "Ezidebit label",
                "gateway_mode": "test"
            }, {
                "_id": "55a51a57ec20ac8423273da3",
                "amount": 90,
                "company_id": "559241db556cc23c1ed3770b",
                "created_at": "2015-07-14T14:19:03.378Z",
                "status": "active",
                "updated_at": "2015-07-14T14:19:11.368Z",
                "user_id": "559241db556cc23c1ed3770a",
                "archived": false,
                "customer": {
                    "customer_id": "55a51a24ec20ac8423273d9e",
                    "first_name": "test",
                    "last_name": "test",
                    "email": "[email protected]"
                },
                "statistics": {
                    "total_collected_amount": 90,
                    "successful_transactions": 1
                },
                "schedule": {
                    "end_date": "2015-08-20T00:00:00.000Z",
                    "first_assessment": "2015-07-14T14:19:03.370Z",
                    "interval": "day",
                    "last_assessment": "2015-07-14T14:19:11.365Z",
                    "next_assessment": "2015-07-15T14:19:03.370Z",
                    "start_date": "2015-07-14T14:19:03.370Z",
                    "status": "complete",
                    "locked": false,
                    "completed_count": 1,
                    "retry_count": 0,
                    "frequency": 1
                },
                "currency": "AUD",
                "gateway_type": "Authorize",
                "gateway_name": "Authorize label",
                "gateway_mode": "test"
            }, {
                "_id": "55a02ca8e0ssddf02395cf41",
                "amount": 55,
                "company_id": "559241db55ssc23c1ed3770b",
                "created_at": "2015-07-10T20:35:52.593Z",
                "status": "active",
                "updated_at": "2015-07-10T20:36:14.386Z",
                "user_id": "559241db556cc23c1ed3770a",
                "archived": false,
                "customer": {
                    "customer_id": "55a02c86e05cddf02395cf3c",
                    "first_name": "test",
                    "last_name": "test",
                    "email": "[email protected]",
                    "reference": "CustomReference"
                },
                "statistics": {
                    "total_collected_amount": 55,
                    "successful_transactions": 1
                },
                "schedule": {
                    "first_assessment": "2015-07-10T20:35:52.585Z",
                    "interval": "day",
                    "last_assessment": "2015-07-10T20:36:14.384Z",
                    "next_assessment": "2015-07-15T20:35:52.585Z",
                    "start_date": "2015-07-10T20:35:52.585Z",
                    "status": "complete",
                    "locked": false,
                    "completed_count": 1,
                    "retry_count": 0,
                    "frequency": 5
                },
                "currency": "AUD",
                "gateway_type": "Securepay",
                "gateway_name": "Secur label",
                "gateway_mode": "test"
            }
        ],
        "count": 30,
        "limit": 3,
        "skip": 0
    }
}

GET /v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}

Retrieving data on existing subscriptions can be driven by number of action parameters set in URI path.

Field Name Description Details
skip Pagination parameter to skip first n payments from list, default = 0 Number, optional
limit Pagination parameter to limit output to n , default = 100 , maximum value = 1000 Number, optional
search Text search parameter (search in fields firstname, lastname, email) String, optional
sortkey Sorting key parameter i.e. firstname, lastname, email, startdate, ASC direction by default String, optional
sortdirection Sorting order direction parameter (ASC by default, only value that affects is DESC) String, optional
customer_id PayDock Customer’s ID String, optional
gateway_id ID of a gateway with which subscriptions were created String, optional
status Status could be: active, expired, failed, deleted String, optional

Get subscription item details

Retrieves data on subscription with specified ID.

GET /v1/subscriptions/{_id}

curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
    var request = require('request');

    request({
        url: 'https://api-sandbox.paydock.com/v1/subscriptions/{_id}',
        method: 'GET',
        headers: {
            'content-type' : 'application/json',
            'x-user-secret-key': 'user_secret_key'
        }
    }, function(error, response, body){
        if(error) {
            console.log(error);
        } else {
            console.log(response.statusCode, body);
        }
    });
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->get()
    ->withSubscriptionId("55b226c273065f9423a45d8d")
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "subscription",
        "data": {
            "created_at": "2015-07-24T11:51:30.211Z",
            "updated_at": "2015-07-24T11:51:30.211Z",
            "user_id": "559241db556cc23c1ed3770a",
            "company_id": "559241db556cc23c1ed3770b",
            "amount": 10,
            "description": "Custom description",
            "reference": "Custom reference",
            "status": "active",
            "_id": "55b226c273065f9423a45d8d",
            "archived": false,
            "customer": {
                "customer_id": "55b226c173065f9423a45d8b",
                "first_name": "Test_first_name",
                "last_name": "Test_last_name",
                "email": "[email protected]",
                "reference": "CustomReference",
                "payment_source": {
                    "gateway_name": "Ezidebit label",
                    "gateway_type": "Ezidebit",
                    "gateway_mode": "test",
                    "updated_at": "2015-07-24T11:51:30.207Z",
                    "address_line1": "Testline1",
                    "address_line2": "Testline2",
                    "address_city": "Testcity",
                    "address_state": "Teststate",
                    "address_country": "AU",
                    "address_postcode": "1234",
                    "gateway_id": "5592499f556cc23c1ed37710",
                    "account_name": "Test",
                    "account_bsb": 32000,
                    "account_number": "XXXX00",
                    "ref_token": "762958",
                    "status": "active",
                    "created_at": "2015-07-24T11:51:30.205Z",
                    "_id": "55b226c273065f9423a45d8c",
                    "type": "bsb"
                }
            },
            "statistics": {
                "total_collected_amount": 0,
                "successful_transactions": 0
            },
            "schedule": {
                "interval": "day",
                "start_date": "2015-07-25T00:00:00.000Z",
                "end_date": "2016-08-25T00:00:00.000Z",
                "next_assessment": "2015-07-25T00:00:00.000Z",
                "first_assessment": "2015-07-25T00:00:00.000Z",
                "status": "inprogress",
                "locked": false,
                "completed_count": 0,
                "retry_count": 0,
                "frequency": 1
            },
            "currency": "AUD"
        }
    }
}
Field Name Description Details
_id Identifier of particular subscription String, required

Delete subscription

curl -X "DELETE" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/subscriptions/{_id}',
    method: "DELETE",
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Subscriptions();
$res = $svc->delete("55b226c273065f9423a45d8d")
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "subscription",
    "data": {
      "_id": "585ba520e45b75bc368087ab",
      "created_at": "2016-12-22T10:04:16.139Z",
      "updated_at": "2016-12-22T10:18:57.948Z",
      "amount": 17,
      "description": "Custom description",
      "reference": "Custom reference",
      "payment_source_id": "585ba516e45b75bc368087a9",
      "status": "deleted",
      "archived": false,
      "customer": {
        "customer_id": "585ba514e45b75bc368087a8",
        "first_name": "Oleg",
        "last_name": "cCdekrigin",
        "email": "[email protected]",
        "phone": "+123451678910"
      },
      "statistics": {
        "total_collected_amount": 27,
        "successful_transactions": 2
      },
      "schedule": {
        "interval": "year",
        "start_date": "2016-12-22T10:16:55.697Z",
        "end_date": null,
        "next_assessment": "2017-12-22T10:16:55.697Z",
        "next_assessment_planned": "2017-12-22T10:16:55.697Z",
        "first_assessment": "2016-12-22T10:16:55.697Z",
        "status": "complete",
        "last_assessment": "2016-12-22T10:17:41.088Z",
        "end_amount_after": null,
        "end_amount_before": null,
        "end_amount_total": null,
        "end_transactions": null,
        "locked": false,
        "completed_count": 2,
        "retry_count": 0,
        "frequency": 1
      },
      "currency": "AUD"
    }
  }
}

DELETE /v1/subscriptions/{_id}

Removes a subscription with specified ID.

Field Name Description Details
_id Payment identifier String, required

Notifications

Notifications are automated messages that are triggered in response to events within the system.

Within PayDock, notification triggers are set up to fire on different events. Notification triggers can have have different types (i.e. Webhook, Email, Sms) and events (i.e. Transaction Success).

Notifications for email and SMS require templates for the notification.

See also Examples of webhook payloads

Notification Templates also provide swap values (eg {{PHONE}} or {{EMAIL}}) that will be populated from the customer, charge or subscription that triggered the notification (See Swap Values for templates for the full list).

Add new notification template

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/templates',
    body: {
        "label":"Sms first template",
        "notification_event":"transaction_success",
        "body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
        "destination":"{{{PHONE}}}",
        "type":"sms"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc->createTemplate("Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.", "label", "refund_failure")
    ->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
"Example of response (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "template",
    "data": {
      "__v": 0,
      "created_at": "2016-12-21T09:07:56.100Z",
      "updated_at": "2016-12-21T09:07:56.100Z",
      "label": "Sms first template",
      "notification_event": "transaction_success",
      "body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
      "_id": "585a466c9af8e1811517afc3"
    }
  }
}

POST /v1/notifications/templates

Create a notification template (available only in email and SMS type of notifications).

Name Description Details
body Use custom text or/and predefined variables, in which PayDock automatically pulls values from customer, charge or subscription data objects. String, required
label Name of current template to identify it further String, required
notification_event Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ String, required
html Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is false Boolean, optional

Edit notification template

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
    body: {
            "label":"Sms first template",
            "notification_event":"transaction_success",
            "body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
            "destination":"{{{PHONE}}}",
            "type":"sms"
         },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc->updateTemplate("585b9aa7bce8378c54a8a61e", "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.", "label", "refund_failure")
    ->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "template",
    "data": {
      "created_at": "2016-12-22T09:19:35.577Z",
      "updated_at": "2016-12-22T09:19:44.221Z",
      "label": "Sms first template",
      "notification_event": "transaction_success",
      "body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
      "_id": "585b9aa7bce8378c54a8a61e"
    }
  }
}

POST /v1/notifications/templates/{_id}

Update a notification template (available only in email and SMS type of notifications).

Name Description Details
_id ID of notification template String, required
body Use custom text or/and predefined variables, in which PayDock automatically pull values from customer, charge or subscription data objects. String, required
label Name of current template to identify it further String, required
notification_event Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ String, required
html Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is ‘false’ Boolean, optional

Get notification template

curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/templates" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
    var request = require('request');

    request({
        url: 'https://api.paydock.com/v1/notifications/templates',
        method: 'GET',
        headers: {
            'content-type' : 'application/json',
            'x-user-secret-key': 'user_secret_key'
        }
    }, function(error, response, body){
        if(error) {
            console.log(error);
        } else {
            console.log(response.statusCode, body);
        }
    });
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc->getTemplates()
    ->call();
?>
"Example of response"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "templates",
        "data": [
            {
                "_id": "59cc90516021e26d049037aa",
                "created_at": "2017-09-28T06:01:53.483Z",
                "updated_at": "2017-09-28T06:01:53.483Z",
                "body": "Your subscription transaction has failed - email [email protected] now!",
                "label": "Subscription Transaction Failed Template",
                "notification_event": "subscription_transaction_failure",
                "html": false
            },
            {
                "_id": "59c4ade26021e26d048fb090",
                "created_at": "2017-09-22T06:29:54.343Z",
                "updated_at": "2017-09-22T06:29:54.343Z",
                "body": "Transaction success!",
                "label": "Transaction success template",
                "notification_event": "transaction_success",
                "html": true
            }
        ],
        "count": 2,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/notifications/templates/

Returns notification templates limited to 100.

Get notification template by id

curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/templates/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc->getTemplates()
    ->withTemplateId("56a0b80e489dc5402557d5e3")
    ->call();
?>
"Example of response (200)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "template",
        "data": {
            "_id": "59deb0f243852f0fa39e73cd",
            "created_at": "2017-10-12T00:01:54.996Z",
            "updated_at": "2017-10-12T00:01:54.996Z",
            "body": "This is an example Transaction Success Notification Template",
            "label": "Transaction Success Notification Template",
            "notification_event": "transaction_success",
            "html": true
        }
    }
}

GET /v1/notifications/templates/{id}

Get specific notification template by template id.

Delete notification template

curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/templates/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc->deleteTemplate("56a0b80e489dc5402557d5e3")
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "template",
        "data": {
            "created_at": "2016-01-21T10:50:54.403Z",
            "updated_at": "2016-01-21T10:52:32.665Z",
            "label": "Sms first template",
            "notification_event": "transaction_success",
            "body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created. ",
            "_id": "56a0b80e489dc5402557d5e3"
        }
    }
}

DELETE /v1/notifications/templates/{_id}

Delete a notification template.

Name Description Details
_id Template ID String, required

Add notification trigger

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications',
    body: {
            "event":"transaction_success",
            "destination":"http://webhooks.com/",
            "type":"webhook"
         },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-addTrigger("webhook", "https://www.paydock.com", "56a0b80e489dc5402557d5e3", "refund_failure")
    ->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"event\":\"transaction_success\",\"destination\":\"http://webhooks.com\,\"type\":\"webhook\"
"Example of response (201)"
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "notification",
        "data": {
            "event": "transaction_success",
            "destination": "http://webhooks.com/",
            "type": "webhook",
            "_id": "55a634a48d7127722432c6a6"
        }
    }
}

POST /v1/notifications

Created a trigger to send a notification to a customer or endpoint. To send an email or SMS to a customer, use swap values (eg {{PHONE}} or {{EMAIL}}) which are loaded from the customer (See Swap Values for templates for the full list).

Name Description Details
type type of notification: ‘webhook’, ‘email’, ‘sms’ String, required
destination Where to send notification (URL for webhook, email address for email ({{EMAIL}} for current customer), phone number in international E.164 format ({{PHONE}} for current customer)) String, required
template_id Custom template, which can be used with email or sms notifications. String, required for email or sms
event Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ String, required

Get notification trigger list

curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/notifications',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-getTriggers()
    ->call();
?>
"Examle of response (200)"
{
     "status": 200,
     "error": null,
     "resource": {
         "type": "notifications",
         "data": [
             {
                 "event": "transaction_failure",
                 "destination": "[email protected]",
                 "type": "email",
                 "_id": "55a00fe0aeb7e987239b47a9"
             },
             {
                 "event": "transaction_success",
                 "destination": "http://webhooks.com/",
                 "type": "webhook",
                 "_id": "55a634a48d7127722432c6a6"
             }
         ],
         "count": 2,
         "limit": 0,
         "skip": 0
     }
}

GET /v1/notifications

Returns all notification triggers for the account, limited to 100 records.

Get notification trigger

curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-getTriggers()
    ->withTriggerId("55a634a48d7127722432c6a6")
    ->call();
?>
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "notification",
    "data": {
      "event": "transaction_success",
      "destination": "http://webhooks.com/",
      "type": "webhook",
      "_id": "585ba240e45b75bc3680879e"
    }
  }
}

GET /v1/notifications/{_id}

Retrive details on a specific notification.

Name Description Details
_id Notification ID String, required

Delete notification trigger

curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/notifications/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-deleteTrigger("55a634a48d7127722432c6a6")
    ->call();
?>
"Example of response (201)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "notification",
    "data": {
      "event": "transaction_success",
      "destination": "http://webhooks.com/",
      "type": "webhook",
      "_id": "585ba240e45b75bc3680879e"
    }
  }
}

DELETE /v1/notifications/{_id}

Remove a notification.

Name Description Details
_id Notification ID String, required

Get user notification log

curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/logs?success=true&type=email&event=transaction_failure&created_at.from=2015-10-01&created_at.to=2016-11-09T10:17:39.016Z&parent_id=560e7abed81ed5da267cf3a6" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/logs?[params]',
    body: {
        "success": "boolean",
        "type": "String",
        "event": "String",
        "_id": "String",
        "parent_id": "String",
        "created_at.from": "String",
        "created_at.to": "String",
        "destination": "String"
     },
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-getLog(["created_at.from" => "2017-01-01", "created_at.to" => "2018-01-01"])
    ->call();
?>
"Example of response"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "notification_logs",
        "data": [
            {
                "created_at": "2015-10-02T13:53:35.114Z",
                "success": true,
                "type": "email",
                "destination": "[email protected]",
                "notification_id": "560e7abed81ed5da267cf3a6",
                "parent_id": "560e7abed81ed5da267cf3a6",
                "event": "transaction_failure",
                "response_status": "OK",
                "_id": "560e8c5fd81ed5da267cf3af",
                "archived": false
            },
            {
                "created_at": "2015-10-02T13:53:31.253Z",
                "success": true,
                "type": "email",
                "destination": "[email protected]",
                "notification_id": "560e7abed81ed5da267cf3a6",
                "parent_id": "560e7abed81ed5da267cf3a6",
                "event": "transaction_failure",
                "response_status": "OK",
                "_id": "560e8c5bd81ed5da267cf3ae",
                "archived": false
            },
            {
                "created_at": "2015-10-02T13:53:25.579Z",
                "success": true,
                "type": "email",
                "destination": "[email protected]",
                "notification_id": "560e7abed81ed5da267cf3a6",
                "parent_id": "560e7abed81ed5da267cf3a6",
                "event": "transaction_failure",
                "response_status": "OK",
                "_id": "560e8c55d81ed5da267cf3ad",
                "archived": false
            }
        ],
        "count": 3,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/notifications/logs?success=true&type=email&event=transaction_failure&created_at.from={yyyy-mm-dd}&created_at.to={yyyy-mm-dd}&parent_id={parent_id}

Retrieve list of all notifications, with parameter list

Name Description Details
_id Parameter to show specific notification details String, optional
success Parameter to filter success or failed notifications. Values: true/false String, optional
event Parameter to filter notification events. Values: transaction_success, transaction_failure, subscription_creation_succes , subscription_creation_failure, subscription_updated, refund_requested, refund_successful, refund_failure, card_expiration_warning String, optional
type Parameter to show notifications of specific type. Values: email, webhook String, optional
created_at.from Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) String, optional
created_at.to Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) String, optional
parent_id Used to search for notifications that have been resent, represents the id of the failed notification String, optional
destination Shows email address or webhook URL. String, optional

Archive notification log

curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/notifications/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Notifications();
$res = $svc-archiveLog("12342347567562")
    ->call();
?>
"Example of response (201)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "charge",
        "data": {
            "company_id": "5584018a27b2cf0b1e4f1a6c",
            "created_at": "2015-10-05T06:03:14.121Z",
            "success": true,
            "type": "email",
            "destination": "[email protected]",
            "notification_id": "560fcc0dd81ed5da267cf4f3",
            "parent_id": "560fcc0dd81ed5da267cf4f3",
            "event": "transaction_failure",
            "response_status": "OK",
            "_id": "561212a2d81ed5da267cf688",
            "__v": 0,
            "archived": true
        }
    }
}

DELETE /v1/notifications/logs/{_id}

Archive remove a notification log.

Name Description Details
_id Notification ID String, required

Tokens

POST /v1/payment_sources/tokens?public_key=[your_public_key]

One-time token represents payment source information including Credit Сards or Direct Debit account details. It is a disposable token for creating charges/subscriptions/customers or updating customers. One-time tokens expire after 3 hours.

Tokens can also be created using:

Here is an example of creating one-time token using direct API request:

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"phone\":\"+12345678910\",\"address_line1\":\"Testline1\",\"address_line2\":\"Testline2\",\"address_city\":\"Testcity\",\"address_state\":\"Teststate\",\"address_country\":\"AU\",\"address_postcode\":\"1324\",\"gateway_id\":\"551bb4af43daf16f355ab259\",\"card_name\":\"Test User\",\"card_number\":\"4200000000000000\",\"expire_month\":\"01\",\"expire_year\":\"17\",\"card_ccv\":\"123\"}"
"Credit Сards example"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]',
    method: 'POST',
    body: {
        "first_name": "Test_first_name",
        "last_name": "Test_last_name",
        "email": "[email protected]",
        "phone":"+12345678910",
        "address_line1": "Testline1",
        "address_line2": "Testline2",
        "address_city": "Testcity",
        "address_state": "Teststate",
        "address_country": "AU",
        "address_postcode": "1234",
        "gateway_id": "551bb4af43daf16f355ab259",
        "card_name":"Test User",
        "card_number":"4200000000000000",
        "expire_month":"01",
        "expire_year":"17",
        "card_ccv":"123"
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Direct Debit example"

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]',
    method: 'POST',
    body: {
        "first_name": "Test_first_name",
        "last_name": "Test_last_name",
        "email": "[email protected]",
        "phone":"+12345678910",
        "address_line1": "Testline1",
        "address_line2": "Testline2",
        "address_city": "Testcity",
        "address_state": "Teststate",
        "address_country": "AU",
        "address_postcode": "1234",
        "type":"bsb",
        "gateway_id": "584125e4990f62cf1457996a",
        "account_name":"Test User",
        "account_number":"064000",
        "account_bsb":"064000"
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
"Credit Сards example"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Tokens();
return $svc->create("John", "Smith")
    ->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Test Name", "123")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Direct Debit example"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Tokens();
return $svc->create("John", "Smith")
    ->withBankAccount("551bb4af43daf16f355ab259", "test", "012003", "456456")
    ->includeAddress("1 something st", "", "NSW", "Australia", "Sydney", "2000")
    ->call();
?>
"Example of response (201)"
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "token",
        "data": "b76c51ed-9c00-4997-903d-54842826269a"
    }
}
Field Name Description Detailsß
gateway_id Gateway ID String, required
type Type of payment. Use ‘bsb’ to post with bsb account and ‘card’ for payments with credit cards. Use ‘bank_account’ for using bank account credentials. Parameter required when using direct Debit String, required
card_name Cardholder name (as on card) String, required for card
card_number Card number Integer, required for card
expire_month Card expiration month mm format String, required for card
expire_year Card expiration year yyyy format String, required for card
card_ccv Card CCV number Integer, optional
account_name Customer account name. Parameter required when using Direct Debit only String, required for bsb
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String, required for bsb
account_number Number of Customer account. Parameter required when using Direct Debit only String, required for bsb and bank account
account_routing Number of Customer account. BSB/Routing/SWIFT/IBAN Number. String, required for bank account
account_holder_type Account type (‘personal’ or ‘business’) String, required for bank account
account_bank_name Name of account bank String, required for bank account
first_name Customer first name String, optional
last_name Customer last name String, optional
email Customer email String, optional
phone Customer phone in E.164 international notation (Example: +12345678901) String, optional
address_line1 Customer Address, line 1 String, optional
address_line2 Customer Address, line 2 String, optional
address_state Customer Address, State String, optional
address_country Customer Address, Country Code String, optional
address_city Customer Address, City String, optional
address_postcode Customer Address, Postcade Integer, optional

See also Required fields by Gateway

Gateways

PayDock enables multiple gateways to be connected to a single PayDock account, see our list of Supported Gateways

Gateways can be added through the API where the third-party gateway supports it or through the PayDock Admin Portal.

Before assigning a gateway to a company, there should be an account registered with required gateway in their system, where specific data can be found (gateway token, merchant ID, etc.).

Add new payment gateway

curl -X "POST" "https://api-sandbox.paydock.com/v1/gateways" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"type\":\"Gateway Type\",\"name\":\"Gateway Name\",\"username\":\"Gateway Username\",\"password\":\"Gateway Password\"}"
    var request = require('request');

    request({
        url: 'https://api-sandbox.paydock.com/v1/gateways',
        body: {
               "type": "PromisePay",
               "name": "Promise Pay",
               "username": "username",
               "password": "password",
               "mode": "test"
            },
        method: 'POST',
        headers: {
            'content-type' : 'application/json',
            'x-user-secret-key': 'user_secret_key'
        }
    }, function(error, response, body){
        if(error) {
            console.log(error);
        } else {
            console.log(response.statusCode, body);
        }
    });
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Gateways();
$res = $svc->create("Brain", "BraintreeTesting", "<merchantid>", "<username>", "<password>", "test")
    ->call();
?>
"Example Response (201)"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "gateway",
    "data": {
      "created_at": "2017-01-11T07:00:28.869Z",
      "updated_at": "2017-01-11T07:00:28.869Z",
      "type": "PromisePay",
      "name": "Promise Pay",
      "username": "username",
      "password": "user's password",
      "_id": "5875d80c85ad563f58a9eebc",
      "mode": "test"
    }
  }
}

POST /v1/gateways

You can add a gateway account more than once, by using a different name each time.

Each of the different gateways require a different set of parameters to add them, see the detailed list below.

eWay

Name Description Details
type value : ‘Eway’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Braintree

Name Description Details
type value : ‘Brain’ String, required
name Name which will be presented gateway String, required
merchant The merchant account ID String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Ezidebit

Name Description Details
type value : ‘Ezidebit’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Stripe

Name Description Details
type value : ‘Stripe’ String, required
name Name which will be presented gateway String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

PayPal

Name Description Details
type value : ‘Paypal’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Pin

Name Description Details
type value : ‘Pin’ String, required
name Name which will be presented gateway String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

PayWay

Name Description Details
type value : ‘PaywayRest’ String, required
name Name which will be presented gateway String, required
merchant Merchant Code String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

SecurePay

Name Description Details
type value : ‘Securepay’ String, required
name Name which will be presented gateway String, required
merchant Username of gateway side String, required
password Password for gateway String, required
mode defaults to test and in case for production mode is have to be live String, optional

Authorize.net

Name Description Details
type value : ‘Authorize’ String, required
name Name which will be presented gateway String, required
merchant Username of gateway side String, required
key Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Payment Express

Name Description Details
type value : ‘Paymentexpress’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

WorldPay

Name Details Description
type value : ‘Worldpay’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

NAB

Name Description Details
type value : ‘Nab’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Merchant Warrior

Name Description Details
type value : ‘Merchantwarrior’ String, required
name Name which will be presented gateway String, required
merchant Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

SQID

Name Description Details
type value : ‘Sqid’ String, required
name Name which will be presented gateway String, required
merchant Merchant Code String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

PromisePay

Name Description Details
type value : ‘PromisePay’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Forte

Name Description Details
type value : ‘Forte’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
merchant Merchant Id of gateway side String, required
signature Signature of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

IpPayments

Name Description Details
type value : ‘IpPayments’ String, required
name Name which will be presented gateway String, required
username Username of gateway side String, required
password Password for gateway String, required
mode Defaults to ‘test’, must be ‘live’ for production mode String, optional

Payeezy

Name Description Details
type value : ‘Payeezy’ String, required
name Name which will be presented gateway String, required
username Aapikey on gateway side String, required
password Token on gateway side String, required
signature Security key on gateway side String, required
mode defaults to test and in case for production mode is have to be live String, optional

Get payment gateway

var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/gateways/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Gateways();
$res = $svc->get()
    ->withId("582eb40446ab09c34205bc82")
    ->call();
?>
curl -X "GET" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
"Example of Response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "gateway",
    "data": {
      "_id": "582eb40446ab09c34205bc82",
      "created_at": "2016-11-18T07:55:48.007Z",
      "merchant": "r7pcwvkbkgjfzk99",
      "name": "Braintreee",
      "password": "password",
      "type": "Brain",
      "updated_at": "2016-12-16T11:44:23.356Z",
      "username": "username",
      "mode": "test",
      "active_subscriptions": 0
    }
  }
}

GET /v1/gateways/{_id}

Retrieves data on a gateway with specified ID.

Parametrs

Name Description Details
_id Gateway Identifier String, required

Update gateway

var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/gateways/{_id}',
    body: {
           "name": "String",
           "username": "String",
           "password": "String"
        },
    method: 'PUT',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Gateways();
$res = $svc->update("582eb40446ab09c34205bc82", "Brain", "BraintreeTesting", "<merchantid>", "<username>", "<password>", "test")
    ->call();
?>
curl -X "PUT" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"Gateway Name\",\"username\":\"Gateway Username\",\"password\":\"Gateway Password\"
"Example Response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "gateway",
    "data": {
      "created_at": "2016-12-22T09:02:35.491Z",
      "updated_at": "2016-12-22T09:07:16.227Z",
      "type": "PromisePay",
      "name": "PromisePay Update",
      "username": "username",
      "password": "password",
      "_id": "585b96abe45b75bc36808739",
      "mode": "test"
    }
  }
}

PUT /v1/gateways/{_id}

Updates configuration for a gateway.

eWay

Name Details
name String, required
username String, required
password String, required
mode String, required

Braintree

Name Details
name String, required
merchant String, required
username String, required
password String, required
mode String, required

Ezidebit

Name Details
name String, required
username String, required
password String, required
mode String, required

Stripe

Name Details
name String, required
password String, required
mode String, required

PayPal

Name Details
name String, required
username String, required
password String, required
mode String, required

Pin

Name Details
name String, required
password String, required
mode String, required

PayWay

Name Details
name String, required
merchant String, required
username String, required
password String, required
Gateway Certificate PassPhrase String, required
Gateway Certificate Id String, required
mode String, required
Certificate file File, required

SecurePay

Name Details
name String, required
merchant String, required
password String, required
mode String, required

Authorize.net

Name Details
name String, required
merchant String, required
key String, required
mode String, required

Payment Express

Name Details
name String, required
username String, required
password String, required
mode String, required

WorldPay

Name Details
name String, required
username String, required
password String, required
mode String, required

NAB

Name Details
name String, required
username String, required
password String, required
mode String, required

Merchant Warrior

Name Details
name String, required
merchant String, required
password String, required
mode String, required

SQID

Name Details
name String, required
merchant String, required
username String, required
password String, required
mode String, required

PromisePay

Name Details
name String, required
username String, required
password String, required
mode String, required

Forte

Name Details
type String, required
name String, required
username String, required
merchant String, required
signature String, required
password String, required
mode String, optional

IpPayments

Name Details
type String, required
name String, required
username String, required
password String, required
mode String, optional

Payeezy

Name Details
type String, required
name String, required
username String, required
password String, required
signature String, required
mode String, optional

Get gateway list

var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/gateways',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Gateways();
$res = $svc->get()
    ->call();
?>
curl -X "GET" "https://api-sandbox.paydock.com/v1/gateways" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "gateways",
    "data": [
      {
        "_id": "582eb40446ab09c34205bc82",
        "created_at": "2016-11-18T07:55:48.007Z",
        "merchant": "r7pcwvkbkgjfzk99",
        "name": "Braintreee",
        "password": "password",
        "type": "Brain",
        "updated_at": "2016-12-21T08:11:36.260Z",
        "username": "username",
        "mode": "test"
      },
      {
        "_id": "5853d3974f76d26c24e69165",
        "created_at": "2016-12-16T11:44:23.356Z",
        "name": "Promise Pay",
        "password": "password",
        "type": "PromisePay",
        "updated_at": "2016-12-21T08:11:36.261Z",
        "username": "username",
        "mode": "test"
      }
    ],
    "count": 2,
    "limit": 0,
    "skip": 0
  }
}

GET /v1/gateways

Returns all gateways for the account, limited to 100 records.

Delete gateway

var request = require('request');

request({
    url: 'https://api.paydock.com/v1/gateways/{_id}',
    method: 'DELETE',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");

$svc = new Gateways();
$res = $svc->delete("582eb40446ab09c34205bc82")
    ->call();
?>
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
"Example of response (200)"
{
  "status": 200,
  "error": null,
  "resource": {
    "type": "gateway",
    "data": {
      "created_at": "2016-12-22T09:02:35.491Z",
      "updated_at": "2016-12-22T09:07:16.227Z",
      "type": "PromisePay",
      "name": "PromisePay Update",
      "username": "username",
      "password": "password",
      "_id": "585b96abe45b75bc36808739",
      "mode": "test"
    }
  }
}

DELETE /v1/gateways/{_id}

Removes gateway with specified ID. A gateway cannot be removed if it has subscriptions running through it.

Name Description Details
_id Gateway Identifier String, required

Vault

PayDock also has a PCI compliant vault that lets you access and store customer payment details from all of your payment gateways. Our vault gives you the power to prefill customer card details and help your customers transact faster - regardless of payment gateway you process transactions with.

The vault is built on PayDock infrastructure so you do not wear any liability or data risk.

Create a vault token

curl -X "POST" "https://api-sandbox.paydock.com/v1/vault/payment_sources" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"card_name\":\"Test\",\"card_number\":\"4444333322221111\",\"expire_month\":\"01\",\"expire_year\":\"2019\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/vault/payment_sources',
    body: {
        "card_name":"Test User",
        "card_number":"4200000000000000",
        "expire_month":"01",
        "expire_year":"17"
    },
    method: 'POST',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new Vault();
$res = $svc->create("4111111111111111", "2020", "10", "Test Name")
    ->call();
?>
"Example of response (201)"
{
    "status": 201,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "updated_at": "2017-11-14T04:45:01.476Z",
            "vault_token": "252e65e9-e4bc-422b-abb6-b2bf25d32c9c",
            "card_name": "Test User",
            "expire_month": 1,
            "expire_year": 2019,
            "card_number_last4": "1111",
            "card_scheme": "visa",
            "status": "active",
            "created_at": "2017-11-14T04:45:01.419Z",
            "user_id": "57fc7066101fdd72799668f3",
            "company_id": "57fc7066101fdd72799668f4",
            "_source_ip_address": "220.101.98.130",
            "type": "card"
        }
    }
}

POST /v1/vault/payment_sources

Create a new payment token representing user’s payment information.

Field Name Description Details
card_name Name of cardholder String, required for card
card_number Credit card number String, required for card
expire_month Card expiry month Integer, required for card
expire_year Card expiry year Integer, required for card

Get vault tokens

curl -X "GET" "https://api-sandbox.paydock.com/v1/vault/payment_sources" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d ""
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/vault/payment_sources',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new Vault();
$response = $svc->get()
    ->call();
?>
"Example of response (200)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "payment_sources",
        "data": [
            {
                "updated_at": "2017-10-25T05:42:19.601Z",
                "vault_token": "a302a89d-2149-47bb-8ce9-d4154b4546af",
                "card_name": "John Smith",
                "expire_month": 4,
                "expire_year": 2020,
                "address_line1": "100 De Neve Drive",
                "address_city": "Sydney",
                "address_state": "NSW",
                "address_country": "Australia",
                "card_number_last4": "4242",
                "card_scheme": "visa",
                "email": "[email protected]",
                "phone": "+6112123123",
                "first_name": "VaultToken",
                "last_name": "TestUser",
                "status": "active",
                "created_at": "2017-10-25T05:42:19.476Z",
                "user_id": "57fc7066101fdd72799668f3",
                "company_id": "57fc7066101fdd72799668f4",
                "_source_ip_address": "220.101.98.130",
                "type": "card"
            },
            {
                "updated_at": "2017-10-25T01:11:28.575Z",
                "vault_token": "a09de9c7-547e-466a-a1ed-2d089691d30c",
                "card_name": "Jimmy Hendrix",
                "expire_month": 4,
                "expire_year": 2021,
                "address_line1": "100 De Neve Drive",
                "address_city": "Sydney",
                "address_state": "NSW",
                "address_country": "Australia",
                "card_number_last4": "4242",
                "card_scheme": "visa",
                "email": "[email protected]",
                "phone": "+6112123123",
                "first_name": "Jimmy",
                "last_name": "Hendrix",
                "status": "active",
                "created_at": "2017-10-25T01:11:28.436Z",
                "user_id": "57fc7066101fdd72799668f3",
                "company_id": "57fc7066101fdd72799668f4",
                "_source_ip_address": "220.101.98.130",
                "type": "card"
            },
        ],
        "count": 2,
        "limit": 100,
        "skip": 0
    }
}

GET /v1/vault/payment_sources

Returns all vault tokens for the account, limited to 100 records.

Get single vault token

curl -X "GET" "https://api-sandbox.paydock.com/v1/vault/payment_sources/{_id}" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d ""
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/vault/payment_sources/{_id}',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new Vault();
$response = $svc->get()
    ->withToken($vaultToken)
    ->call();
?>
"Example of response (200)"
{
    "status": 200,
    "error": null,
    "resource": {
        "type": "payment_source",
        "data": {
            "updated_at": "2017-10-25T05:42:19.601Z",
            "vault_token": "a302a89d-2149-47bb-8ce9-d4154b4546af",
            "card_name": "John Smith",
            "expire_month": 4,
            "expire_year": 2020,
            "address_line1": "100 De Neve Drive",
            "address_city": "Sydney",
            "address_state": "NSW",
            "address_country": "Australia",
            "card_number_last4": "4242",
            "card_scheme": "visa",
            "email": "[email protected]",
            "phone": "+6112123123",
            "first_name": "VaultToken",
            "last_name": "TestUser",
            "status": "active",
            "created_at": "2017-10-25T05:42:19.476Z",
            "user_id": "57fc7066101fdd72799668f3",
            "company_id": "57fc7066101fdd72799668f4",
            "_source_ip_address": "220.101.98.130",
            "type": "card"
        }
    }
}

GET /v1/vault/payment_sources/{vault_token}

Returns payment source information associated with a vault token.

Development SDKs

PayDock provides SDKs or libaries for different programming languages to make integration as simple as possible.

Client side

Client SDK

The Client SDK is our recommended solution for collecting payment details on your website.

Client SDK documentation

The Client SDK is also available through npm.

More detailed documentation on classes and methods available through npm - reference by class.

PayDock.js

PayDock.js is a legacy solution to tokenise credit card credentials and taking payments online. Our recommended solution is to use the Client SDK.

PayDock.js is a client side library for converting all Credit Card and Direct Debit credentials into one-time tokens and securely sending financial information through a web form.

PayDock.js documentation

PayDock iFrame

PayDock iFrame is a legacy solution for tokenising credit card information and sending it through to PayDock. Our recommended solution is to use the Client SDK.

iFrame documentation

php SDK

The php SDK is available through composer on Packagist.

It’s open source, with the code available on github. We welcome feedback on the SDK.

.Net SDK

The .Net SDK comes in 2 flavours: .Net 4.0 and .Net Core:

It’s open source, with the code available on github. We welcome feedback on the SDK.

Java SDK

The Java SDK is available from JCentre.

There are different dependency snippets to be inserted in your code based on your build settings (we support Gradle, Maven or Ivy).

It’s open source, with the code available on github. We welcome feedback on the SDK.

Android SDK

The Android SDK is available from JCentre.

There are different dependency snippets to be inserted in your code based on your build settings (we support Gradle, Maven or Ivy).

It’s open source, with the code available on github. We welcome feedback on the SDK.

Client-sdk

Our Client-SDK is a solution for collecting and handling payment sources in secure way on your website.

With the Client SDK you can create a payment form widget as an independent part or within your forms.

The SDK supports methods for customization of widget by your needs (styling, form fields, etc)

Other information

To work with the widget you will need your public_key and an added gateway - How do I get this?

Get started

There are three ways to integrate PayDock’s Client SDK:

  1. Download from CDN - Add the script tag to your page
  2. Download from CDN - Download the library
  3. Install the library with package manager

Download from CDN - Script Tag

<script src="https://app.paydock.com/v1/widget.umd.min.js"></script>
<script>
    var widget = new paydock.HtmlWidget('#tag', 'publicKey', 'gatewayId');
</script>

Copy and paste the script tag on the right to your page, making sure you have the correct verison of the PayDock app to get started:

Compressed version for production https://app.paydock.com/v1/widget.umd.min.js

Full version for development and debug https://app.paydock.com/v1/widget.umd.js

Download from CDN - Download Library

Download the PayDock Client library and add it to your website domain.

Download the production version here - https://app.paydock.com/v1/widget.umd.min.js

Download the development version here - https://app.paydock.com/v1/widget.umd.js

The library will always be available via the global variable paydock.

For more advanced use, the library has UMD format, thus can be used in requireJs, webpack, etc.

Install library with package manager

// ES2015 / TypeScript

import { HtmlWidget } from '@paydock/client-sdk/widget';

let widget = new HtmlWidget('#selector', 'publicKey', 'gatewayId');
<script src="@paydock/client-sdk/bundles/widget.umd.min.js"></script>
<script>
    var widget = new paydock.HtmlWidget('#tag', 'publicKey', 'gatewayId');
</script>

To install with package manager, enter the following command:

npm install client-sdk

You can use ES2015 or TypeScript modules

@paydock/client-sdk/widget

Also can use UMD module (global visibility, see above)

@paydock/client-sdk/bundles/widget.umd.js

@paydock/client-sdk/bundles/widget.umd.min.js

Widget

You can find description of all methods and parameters here.

This gives you a payment form where it is possible to enter card data/bank accounts and then receive a one-time token for charges, subscriptions etc.

This form can be customized (e.g. set fields and styles).

It is possible in real-time to monitor the actions of user with widget and get information about payment-source using ‘Events’.

Widget simple example

Container

<div id="widget"></div>

You must create a container for the widget. Inside this tag, the widget will be initialized.

Initialization

var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
widget.load();
// ES2015 | TypeScript

import { HtmlWidget } from '@paydock/client-sdk/widget';

var widget = new HtmlWidget('#widget', 'publicKey', 'gatewayId');
widget.load();

Then write only need 2 lines of code in js to initialize widget.

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 100%;height: 300px;}</style>
</head>
<body>
    <form id="paymentForm">
        <div id="widget"></div>
        <input name="payment_source_token" id="payment_source_token" type="hidden">
    </form>
    <script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
    <script>
        var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
        widget.interceptSubmitForm('#paymentForm');
        widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
        widget.load();
    </script>
</body>
</html>

Widget advanced example

Customization

widget.setStyles({
        background_color: 'rgb(0, 0, 0)',
        border_color: 'yellow',
        text_color: '#FFFFAA',
        button_color: 'rgba(255, 255, 255, 0.9)',
        font_size: '20px'
    });

This example shows how you can customize to your needs and design.

Customization from html

<div id="widget"
     widget-style="text-color: #FFFFAA; border-color: #yellow"
     title="Payment form"
     finish-text="Payment resource was successfully accepted"></div>

This example shows how you can set style and texts from html.

Settings

widget.setRefId('id'); // your unique identifier to identify the data

widget.setFormFields(['phone', 'email']); // add additional fields for form of widget

widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported card types

This example shows how you can use a lot of other methods to settings your form.

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 100%;height: 400px;}</style>
</head>
<body>
<form id="paymentForm">
    <div id="widget"
        widget-style="text-color: #FFFFAA; border-color: #yellow"
        title="Payment form"
        finish-text="Payment resource was successfully accepted"></div>
</form>

<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
    var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');

    widget.setSupportedCardIcons(['mastercard', 'visa']);
    widget.setFormFields(['phone', 'email']);
    widget.setRefId('custom-ref-id');
    widget.interceptSubmitForm('#paymentForm');
    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');

    widget.load();
</script>
</body>
</html>

Payment sources widget

You can find description of all methods and parameters here for payment sources.

This widget provides a list of previously added (saved) payment-sources by customer_id or reference. The widget provides an opportunity to use events to track the process of selecting payment-sources and provide meta information about the payment-sources.

Payment-source requires a query_token that represents a pre-generated and secure token for limiting the list payment-sources, for a specific user or reference.

In order to generate this token, you need to send a GET request to getCustomerList where required query parameter must be id or reference. In response you get response.query_token which you can use in the widget.

Payment sources simple example

Container

<div id="list"></div>

You must create a container for the widget. Inside this tag, the widget will be initialized.

Initialization

var list = new paydock.HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
list.load();
// ES2015 | TypeScript

import { HtmlPaymentSourceWidget } from '@paydock/client-sdk/widget';

var list = new HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
list.load();

Then write only need 2 lines of code in js to initialize widget.

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 40%;height: 300px;}</style>
</head>
<body>
    <div id="list"></div>
    <script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
    <script>
        var list = new paydock.HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
        list.load();
    </script>
</body>
</html>

Payment sources advanced example

Customization

list.setStyles({
    icon_size: 'small'
});

This example shows how you can customize to your needs and design.

Settings


list.filterByTypes(['card', 'checkout']); // filter by any payment source types
list.filterByGatewayIds(['gateway1']); // also other filters

list.setRefId('id'); // your unique identifier to identify the data

list.setLimit(4); // Pagination elements will show if count of elements more then argument passed

list.onSelectInsert('input[name="ps_id"]', 'payment_source_id'); // insert one-time-token to your input after finish checkout

list.on('select', function(data) {
    console.log(data);
});

This example shows how you can use a lot of other methods to settings your form.

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 40%;height: 300px;}</style>
</head>
<body>
    <div id="list"></div>
    <input type="text" name="ps_id" />
    <script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
    <script>
        var list = new paydock.HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
        list.filterByTypes(['card', 'checkout']);
        list.filterByGatewayIds(['gateway1']);
        list.setRefId('id');
        list.setLimit(4);
        list.setStyles({
            icon_size: 'small'
        });

        list.load();

        list.onSelectInsert('input[name="ps_id"]', 'payment_source_id');
        list.on('select', function(data) {
            console.log(data);
        });
    </script>
</body>
</html>

Checkout button

You can find description of all methods and parameters here for the checkout button.

PayPal meta parameters description here.

ZipMoney meta parameters description here.

This widget allows you to turn your button into a fullly functional Checkout Button. As a result, you will be able to receive a one-time token for charges, subscriptions etc. And other data given to the user by the payment gateway.

Checkout button simple example

Container

<button type="button" id="button">
    checkout
</button>

You must create a button to turn it into checkout-button.

Initialization

var button = new paydock.CheckoutButton('#button', 'publicKey', 'gatewayId');
// ES2015 | TypeScript


var button = new CheckoutButton('#widget', 'publicKey', 'gatewayId');

Then write only need 2 lines of code in js to initialize widget.

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <button type="button" id="button">checkout</button>
    <script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
    <script>
        var button = new paydock.CheckoutButton('#button', 'publicKey', 'gatewayId');
    </script>
</body>
</html>

Checkout button advanced example

Optional methods

button.onFinishInsert('input[name="pst"]', 'payment_source_token'); // insert one-time-token to your input after finish checkout

button.setMeta({
       brand_name: 'Paydock',
       reference: '15',
       first_name: 'receiver-name',
       last_name: 'receiver-last-name',
       phone: '9379992'}); // settings for checkout pages

button.on('finish', function (data) { // Add handler of event
       console.log('on:finish', data);
});

This example shows how you can use a lot of other methods to settings your button.

Full Paypal example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<form>
    <button type="button" id="button">
        <img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" align="left" style="margin-right:7px;">
    </button>

    <input type="text" name="pst" />
</form>

<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
    var button = new paydock.CheckoutButton('#button', 'publicKey', 'gatewayId');
    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.setMeta({
           brand_name: 'Paydock',
           reference: '15',
           first_name: 'receiver-name',
           last_name: 'receiver-last-name',
           phone: '9379992'}); 

    button.on('finish', function (data) { 
           console.log('on:finish', data);
    });
</script>
</body>
</html>

Full ZipMoney example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<form>
    <button type="button" id="button">
        <img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTVrrEYxDmq4WXv7hfHygKD9ltnOqv0K6soSAhmbKNllPNYWiLiJA" align="left" style="margin-right:7px;">
    </button>

    <input type="text" name="pst" />
</form>

<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
    var button = new paydock.ZipmoneyCheckoutButton('#button', 'publicKey', 'gatewayId');
    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.setMeta({
       "tokenize": true,
       "first_name": "Test",
       "last_name": "Lname",
       "email":"[email protected]",
       "gender": "male",
       "charge": {
           "amount": "4",
           "currency":"AUD",
           "shipping_address": {
               "first_name": "Test",
               "last_name": "Lname",
               "line1": "test",
               "line2": "test",
               "country": "AU",
               "postcode": "3223",
               "city": "Sydney",
               "state": "LA"
           },
           "billing_address": {
               "first_name": "Test",
               "last_name": "Lname",
               "line1": "test",
               "line2": "test",
               "country": "AU",
               "postcode": "3223",
               "city": "Sydney",
               "state": "LA"
           },
           "items": [
               {
                   "name":"Shoess",
                   "amount":"2",
                   "quantity": 1,
                   "reference":"sds"
               },
               {
                   "name":"Shoess2",
                   "amount":"2",
                   "quantity": 1,
                   "reference":"sds1"
               }
           ]
       },

       "statistics": {
           "account_created": "2017-05-05",
           "sales_total_number": "5",
           "sales_total_amount": "4",
           "sales_avg_value": "45",
           "sales_max_value": "400",
           "refunds_total_amount": "21",
           "previous_chargeback": "true",
           "currency": "AUD",
           "last_login": "2017-06-01"
       }
    }); 

    button.on('finish', function (data) { 
           console.log('on:finish', data);
    });
</script>
</body>
</html>

PayPal Integration

Our recommended approach for Paypal integration is to use our Client SDK. This handles most of the complexity of integrating Paypal into your plaform. You can implement PayPal manually, in the process below.

PayPal checkout allows your customers to pay using PayPal. The PayPal checkout process creates a one-time token that can be used to add a payment source to a customer, create a customer or charge a customer.

The process for taking a payment with PayPal checkout is: Paypal checkout

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/external_checkout" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"mode\":\"tsest\",\"type\":\"paypal\",\"gateway_id\":\"583d7c75a1723f941b7137f4\",\"success_redirect_url\":\"https://docs.paydock.com\",\"error_redirect_url\":\"https://docs.paydock.com/charges.php\",\"description\":\"My test PayDock description\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/external_checkout',
    method: 'POST',
    body: {
        "mode": "test",
        "gateway_id":"583d7c75a1723f941b7137f4",
        "success_redirect_url":"https://docs.paydock.com",
        "error_redirect_url": "https://docs.paydock.com/charges.php",
        "description": "My test PayDock description"
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new ExternalCheckout();
$response = $svc->create("test", "58bf55343c541b5b87f741bd", "https://wwww.success.com", "https://www.failure.com", "", [])
    ->call();
"Example of response (201)"

{
  "status": 200,
  "error": null,
  "resource": {
    "type": "payment_source",
    "data": {
      "checkout_type": "link",
      "link": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-12D76527BK035913Y",
      "reference_id": "EC-12D76527BK035913Y",
      "mode": "test",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I"
    }
  }
}

Checkout link redirects a user to PayPal website which will require them to accept the agreements for using PayPal to process further transactions. The Merchant should place this link on the site, so that the end user can accept the checkout token for further operations (create customers, charges, subscriptions, update customer payment sources).

POST /v1/payment_sources/external_checkout

Field Name Description Details
mode Parameter which determines PayPal account mode. Values: test, live String, optional
gateway_id ID of a PayDock gateway. Note: only a PayPal Express checkout gateway has ability to work with checkout tokens String, required
success_redirect_url URL to which customers will be redirected to after accepting agreements on the PayPal checkout page. After redirecting, PayPal will add query param “token=[some PayPal token here]”. In PayDock response this token is named as “reference_id”. See examples String, required
error_redirect_url URL to which customers will be redirected to after canceling operations or experiencing an error on the PayPal checkout page. After redirecting, PayPal will add query param “token=[some PayPal token here]”. In PayDock response this token is named as “reference_id”. See examples String, required
description Custom description that will be shown on a PayPal page when accepting the token String, optional
meta Object where can be specified optional information about customer Object, optional, optional
brand_name A label that overrides the business name in the PayPal account on the PayPal hosted checkout pages String, optional
reference Merchant Customer Service number displayed on the PayPal pages String, optional
email The consumer’s email String, optional
hdr_img URL for the image you want to appear at the top left of the payment page String, optional
logo_img A URL to your logo image String, optional
first_name The consumer’s given names String, optional
last_name The consumer’s surname String, optional
address_line Street address String, optional
address_line2 Second line of the address String, optional
address_city City String, optional
address_postcode Postcode String, optional
hide_shipping_address Determines whether PayPal displays shipping address fields on the PayPal pages String, optional
phone The consumer’s phone number in E.164 international notation (Example: +12345678901) String, optional

Create PayDock one-time token using PayPal checkout token

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]" \
     -H "Content-Type: application/json" \
     -d "{\"type\":\"checkout_token\",\"gateway_id\":\"583d78caa17233341b712bbc\",\"checkout_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]',
    method: 'POST',
    body: {
        "type":"checkout_token",
        "gateway_id":"583d78caa17233341b712bbc",
        "checkout_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I"
    },
    headers: {
        'content-type' : 'application/json'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$apiLink       = 'https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]';
$apiPublicKey  = 'user_public_key';

$query = http_build_query([
    'public_key'   => $apiPublicKey
]);

$data = json_encode([
    'type'                 => 'checkout_token',
    'gateway_id'           => '583d78caa17233341b712bbc',
    'checkout_token'       => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink . '?' . $query);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: ". strlen($data),
    "x-user-secret-key:". $apiKey,
]);

$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"

{
  "status": 201,
  "error": null,
  "resource": {
    "type": "token",
    "data": "bb7fcdfc-1322-sdd8-adba-2c265adb8b25"
  }
}

Before initiating a call to create a one-time token for PayPal, the user must have created a PayPal checkout token using the checkout link. The response returns a one-time token that can be used to:

POST /v1/payment_sources/tokens?public_key=[users_public_key]

Field Name Description Details
type Type of payment source gateway to be created. Available values: “checkout_token” String, required
gateway_id Id of a gateway, that was previously added to PayDock String, required
public_key PayDock users public key String, required
checkout_token Token, that was created on previously step. String, required

Afterpay Integration

Afterpay checkout allows your customers to pay using Afterpay. The Afterpay checkout process creates a one-time token that can be used to add a direct payment.

Before allowing a customer to checkout with Afterpay, check the configuration for Afterpay to ensure that this order will be accepted successfully. You can do this by calling (Afterpay configuration)[#afterpay-configuration]. The configuration does not need to be checked before every order, but it should be checked regularly (eg every day).

Using the client SDK

The easiest way to do this is through the client SDK

Direct API integration

You can also integrate directly with the Paydock API, without using the client SDK.

The process for taking a payment with Afterpay checkout is:

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/external_checkout" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\”mode\”:\”test\”, \”error_redirect_url\”: \”https://docs.paydock.com\”, \”success_redirect_url\”: \”https://google.com\”, \”type\”:\”afterpay\”, \”gateway_id\”:\”59003f15eccac620e61aad6c\”, \”meta\”: { \”amount\”: \”50\”, \”currency\”: \”AUD\”, \”reference\”: \”testreference\”, \”email\”: \”[email protected]\”,  \”first_name\”: \”testFirstName\”, \”last_name\”: \”testLastName\”, \”address_line1\”: \”AddrLine1\”, \”address_line2\”: \”AddrLine2\”,  \”address_city\”: \”AddrCity\”, \”address_state\”: \”NSW\”, \”address_postcode\”: \“1234\”,  \”address_country\”: \”AddrCountry\”,  \”phone\”: \”040000000\”} }"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/external_checkout',
    method: 'POST',
    body: {
            "error_redirect_url": "https://docs.paydock.com",
            "success_redirect_url": "https://google.com",
            "gateway_id":"59003f15eccac620e61aad6c",
            "meta":
                {
                "amount": "20",
                "currency": "AUD",
                "items":[{
                    "name": "widget1",
                    "sku": "1234122346",
                    "quantity": 1,
                    "price": {
                       "amount": "10.00",
                        "currency": "AUD"
                     }
                    },
                    { "name": "widget2",
                      "sku": "1234122345",
                      "quantity": 1,
                      "price": {
                         "amount": "10.00",
                         "currency": "AUD"
                        }
                    }
                ],
                "reference": "testreference",
                "email": "[email protected]",
                "first_name": "testFirstName",
                "last_name": "testLastName",
                "address_line1": "AddrLine1",
                "address_line2": "AddrLine2",
                "address_city": "AddrCity",
                "address_state": "NSW",
                "address_postcode": "1234",
                "address_country": "AddrCountry",
                "phone": "040000000"
                }
          },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new ExternalCheckout();

$meta =  [
    'amount' => '50',
    'currency' => 'AUD',
    'reference' => 'testreference',
    'email' => '[email protected]',
    'first_name' => 'testFirstName',
    'last_name' => 'testLastName',
    'address_line1' => 'AddrLine1',
    'address_line2' => 'AddrLine2',
    'address_city' => 'AddrCity',
    'address_state' => 'NSW',
    'address_postcode' => '1234',
    'address_country' => 'AddrCountry',
    'phone' => '040000000'
];

$reference = uniqid();
$response = $svc->create("test", "59714107fd3abd105fd8ea42",  "https://wwww.success.com", "https://www.failure.com", "", $meta, "", $reference)
    ->call();
?>
"Example of response (201)"

{
  "status": 200,
  "error": null,
  "resource": {
    "type": "payment_source",
    "data": {
      "link": "https://www-sandbox.secure-afterpay.com.au/checkout/?token=4a76e7gd007j2dfducnrhpiemd79q37ocbp8drlt0041mnbn9afd",
      "mode": "test",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiY2hlY2tvdXRfdG9rZW4iLCJnYXRld2F5X2lkIjoiNTkwMDNmMTVlY2NhYzYyMGU2MWFhZDZjIiwiZ2F0ZXdheV90eXBlIjoiQWZ0ZXJwYXkiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiI0YTc2ZTdnZDAwN2oyZGZkdWNucmhwaWVtZDc5cTM3b2NicDhkcmx0MDA0MW1uYm45YWZkIn0sIm1vZGUiOiJ0ZXN0IiwiaWF0IjoxNDkzMjk3MjY3fQ.z5pva920TWoe9q4wqAFii97j4Y9OEG0q6nnNICPaxn0"
    }
  }
}

Checkout link redirects a user to Afterpay website which will require them to accept the agreements for using Afterpay to process transaction. The Merchant should place this link on the site, so that the end user can accept the checkout token for further operation (create charge).

POST /v1/payment_sources/external_checkout

Field Name Description Details
gateway_id ID of a PayDock gateway. Note: only “Afterpay” gateway has ability to work with this type of checkout tokens String, required
success_redirect_url URL to which customers will be redirected to after accepting agreements on the Afterpay checkout page. After redirecting, Afterpay will add query param “token=[some Afterpay token here]”. In PayDock response this token is named as “reference_id”. See examples String, required
error_redirect_url URL to which customers will be redirected to after canceling operations or experiencing an error on the Afterpay checkout page. After redirecting, Afterpay will add query param “token=[some Afterpay token here]”. In PayDock response this token is named as “reference_id”. See examples String, required
description Custom description that will be shown on a Afterpay page when accepting the token String, optional
meta Object with additional information, needed for particular gateway Object, optional
amount Amount to be payed String, required
currency Currency code String, optional
items Additional information of an order items Array, optional
name Product name String, required
sku Product SKU String, optional
quantity The quantity of the item Number, required
price The price of the item String, required
amount The amount of an item rounded to 2 decimal places Number, required
currency The currency is a ISO 4217 format value. Currently only AUD is supported String, required
email The consumer’s email String, optional
first_name The consumer’s given names String, optional
last_name The consumer’s surname String, optional
address_line1 Street address String, optional
address_line2 Second line of the address String, optional
address_city City String, optional
address_state State String, optional
address_postcode Postcode String, optional
address_country ISO 3166-1 country code String, optional
phone The consumer’s phone number in E.164 international notation (Example: +12345678901) String, optional

Create Afterpay one-time token using Afterpay checkout token

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"type\": \"checkout_token\" ,\"gateway_id\":\"583d7c75a1723f941b7137f4\",\"checkout_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=fdsrtk5jl83d7c75a1723f941b7137f4',
    method: 'POST',
    body: {
        "type": "checkout_token",
        "gateway_id":"583d78caa17233341b712bbc",
        "checkout_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I"
    },
    headers: {
        'content-type' : 'application/json'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$apiLink       = 'https://api-sandbox.paydock.com/v1/payment_sources/tokens';
$apiKey        = 'user_secret_key';
$apiPublicKey  = 'user_public_key';

$query = http_build_query([
    'public_key'   => $apiPublicKey
]);

$data = json_encode([
    'type'                 => 'checkout_token',
    'gateway_id'           => '583d78caa17233341b712bbc',
    'checkout_token'       => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink . '?' . $query);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: ". strlen($data),
    "x-user-secret-key:". $apiKey,
]);

$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"

{
  "status": 201,
  "error": null,
  "resource": {
    "type": "token",
    "data": "bb7fcdfc-1322-sdd8-adba-2c265adb8b25"
  }
}

Before initiating a call to create a one-time token for Afterpay, the user must have created a Afterpay checkout token using the checkout link. The response returns a one-time token that can be used to:

POST /v1/payment_sources/tokens?public_key=[users_public_key]

Field Name Description Details
type Type of payment source gateway to be created. Use checkout_token for case, when token created on previous step in PayDock. Use external_checkout_token for token, that was created and accepted on gateway side String, required
gateway_id Id of a gateway, that was previously added to PayDock String, required
public_key PayDock users public key String, required
checkout_token Token, that was created on previous step (used with type - checkout_token) or generated and accepted on gateways side (used with type - external_checkout_token) . String, required

Afterpay Configuration

curl -X "GET https://api-sandbox.paydock.com/v1/gateways/[afterpay_gateway_id]/config" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json"
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/gateways/[afterpay_gateway_id]/config',
    method: 'GET',
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways/[afterpay_gateway_id]/config';
$apiKey  = 'user_secret_key';

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $apiLink);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json",
  "x-user-secret-key:". $apiKey,
]);

$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"

{
    "status": 200,
    "error": null,
    "resource": {
        "type": "configs",
        "data": [
            {
                "type": "PAY_BY_INSTALLMENT",
                "description": "Pay over time",
                "maximumAmount": {
                    "amount": "1000.00",
                    "currency": "AUD"
                }
            }
        ]
    }
}

Retrieve the configuration from Afterpay to confirm the maximum amount allowed for a transaction. This should be called regularly (eg every day).

GET https://api-sandbox.paydock.com/v1/gateways/[afterpay_gateway_id]/config

Other features

You can also use other standard requests from the Paydock API to work with Afterpay transactions including:

Zip Money Integration

ZipMoney checkout allows your customers to pay using ZipMoney or ZipPay. The checkout process creates a one-time token that can be used to add a direct payment.

The process includes the customer logging in or signing up for ZipMoney or ZipPay.

ZipMoney will allow you to store payment details, without needing the customer to log in again. This needs to be approved by ZipMoney for your account. If tokenisation is enabled for your account, you can through tokenize = true to enable.

We also recommend that you send through as many parameters as possible, as it is more likely that transactions will be approved with more information.

When a new account is being created, it might not be immediately approved. See Refer Process for more details.

Using the client SDK

The easiest way to do this is through the client SDK, which handles the process of displaying a login window through to creating a payment token. Once you have a token, you can use that to either save the payment details or create a payment, see Client SDK Documentation.

Direct API integration

We recomment that the client SDK should be used with ZipMoney. However you can also directly integrate with the PayDock API.

The process for taking a payment with ZipMoney checkout is:

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/external_checkout" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"mode\": \"test\",\"gateway_id\":\"59637d35f2aa0c136b0128e2\",\"redirect_url\":\"https://docs.paydock.com\",\"reference\": \"transaction_reference_number\",\"meta\": {\"first_name\": \"Fname\",\"last_name\": \"Lname\",\"tokenize\": true,\"shipping_address\": { \"first_name\": \"Fname\", \"last_name\": \"Lname\", \"line1\": \"1 Help St\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" }, \"billing_address\": { \"first_name\": \"Fname\", \"last_name\": \"Lname\", \"line1\": \"1 Help St\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" },\"amount\": \"4\", \"currency\":\"AUD\",\"reference\":\"transaction_reference\",\"email\":\"[email protected]\",\"items\": [{\"name\":\"Shoes\",\"amount\":\"2\",\"quantity\": 1,\"reference\":\"sds\"},{\"name\":\"Shoes2\",\"amount\":\"2\",\"quantity\": 1,\"reference\":\"sds1\"}],\"statistics\": {\"account_created\": \"2017-05-05\",\"sales_total_number\": \"5\",\"sales_total_amount\": \"4\",\"sales_avg_value\": \"45\",\"sales_max_value\": \"400\",\"refunds_total_amount\": \"1\",\"previous_chargeback\": \"false\",\"currency\": \"AUD\",\"last_login\": \"2017-06-01\"}},\"description\": \"My test PayDock description\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources/external_checkout',
    method: 'POST',
    body: {
            "mode": "test",
            "gateway_id":"59637d35f2aa0c136b0128e2",
            "redirect_url":"https://docs.paydock.com",
            "reference": "transaction_reference_number",
            "meta": {
                "first_name": "Fname",
                "last_name": "Lname",
                "email":"[email protected]",
                "tokenize": true,
                 "description": "My test PayDock description",
                "charge": {
                    "shipping_address": {
                        "first_name": "Fname",
                        "last_name": "Lname",
                        "line1": "1 Help St",
                        "country": "AU",
                        "postcode": "2000",
                        "city": "Sydney",
                        "state": "NSW"
                    },
                    "billing_address": {
                        "first_name": "Fname",
                        "last_name": "Lname",
                        "line1": "1 Help St",
                        "country": "AU",
                        "postcode": "2000",
                        "city": "Sydney",
                        "state": "NSW"
                    },
                    "amount": "4",
                    "currency":"AUD",            
                    "items": [{
                        "name":"Shoes",
                        "amount":"2",
                        "quantity": 1,
                        "reference":"sds"
                    },
                    {
                        "name":"Shoes2",
                        "amount":"2",
                        "quantity": 1,
                        "reference":"sds1"
                    }],
                },
                "statistics": {
                    "account_created": "2017-05-05",
                    "sales_total_number": "5",
                    "sales_total_amount": "4",
                    "sales_avg_value": "45",
                    "sales_max_value": "400",
                    "refunds_total_amount": "1",
                    "previous_chargeback": "false",
                    "currency": "AUD",
                    "last_login": "2017-06-01"
                }
            },
        },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$svc = new ExternalCheckout();

$meta =  [
    "first_name"=> "Fname",
    "last_name"=> "Lname",
    "email"=>"[email protected]",
    "tokenize"=> true,
    "description"=> "My test PayDock description",
    "charge"=> [
        "shipping_address"=> [
            "first_name"=> "Fname",
            "last_name"=> "Lname",
            "line1"=> "1 Help St",
            "country"=> "AU",
            "postcode"=> "2000",
            "city"=> "Sydney",
            "state"=> "NSW"
        ],
        "billing_address"=> [
            "first_name"=> "Fname",
            "last_name"=> "Lname",
            "line1"=> "1 Help St",
            "country"=> "AU",
            "postcode"=> "2000",
            "city"=> "Sydney",
            "state"=> "NSW"
        ],
        "amount"=> "4",
        "currency"=>"AUD",
        "items"=> [[
            "name"=>"Shoes",
            "amount"=>"2",
            "quantity"=> 1,
            "reference"=>"sds"
        ],
        [
            "name"=>"Shoes2",
            "amount"=>"2",
            "quantity"=> 1,
            "reference"=>"sds1"
        ]],
    ],
    "statistics"=> [
        "account_created"=> "2017-05-05",
        "sales_total_number"=> "5",
        "sales_total_amount"=> "4",
        "sales_avg_value"=> "45",
        "sales_max_value"=> "400",
        "refunds_total_amount"=> "1",
        "previous_chargeback"=> "false",
        "currency"=> "AUD",
        "last_login"=> "2017-06-01"
    ]
];

$reference = uniqid();
$response = $svc->create("test", "599a76529c1d950790167453", "", "", "https://www.redirecturl.com", $meta, "", $reference)
    ->call();
?>
"Example of response (201)"

{
  "status": 200,
  "error": null,
  "resource": {
    "type": "payment_source",
    "data": {
      "link": "https://www-sandbox.secure-Zip Money.com.au/checkout/?token=4a76e7gd007j2dfducnrhpiemd79q37ocbp8drlt0041mnbn9afd",
      "mode": "test",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiY2hlY2tvdXRfdG9rZW4iLCJnYXRld2F5X2lkIjoiNTkwMDNmMTVlY2NhYzYyMGU2MWFhZDZjIiwiZ2F0ZXdheV90eXBlIjoiQWZ0ZXJwYXkiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiI0YTc2ZTdnZDAwN2oyZGZkdWNucmhwaWVtZDc5cTM3b2NicDhkcmx0MDA0MW1uYm45YWZkIn0sIm1vZGUiOiJ0ZXN0IiwiaWF0IjoxNDkzMjk3MjY3fQ.z5pva920TWoe9q4wqAFii97j4Y9OEG0q6nnNICPaxn0"
    }
  }
}

Checkout link redirects a user to Zip Money website which will require them to accept the agreements for using Zip Money to process transaction or create a new account. When this link is clicked the user can accept the checkout token for further operation (create charge).

When you create the checkout link, some of the information is optional. However providing as much information as possible will mean a new registration is more likely to be approved.

If someone is registering for the for a new account, their registration can be:

Referals require special handling, see Refer Process

POST /v1/payment_sources/external_checkout

Field Name Description Details
mode Parameter which determines Zip Money account mode. Values: ‘test’, ‘live’ String, optional
gateway_id ID of a PayDock gateway. Note: this will only work for gateways that are either Zip Money / Zip Pay String, required
redirect_url URL to which customers will be redirected to after signing into Zip Money / Zip Pay or registering for a new account. After redirecting, Zip Money will add query param “checkoutid=[some Zip Money token here]”. In PayDock response this token is named as “reference_id”. See examples String, required
description Custom description that will be shown on a Zip Money page when accepting the token String, optional
meta Object with additional information Object, required
first_name First name for the customer String, required
last_name Last name for the customer String, required
phone The consumer’s phone number in E.164 international notation (Example: +12345678901) String, optional
tokenize Controls whether to tokenize the Zip Money / Zip Pay account, defaults to ‘false’ Boolean, optional
email The consumer’s email String, required
gender Customer’s gender String, optional
date_of_birth Birthday of the customer String, optional
charge Charge information Object, required
amount Amount to be paid Float, required
currency Currency code String, required
items Collection of order items Object, required
name Name of the item String, required
amount Amount of the item String, required
quantity Quantity of the item Integer, required
type Type of the item, values can be: ‘sku’, ‘tax’, ‘shipping’, ‘discount’ String, optional
reference Reference of the item String, optional
item_uri Url of the item in your store String, optional
image_url Url of the image in your store String, optional
shipping_address Object with shipping address details Object, required
first_name Shipping first name String, optional
last_name Shipping last name String, optional
line1 Shipping address line 1 String, required
line2 Shipping address line 2 String, optional
city Shipping city String, required
state Shipping state String, required
postcode Shipping postcode String, required
country Shipping country String, required
billing_address Object with billing address details Object, optional
first_name Billing first name String, optional
last_name Billing last name String, optional
line1 Billing address line 1 String, required
line2 Billing address line 2 String, optional
city Billing city String, required
state Billing state String, required
postcode Billing postcode String, required
country Billing country String, required

Create Zip Money one-time token using Zip Money checkout token

curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"type\": \"checkout_token\" ,\"gateway_id\":\"583d7c75a1723f941b7137f4\",\"checkout_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I\"}"
var request = require('request');

request({
    url: 'https://api.paydock.com/v1/payment_sources//tokens?public_key=fdsrtk5jl83d7c75a1723f941b7137f4',
    method: 'POST',
    body: {
        "type": "checkout_token",
        "gateway_id":"583d78caa17233341b712bbc",
        "checkout_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I"
    },
    headers: {
        'content-type' : 'application/json'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$apiLink       = 'https://api-sandbox.paydock.com/v1/payment_sources/tokens';
$apiKey        = 'user_secret_key';
$apiPublicKey  = 'user_public_key';

$query = http_build_query([
    'public_key'   => $apiPublicKey
]);

$data = json_encode([
    'type'                 => 'checkout_token',
    'gateway_id'           => '583d78caa17233341b712bbc',
    'checkout_token'       => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink . '?' . $query);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: ". strlen($data),
    "x-user-secret-key:". $apiKey,
]);

$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"

{
  "status": 201,
  "error": null,
  "resource": {
    "type": "token",
    "data": "bb7fcdfc-1322-sdd8-adba-2c265adb8b25"
  }
}

Before initiating a call to create a one-time token for Zip Money, the user must have created a Zip Money checkout token using the checkout link. The response returns a one-time token that can be used to:

POST /v1/payment_sources/tokens?public_key=[users_public_key]

Field Name Description Details
type Type of payment source gateway to be created. Use checkout_token for case, when token created on previous step in PayDock. Use external_checkout_token for token, that was created and accepted on gateway side String, required
gateway_id Id of a gateway, that was previously added to PayDock String, required
public_key PayDock users public key String, required
checkout_token Token, that was created on previous step (used with type - checkout_token) or generated and accepted on gateways side (used with type - external_checkout_token) . String, required

Zip Money Refer Process

In some cases when a new account is registered, it might not be possible to make an immediate approval. In this case, if this is approved, the user will get an email with a link to confirm their new account. This link will redirect them to the success_redirect_url configured in the checkout link. It’s important that this URL contains enough information for them to continue the checkout. For example, this should include the id for the shopping cart for the user.

From there, the process is similar to a standard checkout flow, Create a Paydock token then use that token to make the payment.

Other features

You can also use other standard requests from the Paydock API to work with ZipMoney transactions including:

PayDock.js

We do not recommend using PayDock.js to take payments - this is a legacy solution.

Our recommended approach of collecting payment details is to use our Client SDK.

Only if Client SDK is not an option should Paydock.js be used to collect payment details.

PayDock.js is a client side library for converting all Credit Card and Direct Debit credentials into one-time tokens and securely sending information from a web form. Using this library, you can avoid sending credit card or bank account details to your server, reducing your PCI compliance requirements.

This library is a wrapper around the PayDock API and provides a javascript friendly interface to creating tokens.

The overall process is: Paydock.js token

Quick start

Paydock.setPublicKey('YOUR_API_PUBLIC_KEY');
Paydock.setSandbox(true); // false is default value

It’s easy to start using PayDock.js. Just add the following script to your website, set the endpoint and public key and start making calls.

<script type="text/javascript" src="https://app.paydock.com/v1/paydock.min.js"></script>

Setting Customer public key

Your must set your Public Key before using Paydock.js to identify the website when communicating with PayDock.

Credentials can be gathered from the Customer Account page on the PayDock Admin Portal.

Paydock.setPublicKey('YOUR_API_PUBLIC_KEY');

API endpoints

Production

Use this method in script to send to Production endpoint

Paydock.setSandbox(false); // Default value.

Sandbox

Use this method in script to send to Sandbox endpoint

Paydock.setSandbox(true);

One-time token

CreateToken converts sensitive card data into one-time tokens which you can use to safely use to trigger operations related pass to your Customers such as creating charges, subscription, new Customers, or when updating the customer payment_source of a current customer.

You can create one-time tokens using either credit card or debit card details (see examples).

// create token with credit card
Paydock.createToken({
    gateway_id: "a133695479f51cdd1e2fc66b56455884215",
    type: "card",
    card_name: "Houston Willian",
    card_number: "4200000000000000",
    expire_month: "01",
    expire_year: "2019",
    card_ccv: "123",
    first_name: "Houston",
    last_name:"Willian"
    email: "[email protected]"},
    function (token, status) { // success callback
        console.log('token', token);
    },
    function (res, status) { // error callback
        console.log('errors', res);
    }
);

// create token with debit card
Paydock.createToken({
    gateway_id: "a133695479f51cdd1e2fc66b56455884215",
    type: "bsb",
    account_name: "Houston Willian",
    account_number: "1234",
    account_bsb: "123123",
    first_name: "Houston",
    last_name:"Willian"
    email: "[email protected]"},
    function (token, status) { // success callback
        console.log('token', token);
    },
    function (res, status) { // error callback
        console.log('errors', res);
    }
);

Parameters

Field Name Description Details
account_name Customer account name. Parameter required when using Direct Debit only String, required for bsb
account_bsb Customer bank state branch number. Parameter required when using Direct Debit only String, required for bsb
account_number Number of Customer account. Parameter required when using Direct Debit only Integer, required for bsb
account_routing Number of Customer account. BSB/Routing/SWIFT/IBAN Number. Integer, required for bank account
account_holder_type Account type (‘personal’ or ‘business’) Integer, required for bank account
account_bank_name Name of account bank Integer, required for bank account
gateway_id ID of a gateway in PayDock system. String, required
card_name Name on credit card String, required for credit card
card_number Credit card number Integer, required for credit card
expire_month Month of the credit card expiry Integer, required for credit card
expire_year Year of the credit card expiry Integer, required for credit card
card_ccv Security code on the back side of the card Integer, required for credit card
type Values are “card” or “bsb”. By default PayDock is using “card” type String, optional
first_name First name String, optional
last_name Last name String, optional
email Email String, optional

JQuery example

This example uses jquery to map the elements of the form to the data to be sent through using paydock.js.

The form includes customer details (email, phone etc), which are optional when creating a token.

Finally the form appends a hidden element, storing the one-time token in temp_token form field. This would need to be handled server side to create a customer, take a payment or create a subscription.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Paydock-js</title>
    </head>
    <body>
        <table width="100%">
            <tr>
                <td>
                    <form name="payment_source" method="post" action="form.php">
                        <label>
                            <input type="text" name="gateway_id"/>
                            gateway_id *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="card_name"/>
                            card_name *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="card_number"/>
                            card_number *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="expire_month"/>
                            expire_month *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="expire_year"/>
                            expire_year *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="card_ccv"/>
                            card_ccv *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="first_name"/>
                            first_name *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="last_name"/>
                            last_name *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="email"/>
                            email *
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="phone"/>
                            phone
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_line1"/>
                            address_line1
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_line2"/>
                            address_line2
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_city"/>
                            address_city
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_state"/>
                            address_state
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_country"/>
                            address_country
                        </label>
                        <br/>
                        <label>
                            <input type="text" name="address_postcode"/>
                            address_postcode
                        </label>
                        <br/>
                        <button type="submit">Send</button>
                    </form>
                </td>
            </tr>
        </table>

        <script src="//code.jquery.com/jquery-1.11.3.min.js"></script>
        <script src="https://app.paydock.com/v1/paydock.min.js"></script>
        <script language="text/javascript">
            // Token creation

            (function(form) {
                var form = $('form[name="payment_source"]');

                form.on('submit', function(event) {
                    Paydock.setPublicKey('YOUR_API_PUBLIC_KEY');

                    var formData = {};
                    form.serializeArray().map( function(input) {
                        formData[input.name] = input.value;
                    });

                    Paydock.createToken(
                        formData,
                        function (token, status) {
                            form.append($('<input type="hidden" name="temp_token" />').val(token));
                            form.get(0).submit();
                        },
                        function (res, status) {
                            $('#error').html(JSON.stringify(res));
                        }
                    );

                    event.preventDefault();
                });
            })();
        </script>
    </body>
</html>

iFrame

We do not recommend using this iFrame widget to take payments - this is a legacy solution.

Our recommended approach of collecting payment details is to initialise the iFrame through our Client SDK.

Our Client SDK wraps some of the complexity of creating an iframe in an easy to use javascript library. Only if you cannot use the Client SDK should you implement the iFrame manually via the process below.

The iFrame is a solution for collecting and handling payment sources in secure way. There are two steps to the iFrame configuration.

The overall process is:

iFrame token

First you need to generate a URL for your iframe, which you can do through our admin interface or by making calls to our API.

Once you have a iframe in place, you can collect the payment details from a number of sources:

Creating configuration token from the Web application

You can generate an iframe configuration token through the PayDock Admin Portal: iFrame token

From here, you can also style and preview your iframe: Style & prefview iFrame

Create configuration token with an API call

curl -X "POST https://api-sandbox.paydock.com/v1/remote-action/configs" \
     -H "x-user-secret-key: x-user-secret-key" \
     -H "Content-Type: application/json" \
     -d "{\"purpose\":\"payment_source\",\"predefined_fields\": {\"gateway_id\":\"1\",\"type\":\"card\"},\"defined_form_fields\": [\"first_name\",\"last_name\",\"email\",\"phone\",\"address_line1\",\"address_line2\",\"address_country\",\"address_city\",\"address_postcode\"]}"
var request = require('request');

request({
    url: 'https://api-sandbox.paydock.com/v1/remote-action/configs',
    method: 'POST',
    body: {
        "purpose": "payment_source",
        "defined_form_fields": [
            "first_name",
            "last_name",
            "email",
            "phone",
            "address_line1",
            "address_line2",
            "address_country",
            "address_city",
            "address_postcode"
        ],
        "allowed_response_data": {
            "url": ["payment_source"],
            "event": ["payment_source"]
        },
        "webhook_destination": "https://mywebsite.com/my-endpoint",
        "success_redirect_url": "https://docs.paydock.com",
        "error_redirect_url": "https://docs.paydock.com",
        "fields_validation": true,
        "supported_card_types": ['ausbc', 'visa', 'mastercard', 'diners', 'japcb', 'laser', 'solo', 'discover', 'amex'],
        "hidden_elements": ['submit_button', 'tabs'],
        "predefined_fields": {
            "gateway_id": "1",
            "type": "card"
        }
    },
    headers: {
        'content-type' : 'application/json',
        'x-user-secret-key': 'user_secret_key'
    }
}, function(error, response, body){
    if(error) {
        console.log(error);
    } else {
        console.log(response.statusCode, body);
    }
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/remote-action/configs';
$apiKey  = 'user_secret_key';

$data = json_encode([
    'purpose'               => 'payment_source',
    'predefined_fields'     => [
        'gateway_id'    => '58377235377aea03343240cc',
        'type'          => 'card' 
    ],
    'defined_form_fields'   => [
        'first_name',
        'last_name',
        'email',
        'phone',
        'address_line1',
        'address_line2',
        'address_country',
        'address_city',
        'address_postcode' 
    ],
    'webhook_destination'   => 'https://mywebsite.com/my-endpoint',
    'success_redirect_url'  => 'https://docs.paydock.com',
    'error_redirect_url'    => 'https://docs.paydock.com',
    'fields_validation'    => true,
    'supported_card_types'   => [
        'ausbc',
        'visa',
        'mastercard',
        'diners',
        'japcb',
        'laser',
        'solo',
        'discover',
        'amex' 
    ],
    'hidden_elements'   => [
            'submit_button',
            'tabs'
    ]
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: ". strlen($data),
    "x-user-secret-key:". $apiKey,
]);

$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"

{
  "status": 200,
  "error": null,
  "resource": {
    "type": "configurationToken",
    "data": {
      "configuration_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJnYXRld2F5X2lkIjoiNTgxYzc1M2E4ZjUxNTY0NzIzNjYzZmU3IiwidHlwZSI6ImNhcmQifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vYmxhYmxhIiwiZGVmaW5lZF9mb3JtX2ZpZWxkcyI6WyJmaXJzdF9uYW1lIiwibGFzdF9uYW1lIiwiZW1haWwiLCJwaG9uZSIsImFkZHJlc3NfbGluZTEiLCJhZGRyZXNzX2xpbmUyIiwiYWRkcmVzc19jb3VudHJ5IiwiYWRkcmVzc19jaXR5IiwiYWRkcmVzc19wb3N0Y29kZSJdLCJpYXQiOjE0NzgyNzE0NTd9.YP-cAKsC3_pPBmuQdD17zHNj8B6dZ1SILj86h8IeQBQ"
    }
  }
}

Rather than using the PayDock Admin portal, you can automate creating a configuration token using our API. This is useful for custom usages of the iframe.

POST /v1/remote-action/configs

Field Name Description Details
purpose Purpose of iFrame form. Available parameters: ‘payment_source’ string, required
webhook_destination Destination, where customer will receive all successful responses. Response will contain “data” object with “payment_source” parameter. Parameter “payment_source” used as “token” in future requests and needed for string, required
allowed_response_data Object containing event information to send Object optional
url Array of parameters to send on redirect url, allowed values are ‘payment_source’. Pass empty array to avoid sending any events Array optional
event Array of parameters to send on javascript events, allowed values are ‘payment_source’. In case of empty array will be set as default Array optional
success_redirect_url URL to which the Customer will be redirected to after the processed operation String, optional
error_redirect_url URL to which the Customer will be redirected to if an error is triggered in the process of operation String, optional
predefined_fields Object with required information Object, required
gateway_id ID of a gateway connected to PayDock String, required
type Type of payment source which shows in iFrame form. Parameters : “card”, “bsb”. String, required
defined_form_fields Array with iFrame form field, which will be shown in form Array, required
first_name first_name String, optional
last_name last_name String, optional
email email String, optional
phone</span phone String, optional
address_line1 address_line1 String, optional
address_line2 address_line2 String, optional
address_state address_state String, optional
address_country address_country String, optional
address_city address_city String, optional
address_postcode address_postcode String, optional
account_bank_name account_bank_name available in case when “type” is bank account String, optional
account_bsb account_bsb available in case when “type” is bank account String, optional
account_holder_type account_holder_type available in case when “type” is bank account String, optional
account_routing account_routing available in case when “type” is bank account String, optional
account_type account_type available in case when “type” is bank account String, optional

Styling iFrame form

//for live mode use  'https://widget.paydock.com/remote-action?'
var url = 'https://widget-sandbox.paydock.com/remote-action?';

//  use several tokens for showing several payment source types
addParamToUrl('public_key', 'asdsdafdsglhewurewfjds0');
addParamToUrl('configurationToken', 'dfsdfsdfsdiFRAMECONFIGTOKENfsdfdsfdf');

addParamToUrl('finish_text', 'black');
addParamToUrl('background_color', 'black');
addParamToUrl('border_color', 'black');
addParamToUrl('form_values', 'user_name: John');

addParamToUrl('ref_id', 'testRefernce');

function addParamToUrl (param, value) {
  sandbox_mode_url += param + '=' +encodeURIComponent(value) + '&';
}
<?php
$url = 'https://widget-sandbox.paydock.com/remote-action';

$query = http_build_query([
    'public_key'          => 'public_key',
    'configuration_token' => 'configuration_token',
    'finish_text'         => 'black',
    'background_color'    => 'black',
    'border_color'        => 'black'
    'form_values'        => 'user_name: John'
    //.......
]);

$resultUrl = $url . '?' . $query;

print_r($resultUrl);
?>

Styles for the iFrame can be configured as encoded URL parameters. Examples as follows:

Field Name Description Details
background_color Color of a form background. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, required
text_color Color of a form text. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, required
public_key PayDock users public key String, required
configuration_token Token of iFrame configuration that was created in previous step. Using configuration with 1 payment source type will not show name of iFrame tab. String, required
configuration_tokens Tokens of iFrame configuration that was created in previous step. This parameter is needed only when using several configuration tokens (several payment source types, such as “card” or “bank_account”). Pass value to this parameter, separated by “,”. Each token will be shown in a separate tab inside the Customer iFrame. Values for this parameter generated in step “Create configuration token” (please, see above). In Examples tab, Customer can see how to use several token values. Array, optional
title Title of an iFrame form String, optional
border_color Color of all borders in a form. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, optional
button_color Color of a button in a form. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, optional
error_color Color of message text, when getting error. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, optional
success_color Color of message text, when operation success. Value could be in several types. Example: “black” or “#000000” or “rgb(0,0,0) or rgba(0,0,0,1)” String, optional
finish_text Custom text after successful completion of the operation String, optional
ref_id Custom value for identify result of processed operation String, optional
fields_validation Boolean value in case when it is true will be shown server validation for fields String, optional
supported_card_types Collection of available payment cards. Will be shown list of images above iframe Array, optional
hidden_elements Field for setting names of elements which can be hidden (e.g. ‘submit_button, tabs’) Array, optional
form_values Query string where can be set values and params which can be set as default for fields String, optional

Events sent from iFrame form

"Example of events and data that iframe sends"

  {
    "event": "afterLoad",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "testRef"
  }
  {
    "event": "validationError",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "testRef"
  }
  {
    "event": "submit",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "testRef"
  }
  {
    "event": "finish",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "testRef",
    "payment_source" : "162bfd33-212f-4546-8127-f9596e37d4d1"
  }

Events are fired throughout the lifecycle of the iFrame. Each event includes an “event.data” object containing data about the event. Note: “payment_source” can be configured to be disabled.

The following events are fired:

Event Description
afterLoad immediately after the iFrame has loaded
submit when the form is submitted
validationError when there is an error in the form
finish when all fields are filled correctly and token is created and returned
if (window.addEventListener) {
    window.addEventListener("message", listener);
} else {
    // IE8
    window.attachEvent("onmessage", listener);
}

function listener(event) {
    console.log('message', event.data);
    console.log('message - json parse', JSON.parse(event.data));
    //  event.data is equal to one of the event objects { "event": "finish", "purpose": "payment_source", "message_source": "widget.paydock", "ref_id": "testRef"}

}

"jquery function to get event"

$(window).on('message', listener);

function listener(event) {
    console.log('message', event.data);
    console.log('message - json parse', JSON.parse(event.data));
    //  event.data is equal to one of the event objects { "event": "finish", "purpose": "payment_source", "message_source": "widget.paydock", "ref_id": "testRef"}

}

Get and handle a redirect

By default, the iframe will not include the one-time token on the redirect. It can be configured to send this through the admin inteface or by setting the parameter in the API.

When a request is redirected, it will include “payment_source” in the URL.

Get and handle webhook result

"Example of response of webhook"

{
    "data": {
        "payment_source": "162bfd33-212f-4546-8127-f9596e37d4d1",
        "custom_reference": "testref",
        "configuration_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJ0eXBlIjoiY2FyZCIsImdhdGV3YXlfaWQiOiI1ODEwNDFhYWFmNDZlZGIzMGMxZmE1OTkifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vcGNmYWl4cGMiLCJzdWNjZXNzX3JlZGlyZWN0X3VybCI6IiIsImVycm9yX3JlZGlyZWN0X3VybCI6IiIsImRlZmluZWRfZm9ybV9maWVsZHMiOltdLCJpYXQiOjE0Nzg1MzMzOTJ9.AINNuIWd5of3bPw9V8bcg7xi6vLMsFRdXoqLf7Rjk-A"
    },
    "signature": "c67de0091aae55ebe432309f957f42f39e93beb71f5d38267b4dc521b8db53cf"
}

In result of iFrame process customer will get webhook with “data” object and “signature” value.

The signature can be used to verify the integrity of the data. To check if the data is correct, you will need to:

  1. Make string of Customer data object
  2. Encrypt secret key using ‘SHA-256’ algorithm.
  3. Combine string with Customer data string with encrypted secret key
  4. Encrypt string using ‘SHA-256’ algorithm which Customer get in step 3.
  5. Compare result with signature value from webhook
"Function to encrypt data in JavaScript using CryptoJS library"

var CryptoJS = require("crypto-js");
var secretHash = CryptoJS.SHA256('e38befe37f826fdcc103f44c0e661a4af16b925d').toString(CryptoJS.enc.Hex); // put secret-key
var bodyString = JSON.stringify({"payment_source":"162bfd33-212f-4546-8127-f9596e37d4d1","custom_reference":"testref","configuration_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJ0eXBlIjoiY2FyZCIsImdhdGV3YXlfaWQiOiI1ODEwNDFhYWFmNDZlZGIzMGMxZmE1OTkifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vcGNmYWl4cGMiLCJzdWNjZXNzX3JlZGlyZWN0X3VybCI6IiIsImVycm9yX3JlZGlyZWN0X3VybCI6IiIsImRlZmluZWRfZm9ybV9maWVsZHMiOltdLCJpYXQiOjE0Nzg1MzMzOTJ9.AINNuIWd5of3bPw9V8bcg7xi6vLMsFRdXoqLf7Rjk-A"}); // put data
var hash = CryptoJS.SHA256(bodyString + secretHash).toString(CryptoJS.enc.Hex);

// hash == 'c67de0091aae55ebe432309f957f42f39e93beb71f5d38267b4dc521b8db53cf';
<?php
$userSecretKeyHash = hash('sha256', "e38befe37f826fdcc103f44c0e661a4af16b925d");
$data = json_encode([
    'payment_source'      => '162bfd33-212f-4546-8127-f9596e37d4d1',
    'custom_reference'    => 'testref',
    'configuration_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJ0eXBlIjoiY2FyZCIsImdhdGV3YXlfaWQiOiI1ODEwNDFhYWFmNDZlZGIzMGMxZmE1OTkifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vcGNmYWl4cGMiLCJzdWNjZXNzX3JlZGlyZWN0X3VybCI6IiIsImVycm9yX3JlZGlyZWN0X3VybCI6IiIsImRlZmluZWRfZm9ybV9maWVsZHMiOltdLCJpYXQiOjE0Nzg1MzMzOTJ9.AINNuIWd5of3bPw9V8bcg7xi6vLMsFRdXoqLf7Rjk-A'
]);

$resultString = $data . $userSecretKeyHash;

$resultHash = hash('sha256', $resultString);

print_r($resultHash);
// $resultHash = 'c67de0091aae55ebe432309f957f42f39e93beb71f5d38267b4dc521b8db53cf'
?>

Other Resources

Required Fields by Gateway

Different gateways require different fields, see detailed listing below

Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 required
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month optional
expire_year optional
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name optional
account_bsb required
account_number required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional