NAV Navbar
Logo.paydock
shell JavaScript PHP Java C#

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.

Sign up for a sandbox account by contacting PayDock here. This will give you access to the admin portal.

If you do not already have services to connect, you can usually sign up for test accounts. You can see a list of some of the services we support here.

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 Company --> 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

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 Request type
200 Call successful Appears on success request any
201 Created successfully Appears on success request while creating new resource POST
400 Merchant data error There is also an error code in response. Check the "error_summary" section for the details. any
403 Permission denied Authorization token does not have permission any
404 Resource not found The requested resource by id is not found for your visibility scope any
500 System error Unexpected server error any
408 API unavailable Only for .Net SDK. The response from the .Net SDK when it can't reach the API for some time any

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


"Gateway processing error"

"error_summary": {
        "message": "Transaction Declined",
        "code": "transaction_declined",
        "status_code": "05",
        "status_code_description": "Do not honour",
        "details": {
            "gateway_specific_code": "DECLINED",
            "gateway_specific_description": "The requested operation was not successful",
            "messages": [
                "Transaction Declined"
            ]
        }
    }

http code

Cause

Error Code

Error Structure

400

Internal validation

  • validation_error

  • required_error

  • unfulfilled_condition

{
message: string,
code: string,
details: {
path?: string,
messages: string[]
} }

400

gateway validation

  • gateway_error

  • insufficient_funds

  • credit_card_invalid_or_expired

  • transaction_declined

  • transaction_declined_hard

  • system_error

  • fraud_warning

  • invalid_transaction_details

  • invalid_request_details

  • invalid_bank_account_details

  • invalid_gateway_credentials

  • unknown

{
message: string,
code: string,
details: {
path?: string,
gateway_specific_code: string,
gateway_specific_description: string
messages: string[]
} }

400

gateway proccesing

  • gateway_error

  • insufficient_funds

  • credit_card_invalid_or_expired

  • transaction_declined

  • transaction_declined_hard

  • system_error

  • fraud_warning

  • invalid_transaction_details

  • invalid_request_details

  • invalid_bank_account_details

  • invalid_gateway_credentials

  • unknown

{ message: string,
code: string,
status_code: string,
status_code_description: string,
details: {
path?: string,
gateway_specific_code: string,
gateway_specific_description: string
messages: string[]
} }

400 - 599

other

  • unspecified_error

  • *

{
message: string,
code: string,
details: {
messages: string[]
} }

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": "Fuga consequuntur sint ab magnam",
      "first_name": "Natalie",
      "last_name": "Foster",
      "email": "nwashington@gmail.com",
      "_id": "5887e30c28e281756b883f63",
      "payment_sources": [
        {
          "updated_at": "2017-01-24T23:28:14.045Z",
          "vault_token": "dd634c0c-ea3b-4d82-b7fb-5ef2d2949ff6",
          "gateway_id": "58377235377aea03343240cc",
          "card_name": "Natalie Foster",
          "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).

Access tokens

With the help of access tokens, you can grant your PayDock integration particular permissions based on your needs. An access token can be used as a header for making API requests instead of public and secret API keys. You can create an unlimited number of access tokens with various permissions and a configurable expiry.

field required type description
label - string Name of the access token to identify it further
expiration_in - number (seconds) Time period in seconds after which the access token will expire
permissions + string Actions the user will be able to perform with the access token

Here is how it looks in the dashboard when you click ‘Create New’: Access token create

You can generate an external access token in your PayDock dashboard if your role has the corresponding privileges. You can give only those permissions to this token which are enabled for your role.

You can set permissions for individual endpoints. For example, instead of granting all charge-related permissions (creating, modifying, searching, getting by ID, archiving, etc.), you can choose only specific ones. As a result, your token could be used only for searching charges but not for creating them.

You can deactivate an access token at any time. It can be useful for cases when you delegate some work on integration to third-party developers. Once the work is done, you can deactivate the token without worrying that it can be used for some unauthorized actions. Access token deactivate

The usage of an access token can be tracked as well. You can view the statistics in the Profile menu -> ‘Audit’ in the dashboard.

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://widget.paydock.com/sdk/latest/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.

Visit PayDock Postman documentation page:

Visit API Reference

 

Or visit PayDock Master Merchant (Brand) documentation:

Visit API Reference

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.

Client-sdk

It is a solution for collecting and handling payment sources in secure way.

With SDK you can create a payment form widget as an independent part or insert use inside your form.

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 public_key or access_token (see Authentication)

Also you will need added gateway (see API Reference by gateway)

Get started

Download from CDN

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

You should begin by including the library in your page.

Add this script tag to your page to get started with with the url below:

Compressed version for production https://widget.paydock.com/sdk/latest/widget.umd.min.js

Full version for development and debug https://widget.paydock.com/sdk/latest/widget.umd.js

Also can download library the production version or the development version

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

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

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 @paydock/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

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, you can customize the fields and set 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');
widget.load();
// ES2015 | TypeScript

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

var widget = new HtmlWidget('#widget', 'publicKey');
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://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var widget = new paydock.HtmlWidget('#widget', 'publicKey');
        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://widget.paydock.com/sdk/latest/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.onFinishInsert('input[name="payment_source_token"]', 'payment_source');z

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

Payment sources widget

You can find description of all methods and parameters here

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/payment-source-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://widget.paydock.com/sdk/latest/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://widget.paydock.com/sdk/latest/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 PayPal meta parameters description here Zipmoney meta parameters description here

This widget allows you to turn your button into a full 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.PaypalCheckoutButton('#button', 'publicKey', 'gatewayId');
// ES2015 | TypeScript


var button = new PaypalCheckoutButton('#button', 'publicKey');

Then write only need 1 line 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://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
    <script>
        var button = new paydock.PaypalCheckoutButton('#button', 'publicKey');
    </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 id="paymentForm">
    <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>
</form>

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

<script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
<script>
    var button = new paydock.PaypalCheckoutButton('#button', 'publicKey', 'gatewayId');
    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.setMeta({
           brand_name: 'Paydock',
           reference: '15',
           first_name: 'Joshua',
           last_name: 'Wood',
           phone: '0231049872'});

    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 id="paymentForm">
    <button type="button" id="button">
        <img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTVrrEYxDmq4WXv7hfHygKD9ltnOqv0K6soSAhmbKNllPNYWiLiJA" align="left" style="margin-right:7px;">
    </button>
</form>

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

<script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
<script>
    var button = new paydock.ZipmoneyCheckoutButton('#button', 'publicKey', 'gatewayId');
    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.setMeta("first_name": "Joshua",
       "tokenize": true,
       "last_name": "Wood",
       "email":"joshuawood@hotmail.com.au",
       "gender": "male",
       "charge": {
           "amount": "4",
           "currency":"AUD",
           "shipping_type": "delivery",
           "shipping_address": {
               "first_name": "Joshua",
               "last_name": "Wood",
               "line1": "Suite 660",
               "line2": "822 Ruiz Square",
               "country": "AU",
               "postcode": "3223",
               "city": "Sydney",
               "state": "LA"
           },
           "billing_address": {
               "first_name": "Joshua",
               "last_name": "Wood",
               "line1": "Suite 660",
               "line2": "test",
               "country": "AU",
               "postcode": "3223",
               "city": "Sydney",
               "state": "LA"
           },
           "items": [
               {
                   "name":"ACME Toolbox",
                   "amount":"2",
                   "quantity": 1,
                   "reference":"Fuga consequuntur sint ab magnam"
               },
               {
                   "name":"Device 42",
                   "amount":"2",
                   "quantity": 1,
                   "reference":"Fuga consequuntur sint ab magnam"
               }
           ]
       },

       "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>

Full Aftepay example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<button type="button" id="button">
    <img src="https://daepxvbfwwgd0.cloudfront.net/assets/logo_scroll-0c43312c5845a0dcd7a3373325da6402bc1d635d3415af28ed40d6c1b48e3d5c.png" align="left" style="margin-right:7px;">
</button>

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

<script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
<script>
    var button = new paydock.AfterpayCheckoutButton('#button', 'publicKey', 'gatewayId');

    button.onFinishInsert('input[name="pst"]', 'payment_source_token');
    button.showEnhancedTrackingProtectionPopup(true);
    button.setMeta({
        amount: "100",
        currency: "AUD",
        reference: 'Vitae commodi provident assumenda',
        email: 'wanda.mertz@example.com',
        first_name: 'Wanda',
        last_name: 'Mertz',
        address_line: '61426 Osvaldo Plains',
        address_line2: 'Apt. 276',
        address_city: 'Lake Robyn',
        address_state: 'WY',
        address_postcode: '07396',
        address_country: 'Australia',
        phone: '0412345678',
    });

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

Api

You can find description of all methods and parameters here

This wrapper helps you to work with paydock api emdpoints

Get browser details

var browserDetails = await new paydock.Api('publicKey').setEnv('env').getBrowserDetails();
// ES2015 | TypeScript

import { Api } from '@paydock/client-sdk/api';

var browserDetails = await new paydock.Api('publicKey').setEnv('env').getBrowserDetails();

Initialization

var response = await new paydock.Api('publicKey').setEnv('env').charge().preAuth({
      amount: 100,
      currency: 'AUD',
      token: 'token',
    });
// ES2015 | TypeScript

import { Api } from '@paydock/client-sdk/api';

var response = await new Api('publicKey').setEnv('env').charge().preAuth({
      amount: 100,
      currency: 'AUD',
      token: 'token',
    });

Then write only need 2 lines of code in js to make request

Initialization full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style></style>
</head>
<body>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
         (async function() {
            var response = await new Api('publicKey').setEnv('env').charge().preAuth({
                amount: 100,
                currency: 'AUD',
                token: 'token',
            });
        })();
    </script>
</body>
</html>

Canvas3ds

You can find description of all methods and parameters here

This widget provides you to integrate 3d Secure

Canvas3ds 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 canvas3ds = new paydock.Canvas3ds('#widget', 'token');
canvas3ds.load();
// ES2015 | TypeScript

import { Canvas3ds } from '@paydock/client-sdk/canvas3ds';

var list = new Canvas3ds('#widget', 'token');
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="widget"></div>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
    <script>
        var canvas3ds = new paydock.Canvas3ds('#widget', 'token');
        canvas3ds.load();
    </script>
</body>
</html>

Canvas3ds advanced example

Settings


canvas3ds.setEnv('sandbox'); // set enviroment

canvas3ds.hide(); // hide widget

canvas3ds.show(); // show widget

canvas3ds.on('chargeAuthSuccess', function (data) {
  console.log(data);
});
canvas3ds.on('chargeAuthReject', function (data) {
  console.log(data);
});
canvas3ds.on('chargeAuthCancelled', function (data) {
  console.log(data);
});
canvas3ds.on('additionalDataCollectSuccess', function (data) {
  console.log(data);
});
canvas3ds.on('additionalDataCollectReject', function (data) {
  console.log(data);
});
canvas3ds.on('chargeAuth', 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: 450px;}</style>
</head>
<body>
    <div id="widget3ds"></div>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
    <script>
        var canvas3ds = new paydock.Canvas3ds('#widget3ds', 'token');
        canvas3ds.on('chargeAuthSuccess', function (data) {
            console.log('chargeAuthSuccess', data);
        });
        canvas3ds.on('chargeAuthReject', function (data) {
            console.log('chargeAuthReject', data);
        });
        canvas3ds.load();
    </script>
</body>
</html>

Full example with pre authorization

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 40%;height: 450px;}</style>
</head>
<body>
    <div id="widget"></div>
    <div id="widget3ds"></div>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
    <script>
        (async function () {
            var htmlWidget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
            htmlWidget.load();
            var {payment_source} = await htmlWidget.on('finish');
            var preAuthResp = await new paydock.Api('publicKey').setEnv('sandbox').charge().preAuth({
                  amount: 100,
                  currency: 'AUD',
                  token: payment_source,
                });
            var canvas = new paydock.Canvas3ds('#widget3ds', preAuthResp._3ds.token);
            canvas.load();
            var chargeAuthEvent = await canvas.on('chargeAuth');
            console.log('chargeAuthEvent', chargeAuthEvent);
        })()
    </script>
</body>
</html>

Canvas 3ds for Standalone 3ds charges

After you initialized the standalone 3ds charge via v1/charges/standalone-3ds API endpoint, you get a token used to initialize the Canvas3ds. All above information regarding setup, loading and initialization still apply.

Full example

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Title</title>
        <style>
            iframe {
                border: 0;
                width: 40%;
                height: 450px;
            }
        </style>
    </head>
    <body>
        <div id="widget3ds"></div>
        <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
        <script>
            var canvas3ds = new paydock.Canvas3ds("#widget3ds", "token");
            canvas3ds.on("chargeAuthSuccess", function (data) {
                console.log(data);
            });
            canvas3ds.on("chargeAuthReject", function (data) {
                console.log(data);
            });
            canvas3ds.on("chargeAuthChallenge", function (data) {
                console.log(data);
            });
            canvas3ds.on("chargeAuthDecoupled", function (data) {
                console.log(data.result.description);
            });
            canvas3ds.on("chargeAuthInfo", function (data) {
                console.log(data.info);
            });
            canvas3ds.on("error", function ({ charge_3ds_id, error }) {
                console.log(error);
            });
            canvas3ds.load();
        </script>
    </body>
</html>

Events and Values

Event Value Type Description
chargeAuthSuccess object Instance of ChargeEventResponse
chargeAuthReject object Instance of ChargeEventResponse
chargeAuthChallenge object Instance of ChargeEventResponse
chargeAuthDecoupled object Instance of ChargeEventResponse
chargeAuthInfo object Instance of ChargeEventResponse
error object Instance of chargeError

Response Values

ChargeEventResponse

Param Type Description
status string status for the event transaction
charge_3ds_id string Universal unique transaction identifier to identify the transaction
info string info field for chargeAuthInfo event
result.description string [Optional] field that you must show to the customer, indicating the method the user must use to authenticate during the decoupled challenge flow.

ChargeError

Param Type Description
error object error response
charge_3ds_id string Universal unique transaction identifier to identify the transaction

Vault Display Widget

You can find description of all methods and parameters here

The vault display form allows viewing card number and CVV. The form can be customised according to your needs. You can set styles as well as subscribe to widget events that help monitor user’s actions in real time.

Vault Display 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.VaultDisplayWidget('#widget', 'token');
widget.load();
// ES2015 | TypeScript

import { VaultDisplayWidget } from '@paydock/client-sdk/vault-display-widget';

var widget = new VaultDisplayWidget('#widget', 'token');
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>

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

    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var widget = new paydock.VaultDisplayWidget('#widget', 'token');
        widget.load();
    </script>
</body>
</html>

Widget advanced example

Customization

widget.setEnv('sandbox');

widget.on('after_load', function (data) {
  console.log(data);
});

widget.on('cvv_secure_code_requested', function (data) {
  console.log(data);
});

widget.on('card_number_secure_code_requested', function (data) {
  console.log(data);
});

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 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: 450px;}</style>
</head>
<body>

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

    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var widget = new paydock.VaultDisplayWidget('#widget', 'token');

        widget.setEnv('sandbox');

        widget.on('after_load', function (data) {
          console.log(data);
        });

        widget.on('cvv_secure_code_requested', function (data) {
          console.log(data);
        });

        widget.on('card_number_secure_code_requested', function (data) {
          console.log(data);
        });

        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'
        });

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

Wallet Buttons

You can find description of all methods and parameters here

Wallet Buttons allow you to easily integrate different E-Wallets into your checkout. Currently supports ApplePay, Google Pay, Google Pay and Apple Pay via Stripe, Flypay checkout, Paypal Smart Buttons Checkout and Afterpay.

If available in your client environment, you will display a simple button that upon clicking it the user will follow the standard flow for the appropriate Wallet. If not available an event will be raised and no button will be displayed.

Wallet Buttons simple example

Container

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

You must create a container for the Wallet Buttons. Inside this tag, the button will be initialized.

Before initializing the button, you must perform a POST request to charges/wallet from a secure environment like your server. This call will return a token that is required to load the button and securely complete the payment. You can find the documentation to this call in the PayDock API documentation.

Initialization

The following is the minimum required initialization parameters for Apple Pay and Google Pay via Stripe: javascript let button = new paydock.WalletButtons( "#widget", token, { amount_label: "Total", country: "DE", } ); button.load();

// ES2015 | TypeScript
import { WalletButtons } from '@paydock/client-sdk';

var button = new WalletButtons(
    '#widget',
    token,
    {
        amount_label: 'Total',
        country: 'DE',
    }
);
button.load();

Flypay and Paypal wallets do not require any meta sent to the wallet, so the following is enough for initialization: javascript let button = new paydock.WalletButtons( "#widget", token, {} ); button.load();

// ES2015 | TypeScript
import { WalletButtons } from '@paydock/client-sdk';

var button = new WalletButtons(
    '#widget',
    token,
    {}
);
button.load();

For Afterpay wallet, the country code is required: javascript let button = new paydock.WalletButtons( "#widget", token, { country: "AU", } ); button.load();

// ES2015 | TypeScript
import { WalletButtons } from '@paydock/client-sdk';

var button = new WalletButtons(
    '#widget',
    token,
    {
        country: 'AU',
    }
);
button.load();

Setting environment

Current method can change environment. By default environment = sandbox. Bear in mind that you must set an environment before calling button.load().

button.setEnv('sandbox');

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
        let button = new paydock.WalletButtons(
            "#widget",
            token,
            {
                amount_label: "Total",
                country: "DE",
            }
        );
        button.load();
</script>
</html>

Wallet Buttons advanced example

Checking for button availability

If the customer's browser is not supported, or the customer does not have any card added to their Google Pay or Apple Pay wallets, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.

button.onUnavailable(() => console.log("No wallet buttons available"));

Forcibly closing the checkout

In some situations you may want to forcibly close the checkout so that your user is back in your checkout screen, fow which you can use this method. Currently supported by Flypay wallet only.

button.close();

Performing actions when shipping info is updated

In Flypay, Paypal and ApplePay via MPGS integrations after each shipping info update the onUpdate(data) will be called with the selected shipping address information (plus selected shipping method for Paypal). Merchants should handle this callback, recalculate shipping costs in their server by analyzing the new data, and submit a backend to backend request to POST charges/:id with the new total amount and shipping amount (you can find the documentation of this call in the PayDock API documentation).

For Paypal integration specifically, if shipping is enabled for the wallet button and different shipping methods were provided in the create wallet charge call, Merchants must ensure that the posted shipping.amount to POST charges/:id matches the selected shipping option amount (value sent in when initializing the wallet charge). In other words, when providing shipping methods the shipping amount is bound to being one of the provided shipping method amount necessarily. Bear in mind that the total charge amount must include the shipping.amount, since it represents the full amount to be charged to the customer.

After analyzing the new shipping information, and making the post with the updated charge and shipping amounts if necessary, the button.update({ success: true/false }) wallet button method needs to be called to resume the interactions with the customer. Not calling this will result in unexpected behavior.

button.onUpdate((data) => {
    console.log("Updating amount via a backend to backend call to POST charges/:id");
    // call `POST charges/:id` to modify charge
    button.update({ success: true });
});

For ApplePay via MPGS integration specifically, you must return the new amount and new shipping_options If new options are needed based on the updated shipping data. Before the user authorizes the transaction with Touch ID, Face ID, or passcode, you receive redacted address information (address_country, address_city, address_state, address_postcode), this data can be used to recalculate the amount and new shipping options. (https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypayment/1916097-shippingcontact)

button.onUpdate((data) => {
    console.log("Updating amount via a backend to backend call to POST charges/:id");
    // call `POST charges/:id` to modify charge
    button.update({
        success: true,
        body: {
            amount: 15,
            shipping_options: [
                {
                    id: "NEW-FreeShip",
                    label: "NEW - Free Shipping",
                    detail: "Arrives in 3 to 5 days",
                    amount: "0.00"
                },
                {
                    id: "NEW - FastShip",
                    label: "NEW - Fast Shipping",
                    detail: "Arrives in less than 1 day",
                    amount: "10.00"
                }
            ]
        }
    });
});

Performing actions after the payment is completed

After the payment is completed, the onPaymentSuccessful(data) will be called if the payment was successful. If the payment was not successful, the function onPaymentError(data) will be called. If fraud check is active for the gateway, a fraud body was sent in the wallet charge initialize call and the fraud service left the charge in review, then the onPaymentInReview(data) will be called. All three callbacks return relevant data according to each one of the scenarios.

Note that these callbacks will not trigger for Afterpay wallet since the payment completion for it is done via Redirect method, and therefore this SDK won't be loaded once the payment is completed at checkout.

button.onPaymentSuccessful((data) => console.log("The payment was successful"));
button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
button.onPaymentError((data) => console.log("The payment was not successful"));

Events

The above events can be used in a more generic way via de on function, and making use of the corresponding event names.

button.on(EVENT.UNAVAILABLE, () => console.log("No wallet buttons available"));
button.on(EVENT.UPDATE, (data) => console.log("Updating amount via a backend to backend call to POST charges/:id");
button.on(EVENT.PAYMENT_SUCCESSFUL, (data) => console.log("The payment was successful"));
button.on(EVENT.PAYMENT_ERROR, (data) => console.log("The payment was not successful"));

This example shows how to use these functions for Apple and Google Pay via Stripe: (Required meta fields: amount_label, country. Optional meta fields: wallets)

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
    let button = new paydock.WalletButtons(
        "#widget",
        charge_token,
        {
            amount_label: "Total",
            country: "DE",
            wallets: ["google", "apple"],
        }
    );
    button.setEnv('sandbox');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
    button.load();
</script>
</html>

This example shows how to use these functions for Paypal Smart Checkout Buttons: (Required meta fields: - . Optional meta fields: request_shipping, pay_later, style)

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
    let button = new paydock.WalletButtons(
        "#widget",
        charge_token,
        {
            request_shipping: true,
            pay_later: true,
            style: {
                layout: 'horizontal',
                color: 'blue',
                shape: 'rect',
                label: 'paypal',
            },
        }
    );
    button.setEnv('sandbox');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onUpdate((data) => {
        console.log("Updating amount via a backend to backend call to POST charges/:id");
        // call `POST charges/:id` to modify charge
        button.update({ success: true });
    });
    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
    button.load();
</script>
</html>

This example shows how to use these functions for Flypay Checkout. (Required meta fields: - . Optional meta fields: request_shipping, pay_later, style)

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
    let button = new paydock.WalletButtons(
        "#widget",
        charge_token,
        {
            request_shipping: true
        }
    );
    button.setEnv('sandbox');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onUpdate((data) => {
        console.log("Updating amount via a backend to backend call to POST charges/:id");
        // call `POST charges/:id` to modify charge
        button.update({ success: true });
    });
    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
    button.load();
</script>
</html>

This example shows how to use these functions for ApplePay via MPGS: (Required meta fields: amount_label, country. Optional meta fields: raw_data_initialization, request_shipping, style.button_type)

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
    let button = new paydock.WalletButtons(
        "#widget",
        charge_token,
        {
            amount_label: "Total",
            country: 'DE',
            request_shipping: true,
            style: {
                button_type: 'buy',
            },
            shipping_options: [
                {
                    id: "FreeShip",
                    label: "Free Shipping",
                    detail: "Arrives in 5 to 7 days",
                    amount: "0.00"
                },
                {
                    id: "FastShip",
                    label: "Fast Shipping",
                    detail: "Arrives in 1 day",
                    amount: "10.00"
                }
            ]
        }
    );
    button.setEnv('sandbox');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.load();
</script>
</html>

Also, for ApplePay via MPGS you can initialize the ApplePayPaymentRequest with your own values instead of using the default ones. Below you can see an example on how to initialize the ApplePayPaymentRequest with the raw_data_initialization meta field:

Raw data initialization example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h2>Payment using PayDock Wallet Button!</h2>
    <div id="widget"></div>
</body>
<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
<script>
    let button = new paydock.WalletButtons(
        "#widget",
        charge_token,
        {
            raw_data_initialization: {
                countryCode: "AU",
                currencyCode: "AUD",
                merchantCapabilities: ["supports3DS","supportsCredit","supportsDebit"],
                supportedNetworks: ["visa","masterCard","amex","discover"],
                requiredBillingContactFields: ["name","postalAddress"],
                requiredShippingContactFields:["postalAddress","name","phone","email" ],
                total: {
                    label: "Total",
                    amount: "10",
                    type: "final",
                }
            },
            amount_label: "Total",
            country: 'DE',
            request_shipping: true,
            style: {
                button_type: 'buy',
            },
            shipping_options: [
                {
                    id: "FreeShip",
                    label: "Free Shipping",
                    detail: "Arrives in 5 to 7 days",
                    amount: "0.00"
                },
                {
                    id: "FastShip",
                    label: "Fast Shipping",
                    detail: "Arrives in 1 day",
                    amount: "10.00"
                }
            ]
        }
    );
    button.setEnv('sandbox');
    button.onUnavailable(() => console.log("No wallet buttons available"));
    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
    button.onPaymentError((data) => console.log("The payment was not successful"));
    button.load();
</script>
</html>

Secure Remote Commerce

You can find description of all methods and parameters here.

This widget provides you with the ability to easily integrate with SRC providers. Currently Visa SRC is supported.

SRC simple example

Container

<div id="checkoutButton"></div>
<div id="checkoutIframe"></div>

You must create a container for the initial checkout button, and a different one for the checkout iFrame. Inside the first tag the button will be initialized, and inside the second one the iFrame will be loaded once the button is clicked.

Initialization

var src = new paydock.SRC(
    "#checkoutButton",
    "#checkoutIframe",
    "scheme_service_id",
    "paydock_public_key_or_access_token",
    {}, // meta
);
src.load();
// ES2015 | TypeScript

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

var src = new SRC(
    "#checkoutButton",
    "#checkoutIframe",
    "scheme_service_id",
    "paydock_public_key_or_access_token",
    {}, // meta
);
src.load();

NOTE: it's highly recommended to use a Paydock Access Token instead of the public key for security reasons. When creating it, you will need to enable the Secure Remote Commerce and add a whiteliste for the domain of your checkout screen.

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="checkoutButton"></div>
    <div id="checkoutIframe"></div>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var src = new paydock.SRC(
            "#checkoutButton",
            "#checkoutIframe",
            "scheme_service_id",
            "paydock_public_key_or_access_token",
            {},
        );
        src.load();
    </script>
</body>
</html>

SRC advanced example

Settings


src.setEnv('sandbox'); // set enviroment

src.hideButton(); // hide button

src.showButton(); // show button

src.hideCheckout(); // hide checkout iframe

src.showCheckout(); // show checkout iframe

src.on('checkoutButtonLoaded', () => {
    console.log("Button loaded");
});

src.on('checkoutButtonClicked', () => {
    console.log("Button clicked");
});

src.on('iframeLoaded', () => {
    console.log("Initial iframe loaded");
});

src.on('checkoutReady', () => {
    console.log("Checkout ready to be used");
});

src.on('checkoutCompleted', (token) => {
    console.log(token);
});

src.on('checkoutError', (error) => {
    console.log(error);
});

Here you can see how you can use this methods to customize your checkout experience

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 40%;height: 450px;}</style>
</head>
<body>
    <div id="checkoutButton"></div>
    <div id="checkoutIframe"></div>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var src = new paydock.SRC(
            "#checkoutButton",
            "#checkoutIframe",
            "scheme_service_id",
            "paydock_public_key_or_access_token",
            {},
        );

        src.on('checkoutReady', () => {
            console.log("Checkout ready to be used");
        });

        src.on('checkoutCompleted', (token) => {
            console.log(token);
        });
        src.load();
    </script>
</body>
</html>

Customization options for address fields

Shipping address:

To customize shipping address experience we use a flag that manages how VisaSRC requires or not shipping address to the customer. Options are NONE (default option), POSTAL_COUNTRY or ALL.

var src = new paydock.SRC(
    "#checkoutButton",
    "#checkoutIframe",
    "scheme_service_id",
    "paydock_public_key_or_access_token",
    {
        "dpa_transaction_options": {
            "dpa_shipping_preference": "ALL"
        }
    },
);

With this the Visa popup requires the shipping address from consumer, and these information will be stored in the Paydock charge.

Another option is at time of creating the charge. Say that you have a different way of collecting the shipping address (outside Paydock checkout), you can then disable the shipping address on our SRC widget and send it when creating the charge creation after getting the One Time Token out of the SRC widget:

POST v1/charges

{
    "amount": "10.00",
    "currency": "AUD",
    "token": "token",
    "customer": {
        "payment_source": {
            "gateway_id": "gateway_id"
        }
    },
    "shipping": {
        "address_line1": "address_line1",
        "address_line2": "address_line2",
        "address_line3": "address_line3",
        "address_city": "address_city",
        "address_postcode": "address_postcode",
        "address_state": "address_state",
        "address_country": "address_country"
    }
}

Billing address fields are always present on the checkout and required when adding a new credit card (or for new consumer checkout). You can send billing fields on the meta data to pre-fill these fields inside the customer object:

var src = new paydock.SRC(
    "#checkoutButton",
    "#checkoutIframe",
    "scheme_service_id",
    "paydock_public_key_or_access_token",
    {
        "customer": {
            "email": "test@email.com",
            "first_name": "Name",
            "last_name": "Surname",
            "phone": {
                "country_code": "1",
                "phone": "2124567890"
            },
            "payment_source": {
                "address_line1": "Line 1",
                "address_line2": "Line 2",
                "address_city": "Miami",
                "address_postcode": "33126",
                "address_state": "FL",
                "address_country": "US"
            }
        }
    },
);

Personalization Styling

To improve the experience in the use of the widget, it is allowed to send props that customize the UI.

Example code

var src = new paydock.SRC(
    "#checkoutButton",
    "#checkoutIframe",
    "scheme_service_id",
    "paydock_public_key",
);

button.setStyles({"primary_color":"#a83232","button_text_color":"#171e9c","font_family":"sans-serif"})

Event and Values

Event Value Type Description
primary_color string HEX color for the principal buttons, example : #32a852
button_text_color string HEX color for the text of the buttons, example : #32a852
font_family string Look more mozilla.org/color
card_schemes [string] - array of string Possible values "visa", "mastercard", "amex" and "discover" - Default show all logos

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

PayPal Smart Button Integration

PayPal Checkout with Smart Payment Buttons gives your merchants a simplified and secure checkout experience. PayPal intelligently presents the most relevant payment types to your shoppers, automatically, making it easier for them to complete their purchase using credit card payments. Also, you can enable the Pay in 4 feature at PayPal Checkout. In this case, you can split your purchase into 4 payments, with the down payment due at the time of transaction and 3 subsequent payments made every 2 weeks thereafter.

Add PayPal Gateway

First, you must connect to the PayPal gateway at Paydock. Please refer to our PayPal integration guide. After adding a gateway, you can use the PayPal Smart Button. This allows customers to log into PayPal during each checkout and select the shipping address and credit card or other payment method they wish to use. The Paypal Smart Button can be added to the website via the Client SDK package.

How the PayPal Smart Button works

Below is a step-by-step flow of the charge made via the PayPal Smart button: 1. Create a wallet token to utilize it in Client SDK using the {{url}}/v1/charges/wallet endpoint. 2. Use our Client SDK to create a payment form with the checkout button that redirects a client to an external PayPal checkout process. 3. After clicking the PayPal Smart Payment button, the client logs into their PayPal account. 4. As soon as the client is logged into the account, the PayPal Checkout page is rendered into PayPal SDK with a summary of the charge information and a PayPal Smart Button. 5. It is possible to modify the amount and shipping_amount parameters using the {{url}}/v1/charges/:id endpoint. These parameters can be updated if they were modified during the checkout. 6. After clicking the Pay Now button, a Successful/Failed payment message is sent to the client's side. 7. Finally, the PayPal popup is closed.

Add the PayPal Smart Button

The PayPal Smart Button can be added to the merchant's website via the Client SDK package. You can find more information about how to integrate this button into your website in the wallet-buttons-examples section of the package’s readme.

Apple Pay Integration

Apple Pay is a digital wallet service by Apple Inc. that allows merchants to make payments in person, in iOS apps, and on the web using Safari. This feature is supported by the iPhone, Apple Watch, iPad, and Mac.

Add Apple Pay & MasterCard Gateway

  1. It is needed to create an Apple developer account using this link. After the account is successfully created, you should set up a Merchant ID, Merchant Domain, Payment Processing Certificate (used for the encryption process) and Merchant Identity Certificate (used to authenticate the communication with Apple Pay servers). More information about this can be found using these links: Configuring Your Environment Configure Apple Pay on the web
  2. The next step is connecting the MasterCard gateway at Paydock. You can refer to our MasterCard integration guide.
  3. After the setup at Paydock is configured, upload the Apple Payment Processing Certificate to the MPGS Merchant Administration dashboard by going to Admin > Device Payments > Add New Certificate. Note: For Apple Pay to work correctly, it is needed to select the ‘Enable Wallet Payments’ checkbox for the MasterCard service at Paydock’s dashboard.

Apple Pay (MPGS) Checkout Flow

Below is a step-by-step flow of the Apple Pay checkout button:

  1. Create a wallet token to utilize it in Client SDK using the {{url}}/v1/charges/wallet endpoint.
  2. Use our Client SDK to create a payment form with the checkout button that displays the Apple Pay payment sheet to your customers.
  3. After clicking the Apple Pay button, the Apple Payment Sheet is displayed.
  4. The customer can update Credit Card and Billing information and confirm the payment.
  5. Finally, the Apple Pay sheet is closed.

Add the Apple Pay Checkout Button

The Apple Pay button can be added to the website via the Client SDK package. You can find information on how this can be integrated into your website here in the 'wallet-buttons-examples' section.

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\”: \”samwashington@gmail.com\”,  \”first_name\”: \”Samantha\”, \”last_name\”: \”Washington\”, \”address_line1\”: \”Suite 660\”, \”address_line2\”: \”822 Ruiz Square\”,  \”address_city\”: \”Lake Edward\”, \”address_state\”: \”NSW\”, \”address_postcode\”: \“1234\”,  \”address_country\”: \”Australia\”,  \”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": "Vitae commodi provident assumenda",
                "email": "samwashington@gmail.com",
                "first_name": "Samantha",
                "last_name": "Washington",
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Lake Edward",
                "address_state": "NSW",
                "address_postcode": "1234",
                "address_country": "Australia",
                "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' => 'Vitae commodi provident assumenda',
    'email' => 'samwashington@gmail.com',
    'first_name' => 'Samantha',
    'last_name' => 'Washington',
    'address_line1' => 'Suite 660',
    'address_line2' => '822 Ruiz Square',
    'address_city' => 'Lake Edward',
    'address_state' => 'NSW',
    'address_postcode' => '1234',
    'address_country' => 'Australia',
    '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\": \"Samantha\",\"last_name\": \"Washington\",\"tokenize\": true,\"shipping_address\": { \"first_name\": \"Samantha\", \"last_name\": \"Washington\", \"line1\": \"Suite 660\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" }, \"billing_address\": { \"first_name\": \"Samantha\", \"last_name\": \"Washington\", \"line1\": \"Suite 660\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" },\"amount\": \"4\", \"currency\":\"AUD\",\"reference\":\"transaction_reference\",\"email\":\"curtischarles@diaz-brown.net.au\",\"items\": [{\"name\":\"ACME Tollbox\",\"amount\":\"2\",\"quantity\": 1,\"reference\":\"sds\"},{\"name\":\"Device 42\",\"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\": \"Vitae commodi provident assumenda\"}"
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": "Samantha",
                "last_name": "Washington",
                "email":"curtischarles@diaz-brown.net.au",
                "tokenize": true,
                 "description": "Vitae commodi provident assumenda",
                "charge": {
                    "shipping_address": {
                        "first_name": "Samantha",
                        "last_name": "Washington",
                        "line1": "Suite 660",
                        "country": "AU",
                        "postcode": "2000",
                        "city": "Sydney",
                        "state": "NSW"
                    },
                    "billing_address": {
                        "first_name": "Samantha",
                        "last_name": "Washington",
                        "line1": "Suite 660",
                        "country": "AU",
                        "postcode": "2000",
                        "city": "Sydney",
                        "state": "NSW"
                    },
                    "amount": "4",
                    "currency":"AUD",            
                    "items": [{
                        "name":"ACME Toolbox",
                        "amount":"2",
                        "quantity": 1,
                        "reference":"Fuga consequuntur sint ab magnam"
                    },
                    {
                        "name":"Device 42",
                        "amount":"2",
                        "quantity": 1,
                        "reference":"Fuga consequuntur sint ab magnam"
                    }],
                },
                "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"=> "Samantha",
    "last_name"=> "Washington",
    "email"=>"curtischarles@diaz-brown.net.au",
    "tokenize"=> true,
    "description"=> "Vitae commodi provident assumenda",
    "charge"=> [
        "shipping_address"=> [
            "first_name"=> "Samantha",
            "last_name"=> "Washington",
            "line1"=> "Suite 660",
            "country"=> "AU",
            "postcode"=> "2000",
            "city"=> "Sydney",
            "state"=> "NSW"
        ],
        "billing_address"=> [
            "first_name"=> "Samantha",
            "last_name"=> "Washington",
            "line1"=> "Suite 660",
            "country"=> "AU",
            "postcode"=> "2000",
            "city"=> "Sydney",
            "state"=> "NSW"
        ],
        "amount"=> "4",
        "currency"=>"AUD",
        "items"=> [[
            "name"=>"ACME Tollbox",
            "amount"=>"2",
            "quantity"=> 1,
            "reference"=>"Fuga consequuntur sint ab magnam"
        ],
        [
            "name"=>"Device 42",
            "amount"=>"2",
            "quantity"=> 1,
            "reference"=>"Fuga consequuntur sint ab magnam"
        ]],
    ],
    "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: "houston@domain.com"},
    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: "houston@domain.com"},
    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

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

Fraud detection service

Available only if configured for your account. PayDock Fraud detection API has an ability to operate in 'active' mode where PayDock will: Collect and report but also take the following actions

Or in ‘passive' mode (where PayDock collects and reports, but does not respond to Fraud Service responses, and doesn’t block transaction processing)

PayDock API returns all fraud-related response data inside the "fraud" section of each processed transaction.

Fraud Data Description

Field Name Description Possible values
score Overall score of the fraud risk. Bigger number means bigger risk Optional. Not all fraud providers return it. Numeric
status Service-agnostic recommendation from PayDock on the base of the service response "approve", "reject", "review", "failed"
specific_code Fraud service specific code Depends on the fraud service
specific_message Explanation of the code, coming from the fraud service Human-readable text

Testing

PayDock Fraud API in the Sandbox mode is set to return custom results based on the email. While creating one-time token request use "email" key or on tha stage of creating a charge with fraud check use "fraud.data.transaction.billing.customerEmailAddress" key to reproduce different type of responses:

Email value Fraud status
reject@example.com reject
review@example.com review
failed@example.com failed
any other approve

Also PayDock Fraud API in the Sandbox mode is set to return custom results based on the transaction amount.

Amount Fraud status
101 reject
102 review
103 failed
any other approve

Fraud API response examples

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
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
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
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
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 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
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country required
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 n/a
account_number required
account_routing required
account_type required
account_holder_type required
account_bank_name 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 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

Swap Values for templates

The notification templates can be used to load parameters from the customer or transaction into the notification. These can also be used to populate the destination (eg phone number for sms).

The full list of available swap values is:

Field Name Description
{{CHARGE_ID}} PayDock ID for the charge
{{EMAIL}} The email address for the customer associated with the event
{{FIRST_NAME}} The first name for the customer associated with the event
{{LAST_NAME}} The last name for the customer associated with the event
{{PHONE}} The phone number for the customer associated with the event
{{AMOUNT}} The amount for the transaction
{{CURRENCY}} The currency for the transation
{{CUSTOMER_REFERENCE}} The customer reference number provided by the merchant for the customer
{{CHARGE_REFERENCE}} The reference number provided by the merchant for the transaction
{{CHARGE_DESCRIPTION}} The description provided by the merchant for the transaction
{{CREATED_AT}} create date for the object (eg customer, subscription) in ISO format date and time (eg 2016-12-22T10:36:08.170Z)
{{UPDATED_AT}} updated date for the object (eg customer, subscription) in ISO format date and time (eg 2016-12-22T10:36:08.170Z)

Webhook event example

"Example of Transaction Success"
{
    "event": "transaction_success",
    "data": {
        "external_id": "ch_A5UQxvnd7B1aC2",
        "_id": "589c848fc1ecdd2a29fd2197",
        "created_at": "2017-02-09T15:02:39.971Z",
        "updated_at": "2017-02-09T15:02:41.498Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "reference": "Reprehenderit laborum ea a optio iusto quis",
        "description": "Quidem in ea maiores illo quos esse",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-09T15:02:39.968Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589c848fc1ecdd2a29fd2198",
                "status": "complete",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "reference": "Quidem in ea maiores illo quos esse",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "complete"
    }
}

PayDock supports the following webhook events (see payload examples to the right):

"Example of Transaction Failure"
{
    "event": "transaction_failure",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "failed"
    }
}
"Example of Transaction by Subscription Success"
{
    "event": "subscription_transaction",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "complete"
    }
}
"Example of Transaction by Subscription Failed"
{
    "event": "subscription_transaction_failure",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "failed"
    }
}
"Example of Subscription Creation Success"
{
    "event": "subscription_creation_success",
    "data": {
        "__v": 0,
        "created_at": "2017-02-10T11:55:59.804Z",
        "updated_at": "2017-02-10T11:55:59.804Z",
        "amount": 111,
        "payment_source_id": "589daa4fa6c87450a798347d",
        "status": "active",
        "_id": "589daa4fa6c87450a798347f",
        "archived": false,
        "_service": {
            "customer_default_gateway_id": "56a8ab12d6bd4e7d628576aa",
            "tags": "Samantha Washington samwashington@gmail.com"
        },
        "customer": {
            "customer_id": "589daa4ea6c87450a798347c",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 0,
            "successful_transactions": 0
        },
        "schedule": {
            "interval": "week",
            "start_date": "2017-02-10T11:55:58.477Z",
            "next_assessment": "2017-02-10T11:55:58.477Z",
            "next_assessment_planned": "2017-02-10T11:55:58.477Z",
            "first_assessment": "2017-02-10T11:55:58.477Z",
            "status": "inprogress",
            "locked": false,
            "completed_count": 0,
            "retry_count": 0,
            "frequency": 2
        },
        "currency": "AUD"
    }
}
"Example of Subscription Creation Failure"
{
    "event": "subscription_creation_failure",
    "data": {
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "address_country": "AU",
                "type": "card",
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": "**",
                "expire_year": "****",
                "card_ccv": "***"
            },
            "_check_expire_date": false
        },
        "amount": "111",
        "currency": "AUD"
    }
}
"Example of Subscription Finished"
{
    "event": "subscription_finished",
    "data": {
        "_id": "589dacaf1958cb42532f2482",
        "created_at": "2017-02-10T12:06:07.575Z",
        "updated_at": "2017-02-10T12:06:19.146Z",
        "amount": 111,
        "payment_source_id": "589dacaf1958cb42532f2480",
        "status": "expired",
        "__v": 0,
        "archived": false,
        "_service": {
            "customer_default_gateway_id": "56a8ab12d6bd4e7d628576aa",
            "tags": "Samantha Washington samwashington@gmail.com",
            "queue_id": "QU-DD034F558CB0C576"
        },
        "customer": {
            "customer_id": "589dacae1958cb42532f247f",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "last_assessment": "2017-02-10T12:06:19.143Z",
            "interval": "week",
            "start_date": "2017-02-10T12:06:06.596Z",
            "end_date": "2017-02-11T00:00:00.000Z",
            "next_assessment": "2017-02-10T12:06:06.596Z",
            "next_assessment_planned": "2017-02-10T12:06:06.596Z",
            "first_assessment": "2017-02-10T12:06:06.596Z",
            "status": "complete",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD"
    }
}
"Example of Subscription Updated"
{
    "event": "subscription_updated",
    "data": {
        "_id": "589dae7aa6c87450a798348e",
        "created_at": "2017-02-10T12:13:46.059Z",
        "updated_at": "2017-02-10T12:14:39.872Z",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "amount": 111,
        "payment_source_id": "589dae79a6c87450a798348c",
        "_source_ip_address": "159.224.44.130",
        "status": "active",
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "end_amount_total": null,
            "end_amount_before": null,
            "end_transactions": null,
            "end_amount_after": null,
            "end_date": null,
            "interval": "day",
            "start_date": "2017-02-12T00:00:00.000Z",
            "next_assessment": "2017-02-12T00:00:00.000Z",
            "next_assessment_planned": "2017-02-12T00:00:00.000Z",
            "first_assessment": "2017-02-12T00:00:00.000Z",
            "status": "complete",
            "last_assessment": "2017-02-10T12:13:49.469Z",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD",
        "gateway_type": "GatewayType",
        "gateway_name": "Gateway Name",
        "gateway_mode": "test"
    }
}
"Example of Subscription Failed"
{
    "event": "subscription_failed",
    "data": {
        "_id": "589dae7aa6c87450a798348e",
        "created_at": "2017-02-10T12:13:46.059Z",
        "updated_at": "2017-02-10T12:14:39.872Z",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "amount": 111,
        "payment_source_id": "589dae79a6c87450a798348c",
        "_source_ip_address": "159.224.44.130",
        "status": "active",
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "interval": "day",
            "start_date": "2017-02-12T00:00:00.000Z",
            "next_assessment": "2017-02-12T00:00:00.000Z",
            "next_assessment_planned": "2017-02-12T00:00:00.000Z",
            "first_assessment": "2017-02-12T00:00:00.000Z",
            "status": "complete",
            "last_assessment": "2017-02-10T12:13:49.469Z",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD",
        "gateway_type": "GatewayType",
        "gateway_name": "Gateway Name",
        "gateway_mode": "test"
    }
}
"Example of Refund Requested"
{
    "event": "refund_requested",
    "data": {
        "_id": "589dae7c1958cb42532f248a",
        "created_at": "2017-02-10T12:13:48.034Z",
        "updated_at": "2017-02-10T12:16:53.495Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 3,
        "external_id": "ch_A5ovQPHUOTprV7",
        "transactions": [
            {
                "created_at": "2017-02-10T12:13:48.029Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589dae7c1958cb42532f248b",
                "status": "complete",
                "type": "sale"
            },
            {
                "pended_at": "2017-02-11T12:16:53.509Z",
                "created_at": "2017-02-10T12:16:51.582Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daf33a6c87450a7983491",
                "status": "requested",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "refund_requested",
        "transaction": {
            "pended_at": "2017-02-11T12:16:53.509Z",
            "created_at": "2017-02-10T12:16:51.582Z",
            "amount": 111,
            "currency": "AUD",
            "_id": "589daf33a6c87450a7983491",
            "status": "requested",
            "type": "refund"
        }
    }
}
"Example of Refund Success"
{
    "event": "refund_success",
    "data": {
        "_id": "589dae7c1958cb42532f248a",
        "created_at": "2017-02-10T12:13:48.034Z",
        "updated_at": "2017-02-10T12:19:05.117Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 4,
        "external_id": "ch_A5ovQPHUOTprV7",
        "transactions": [
            {
                "created_at": "2017-02-10T12:13:48.029Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589dae7c1958cb42532f248b",
                "status": "complete",
                "type": "sale"
            },
            {
                "created_at": "2017-02-10T12:16:51.582Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daf33a6c87450a7983491",
                "pended_at": "2017-02-11T12:16:53.509Z",
                "status": "complete",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "refunded",
        "transaction": {
            "created_at": "2017-02-10T12:16:51.582Z",
            "amount": 111,
            "currency": "AUD",
            "_id": "589daf33a6c87450a7983491",
            "pended_at": "2017-02-11T12:16:53.509Z",
            "status": "complete",
            "type": "refund"
        }
    }
}
"Example of Refund Failure"
{
    "event": "refund_failure",
    "data": {
        "_id": "589daa621958cb42532f2476",
        "created_at": "2017-02-10T11:56:18.021Z",
        "updated_at": "2017-02-10T12:24:56.723Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589daa4fa6c87450a798347f",
        "__v": 3,
        "external_id": "ch_A5odfEhbA7VaT1",
        "transactions": [
            {
                "created_at": "2017-02-10T11:56:18.017Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daa621958cb42532f2477",
                "status": "complete",
                "type": "sale"
            },
            {
                "created_at": "2017-02-10T12:24:55.732Z",
                "amount": 11111111111,
                "currency": "AUD",
                "_id": "589db1171958cb42532f2497",
                "status": "failed",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589daa4ea6c87450a798347c",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "complete",
        "transaction": {
            "created_at": "2017-02-10T12:24:55.732Z",
            "amount": 11111111111,
            "currency": "AUD",
            "_id": "589db1171958cb42532f2497",
            "status": "failed",
            "type": "refund"
        }
    }
}
"Example of Card Expiration Warning"
{
    "event": "card_expiration_warning",
    "data": {
        "_id": "589db4311958cb42532f24a3",
        "created_at": "2017-02-10T12:38:11.385Z",
        "updated_at": "2017-02-10T12:38:11.385Z",
        "status": "active",
        "default_source": "589db4331958cb42532f24a4",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "first_name": "Samantha",
        "last_name": "Washington",
        "email": "samwashington@gmail.com",
        "statistics": {
            "total_collected_amount": 5555,
            "successful_transactions": 1,
            "currency": {
                "AUD": {
                    "total_amount": 5555,
                    "count": 1
                }
            }
        },
        "payment_source": {
            "updated_at": "2017-02-10T12:38:11.384Z",
            "vault_token": "f5900584-9ced-4b36-9b3a-5e8976d03d11",
            "address_country": "AU",
            "address_line1": "Suite 660",
            "address_line2": "822 Ruiz Square",
            "address_city": "Sydney",
            "address_postcode": "1111",
            "gateway_id": "56b22bc45a9cb7517bdb1079",
            "card_name": "Samantha Washington",
            "expire_month": 3,
            "expire_year": 2017,
            "card_number_last4": "4444",
            "card_scheme": "mastercard",
            "ref_token": "cus_A5pJfU1O30AJsj",
            "status": "active",
            "created_at": "2017-02-10T12:38:11.125Z",
            "_id": "589db4331958cb42532f24a4",
            "type": "card"
        }
    }
}

Card scheme mapping

Card first n digits Code Name
5610, 560221, 560222, 560223, 560224, 560225 ausbc Australian Bank Card
2014, 2149 diners Diner's Club
36 diners Diner's Club International
3528 - 3589 japcb Japanese Credit Bureau
5018, 5020, 5038, 6304, 6759, 6761 - 6763 maestro Maestro
6304, 6706, 6709, 6771 laser Laser
6334, 6767 solo Solo (Paymentech)
51 - 55, 22 - 27 mastercard MasterCard
6011, 622, 64, 65 discover Discover
34,37 amex American Express
300 - 305, 36, 38, 54, 55, 2014, 2149 diners Diner's Club / Carte Blanche
4026, 417500, 4508, 4844, 4913, 4917 visa Visa Electron
4 visa Visa