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:
- The API is a REST API, giving you full control
- Client SDK is a client side javascript library, which provides a secure way of collecting payment information and an easy way to access Paypal and saved payment sources
Getting started
You can get up and running using the PayDock API in just a few minutes.
Start by signing up for a sandbox account. This will give you access to the admin portal.
From the admin portal you can add a payment gateway. You’ll need to sign up for a test account with a payment gateway. Chose any one of the following gateways
Then add your gateway:
You can retrieve your API public key from the admin portal, which you’ll need to authenticate:
Then 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 iFrame). |
| 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
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 |
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
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:
The public key is provided in a few different ways for authentication:
- using Paydock.js, the API Public Key is set with a function call
- using the iFrame, tthe API Public Key is set as a querystring parameter
- using the API, the API Secret Key is added as a header
Response codes / Error codes
"Error appears when no gateway type provided while creating"
{
"status": 400,
"error": {
"message": "No gateway type provided"
},
"resource": {
"type": "gateway",
"data": null
}
}
"Error appears when credentials are not correct"
{
"status": 400,
"error": {
"message": {
"message": "Invalid Transaction Details",
"http_status_code": 400,
"errors": [
{
"gateway_specific_code": "invalid_credentials",
"gateway_specific_description": "invalid credentialssss",
"param_name": null,
"description": "Invalid Transaction Details"
}
]
}
},
"resource": {
"type": "gateway",
"data": null
}
}
"Error appears when credit card is not provided"
{
"status": 400,
"error": {
"message": "Credit Card Invalid or Expired",
"details": [
{
"gateway_specific_code": "number",
"gateway_specific_description": "is not a valid card",
"param_name": "number",
"description": "Credit Card Invalid or Expired"
}
]
}
}
"Error appears when some field or fields not valid"
{
"status": 400,
"error": {
"message": "Validation Error",
"details": [
"No amount provided"
]
},
"resource": {
"type": "charge"
}
}
"Error appears when provided resource is not correct"
{
"status": 404,
"error": {
"message": "Wrong Api path"
},
"resource": {
"type": "path",
"data": null
}
}
"Error appears when some data valid but not exist"
{
"status": 400,
"error": {
"message": "Invalid Transaction Details",
"details": [
{
"gateway_specific_code": "unknown",
"gateway_specific_description": "unknown error",
"param_name": null,
"description": "Invalid Transaction Details"
}
]
}
}
"Error appears when user does not provide correct credentials"
{
"status": 403,
"error": {
"message": "No user with provided secret key"
},
"resource": {
"type": "user",
"data": null
}
}
PayDock’s API follows REST principles on status codes returned from our API.
In addition, the API will generally return a detailed error message and any downstream errors. See the right panel for examples
| HTTP code | Meaning | Description |
|---|---|---|
| 200 | Call successful | appears on success GET request |
| 201 | Created successfully | appears on success POST request while creating new essence |
| 400 | Error with sent data | data which sent has error, description of each of message see below |
| 403 | Error with access | current customer does not have permission |
| 404 | Error with resource | current resource does not exist |
| 500 | System error | appears when server can’t processing request |
PayDock vault
"Example response with vault token"
{
"status": 201,
"error": null,
"resource": {
"type": "customer",
"data": {
"__v": 0,
"created_at": "2017-01-24T23:28:14.045Z",
"updated_at": "2017-01-24T23:28:14.045Z",
"status": "active",
"default_source": "5887e30d28e281756b883f64",
"reference": "TestUniqueReference",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "testpin2@test.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": "Test User",
"expire_month": 1,
"expire_year": 2019,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "53774915",
"status": "active",
"created_at": "2017-01-24T23:28:13.826Z",
"_id": "5887e30d28e281756b883f64",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "58377235377aea03343240cc"
}
}
}
}
PayDock provides a PCI compliant vault for payment details. When the vault is enabled, all payment details are stored in the vault. The vault is enabled or disabled across a whole PayDock account, rather than for individual requests.
When the vault is enabled, any time a payment source is added, this information is stored in the vault. This most commonly happens when a payment source is added to a customer or a new customer is created. This is also visible in the response, which includes the id for the vault token, see example to the right (payment_sources -> vault_token).
Recipes
We have a number of recipes that cover most common uses of the PayDock platform.
Taking a single payment - using the iFrame
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 the Charges API.
We’ll use the client SDK to generate an iframe that collects the payment details from a customer. This will convert the payment details to a one-time token. This token will be submitted with the amount. We’ll then make a call to PayDock’s API to make the payment.
Getting set up
You’ll need a page that you want to display a payment form and your PayDock public key (see Getting Started).
Generating a one-time token using the iFrame
<!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', '', ''); // 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 can then 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 our 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.
Taking a payment
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges';
$apiKey = ; //put your private key here
$data = json_encode([
'amount' => $_POST["donation"],
'currency' => 'AUD',
'token' => $_POST["payment_source"]
]);
$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));
?>
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 needs to be sent to PayDock, along with the amount, to make a payment.
API Reference
The PayDock API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate URL to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.
PayDock users can interact with the service in a number of ways.
| Name | Description |
|---|---|
| Charges | create and query payments |
| Customers | create and manage customer details, with payment information for future payments |
| Subscriptions | create and manage recurring payments |
| Notifications | notifications are automated messages that are triggered from system events |
| Tokens | manages tokens for payment sources |
| Gateways | create and manage gateways |
Charges
A Charge is a one-time payment that can be triggered against any of customer’s connected gateways.
Add charges
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"customer\": \ {\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\", \"email\":\"Test@test.com\",\"reference\":\"CustomReferenceOfCustomer\", \"payment_source\":,\ {\"address_line1\":\"Testline1\",\"address_line2\":\"Testline2\",\"address_city\":\"Testcity\",\"address_state\":\"Teststate\",\"address_country\":\"AU\",\"address_postcode\":\"1234\",\"gateway_id\":\"584577f7822c66541628fa69\",\"card_name\":\"Test\",\"card_number\":\"4444333322221111\",\"expire_month\":\"01\",\"expire_year\":\"19\",\"card_ccv\":\"123\"}}"
"Charge with one time token"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount":"10.00",
"currency":"AUD",
"reference": "Custom user reference",
"description": "Custom user description",
"token":"b76c51ed-9c00-4997-903d-54842826269a"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Charge with credit card"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount": "10.00",
"currency": "AUD",
"reference":"Custom user reference",
"description":"Custom user description",
"customer":{
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "Test@test.com",
"payment_source": {
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Test User",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"17",
"card_ccv":"123"
}
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Charge with bank account"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount": "13630",
"currency": "AUD",
"reference":"Custom user reference",
"customer":{
"first_name": "Promise name",
"last_name": "Promise last name",
"email": "mady889278@gmail.com",
"payment_source": {
"gateway_id": "58495c9490cde693374afc0c",
"type": "bank_account",
"account_name":"Test User",
"account_number":"411111111111111",
"address_postcode": "",
"account_routing":"123123",
"account_type": "savings",
"account_holder_type": "personal",
"account_bank_name": "Bank of Australia"
}
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Charge with customer id"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount":"1350",
"currency":"AUD",
"reference": "Custom user reference",
"description": "Custom user description",
"customer_id":"5857abb356f0cedd2d90a436"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Charge customer with non-default payment source"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount":"1350",
"currency":"AUD",
"reference": "Custom user reference",
"description": "Custom user description",
"customer_id":"5857abb356f0cedd2d90a436",
"payment_source_id":"58209cc5c2ee2574399de888"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges';
$apiKey = 'user_secure_key';
$data = json_encode([
'amount' => '10.00',
'currency' => 'AUD',
'reference' => 'Custom user reference',
'description' => 'Custom user description',
'customer' => [
'first_name' => 'Test_first_name',
'last_name' => 'Test_last_name',
'email' => 'Test@test.com',
'payment_source' => [
'address_line1' => 'Testline1',
'address_line2' => 'Testline2',
'address_city' => 'Testcity',
'address_state' => 'Teststate',
'address_country' => 'AU',
'address_postcode' => '1234',
'gateway_id' => '551bb4af43daf16f355ab259',
'card_name' => 'Test User',
'card_number' => '4200000000000000',
'expire_month' => '05',
'expire_year' => '17',
'card_ccv' => '123',
],
],
]);
$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-token:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "charge",
"data": {
"external_id": "ea1210e2-7be9-44b2-a9cb-f1d0c94ae646",
"__v": 1,
"_id": "585a65fe0daa499b1553c623",
"amount": 7750,
"company_id": "582d930808277de017a2a3f4",
"created_at": "2016-12-21T11:22:38.520Z",
"currency": "AUD",
"reference": "Custom user reference",
"updated_at": "2016-12-21T11:22:49.322Z",
"user_id": "582d930808277de017a2a3f3",
"transactions": [
{
"_id": "585a65fe0daa499b1553c624",
"amount": 7750,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "sale"
}
],
"one_off": true,
"archived": false,
"customer": {
"first_name": "",
"last_name": "Promise last name",
"email": "maybik87@gmail.com",
"reference": "AUS",
"payment_source": {
"type": "card",
"card_name": "Test User",
"card_number_last4": "1111",
"expire_month": 4,
"expire_year": 2020,
"address_postcode": "3000",
"gateway_id": "5853d3974f76d26c24e69165",
"card_scheme": "visa",
"gateway_name": "Promise Pay",
"gateway_type": "PromisePay"
}
},
"status": "complete"
}
}
}
POST /v1/charges
You can create a charge using:
- one-time token, which could be generated using Paydock.js or the iFrame
- credit card details
- direct debit details, using bank account or BSB
- an existing customer
- an existing customer with non-default payment source
For a one time charge, payments are made using a one-time token, credit card or direct debit. Otherwise if you are making a payment for an existing customer, it’s simpler to store the payment source with the customer and make a payment using the customer ID.
| Field Name | Description | Details |
|---|---|---|
| amount | Amount of payment | Float, required |
| currency | Currency code, AUD by default | String, required |
| token | One-time token with all the payment source information | String, required for one-time token |
| description | Manually defined description for payments in payment systems | String, optional |
| reference | Manually defined reference for customer in payment systems | String, optional |
| customer_id | Existing customer ID | String, required for creating charge with customer_id |
| customer | Object with the customer’s information. Not required for one-time token | Object, required unless one-time token is used |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| payment_source_id | Payment source ID | String, optional for creating charge with non-default payment source |
| payment_source | Object with payment information | Object, required |
| gateway_id | Gateway ID | String, required |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments | String, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| card_name | Cardholder name (as on card) | String, required for card |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | Integer, required for card |
| expire_year | Card expiration year yyyy format | Integer, required for card |
| card_ccv | Card CCV number | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| address_city | Customer Address, City | String, optional |
| address_postcode | Customer Address, Postcade | Integer, optional |
| meta | Optional object for stripe connect | Object, optional |
| account_id | Associated stripe account id to specify particular account | String, optional |
See also Required Fields by Gateway
Get charges list
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges';
$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"
{
"status": 200,
"error": null,
"resource": {
"type": "charges",
"data": [
{
"_id": "56f3babec1b4578a24b96813",
"amount": 22,
"created_at": "2016-03-24T10:00:30.266Z",
"currency": "AUD",
"external_id": "000000031b0c71b8",
"subscription_id": "56b07e1d56b29f4e25b1e731",
"updated_at": "2016-03-24T10:00:30.507Z",
"one_off": false,
"archived": false,
"customer": {
"customer_id": "56b07d6156b29f4e25b1e72a",
"first_name": "TEST_FIRST_NAME",
"last_name": "TEST_LAST_NAME",
"email": "test@test.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"type": "card",
"card_name": "test user",
"card_number_last4": "1111",
"expire_month": 5,
"expire_year": 2017,
"address_line1": "test",
"address_line2": "test",
"address_city": "test",
"address_postcode": "1234",
"address_state": "nsw",
"address_country": "AU",
"gateway_id": "56b063f856b29f4e25b1e675"
}
},
"status": "complete"
}, {
"_id": "56f3b33ec1b4578a24b967f3",
"amount": 53.99,
"created_at": "2016-03-24T09:28:30.118Z",
"currency": "AUD",
"external_id": "000000031b0c371e",
"subscription_id": "56b1c8314f5344b5279d98f9",
"updated_at": "2016-03-24T09:28:30.387Z",
"one_off": false,
"archived": false,
"customer": {
"customer_id": "56b1c8314f5344b5279d98f7",
"first_name": "TEST_NEW",
"last_name": "TEST_NEW_2",
"email": "test@test.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"type": "card",
"card_name": "test user",
"card_number_last4": "1111",
"expire_month": 5,
"expire_year": 2017,
"address_line1": "TEST_NEW",
"address_line2": "TEST_NEW",
"address_city": "TEST_NEW",
"address_postcode": "1234",
"address_state": "nsw",
"address_country": "AU",
"gateway_id": "56b063f856b29f4e25b1e675"
}
},
"status": "complete"
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/charges
Returns all charges for the account, limited to 100 records.
Get charges list with parameters
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/?created_at.from=2017-01-01&created_at.to=2017-01-31" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/?created_at.from=2017-01-01&created_at.to=2017-01-31',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges';
$apiKey = 'user_secret_key';
$query = http_build_query([
'created_at.from' => '2017-01-01',
'created_at.to' => '2018-01-31'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "charges",
"data": [
{
"_id": "586cb0b1bce8378c54a8aba7",
"amount": 10,
"created_at": "2017-01-04T08:22:09.223Z",
"currency": "AUD",
"description": "Custom user description",
"external_id": "684000-Custom user reference",
"reference": "Custom user reference",
"updated_at": "2017-01-04T08:22:11.469Z",
"one_off": true,
"archived": false,
"customer": {
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "Test@test.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Test User",
"card_number_last4": "1111",
"expire_month": 1,
"expire_year": 19,
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_postcode": "1234",
"address_state": "Teststate",
"address_country": "AU",
"gateway_id": "586cb09dbce8378c54a8aba6",
"card_scheme": "visa",
"gateway_name": "Nab",
"gateway_type": "Nab"
}
},
"status": "complete"
},
{
"_id": "586bba1abce8378c54a8ab9b",
"amount": 10,
"created_at": "2017-01-03T14:50:02.709Z",
"currency": "AUD",
"description": "Custom user description",
"external_id": "680246-Custom user reference",
"reference": "Custom user reference",
"updated_at": "2017-01-03T14:50:04.596Z",
"one_off": true,
"archived": false,
"customer": {
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "Test@test.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Test User",
"card_number_last4": "1111",
"expire_month": 1,
"expire_year": 19,
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_postcode": "1234",
"address_state": "Teststate",
"address_country": "AU",
"gateway_id": "586bba03bce8378c54a8ab9a",
"card_scheme": "visa",
"gateway_name": "Nab",
"gateway_type": "Nab"
}
},
"status": "complete"
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/charges/?created_at.from=2017-01-01&created_at.to=2017-01-31
Retrieving data on existing charges can be driven by number of action parameters set in URI path.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n transactions from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| subscription_id | To only fetch transactions related to particular subscription | String, optional |
| gateway_id | ID of a gateway with which charges were created | String, optional |
| company_id | ID of a company with which charges were created | String, optional |
| created_at.from | Parameter to set range of created transactions date (yyyy-mm-dd) | String, optional |
| created_at.to | Parameter to set range of created transactions date ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | String, optional |
| search | Word of phrase Customer want to search in created charges (search works by fields: First, Last names and Emails) | String, optional |
| status | Status could be: complete, failed, archived, requested, refund_requested, refunded, inprogress | String, optional |
| archived | Set to true to show all the archived charges. Default: false | Boolean, optional |
| transaction_external_id | ID of an original transaction on gateway side | String, optional |
Get single charge
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges/:id';
$apiKey = 'user_secret_key';
$chargeId = 'charge_id';
$resultLink = str_replace(':id', $chargeId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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"
{
"status": 200,
"error": null,
"resource": {
"type": "charge",
"data": {
"_id": "585ba834e45b75bc368087b3",
"created_at": "2016-12-22T10:17:24.504Z",
"updated_at": "2016-12-22T10:17:41.072Z",
"company_id": "582d930808277de017a2a3f4",
"user_id": "582d930808277de017a2a3f3",
"amount": 17,
"currency": "AUD",
"subscription_id": "585ba520e45b75bc368087ab",
"reference": "Custom reference",
"description": "Custom description",
"__v": 1,
"external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
"transactions": [
{
"created_at": "2016-12-22T10:17:24.495Z",
"amount": 17,
"currency": "AUD",
"_id": "585ba834e45b75bc368087b4",
"service_logs": [
{
"req": {
"account_id": "70b234c5-3af7-41b5-9992-96a014eab056",
"amount": 1700,
"zip": "3000",
"email": "chcsviginolegsdsd12f@gmail.com",
"currency": "AUD",
"country": "AUS",
"retain_account": "true"
},
"response_body": "{\"charges\":{\"id\":\"ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"name\":\"Charge ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"created_at\":\"2016-12-22T10:17:27.108Z\",\"updated_at\":\"2016-12-22T10:17:33.275Z\",\"state\":\"completed\",\"buyer_fees\":0,\"seller_fees\":0,\"credit_card_fee\":0,\"status\":22500,\"amount\":1700,\"custom_data\":null,\"account_id\":\"70b234c5-3af7-41b5-9992-96a014eab056\",\"account_type\":\"credit card\",\"promisepay_fee\":89,\"currency\":\"AUD\",\"payment_method\":\"charge\",\"buyer_name\":\"Oleg cCdekrigin\",\"buyer_email\":\"chcsviginolegsdsd12f@gmail.com\",\"buyer_zip\":\"3000\",\"buyer_country\":\"AUS\",\"related\":{\"buyers\":\"950074ce-bf25-4a8f-ac61-d4c3394ea14a\",\"sellers\":\"5fbeeee6fb58c2519703b115cde28573\"},\"links\":{\"self\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"buyers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/buyers\",\"sellers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/sellers\",\"status\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/status\",\"fees\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/fees\",\"transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/transactions\",\"batch_transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/batch_transactions\"}}}",
"created_at": "2016-12-22T10:17:41.041Z",
"statusCode": 0,
"_id": "585ba845e45b75bc368087b5"
}
],
"status": "complete",
"type": "sale"
}
],
"one_off": false,
"archived": false,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"payment_source": {
"type": "card",
"card_name": "Test User",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_postcode": "3000",
"address_state": "Teststate",
"address_country": "AU",
"gateway_id": "5853e89c2bd79538605a3fb6"
}
},
"status": "complete"
}
}
}
GET /v1/charges/{_id}
Retrieves data on a charge with specified ID.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, optional |
Refund Charge
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges/{_id}/refunds" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/charges/{_id}/refunds',
method: 'POST',
body: {"amount":"50"},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges/:id/refunds';
$apiKey = 'user_secret_key';
$chargeId = 'charge_id';
$data = json_encode([
'amount' => 50
]);
$resultLink = str_replace(':id', $chargeId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $resultLink);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "charge",
"data": {
"__v": 3,
"_id": "55d433f7194516d824af36f6",
"amount": 100,
"company_id": "5584018a27b2cf0b1e4f1a6c",
"created_at": "2015-08-19T07:44:55.874Z",
"currency": "AUD",
"external_id": "ch_6p5Q1DvuPkMhgS",
"updated_at": "2015-08-19T07:45:15.631Z",
"user_id": "5584018a27b2cf0b1e4f1a6b",
"transactions": [
{
"_id": "55d433f7194516d824af36f7",
"amount": 100,
"created_at": "2015-08-19T07:44:55.872Z",
"currency": "AUD",
"service_logs": [
{
"req": {
"body": {
"amount": 10000,
"currency": "AUD",
"card": {
"number": "************4242",
"exp_month": "05",
"exp_year": "17",
"cvc": "123",
"name": "************",
"address_line1": "TestL1",
"address_line2": "TestL2",
"address_city": "TestCity",
"address_zip": "1234",
"address_state": "TestState",
"address_country": "AU"
}
}
},
"response_body": {
"id": "ch_6p5Q1DvuPkMhgS",
"object": "charge",
"created": 1439970296,
"livemode": false,
"paid": true,
"status": "paid",
"amount": 10000,
"currency": "aud",
"refunded": false,
"source": {
"id": "card_6p5QWMz09Em7GV",
"object": "card",
"last4": "4242",
"brand": "Visa",
"funding": "credit",
"exp_month": 5,
"exp_year": 2017,
"fingerprint": "tcKbROx2vZva0RVt",
"country": "US",
"name": "Test Test",
"address_line1": "TestL1",
"address_line2": "TestL2",
"address_city": "TestCity",
"address_state": "TestState",
"address_zip": "1234",
"address_country": "AU",
"cvc_check": "pass",
"address_line1_check": "pass",
"address_zip_check": "pass",
"tokenization_method": null,
"dynamic_last4": null,
"customer": null,
"type": "Visa"
},
"captured": true,
"card": {
"id": "card_6p5QWMz09Em7GV",
"object": "card",
"last4": "4242",
"brand": "Visa",
"funding": "credit",
"exp_month": 5,
"exp_year": 2017,
"fingerprint": "tcKbROx2vZva0RVt",
"country": "US",
"name": "Test Test",
"address_line1": "TestL1",
"address_line2": "TestL2",
"address_city": "TestCity",
"address_state": "TestState",
"address_zip": "1234",
"address_country": "AU",
"cvc_check": "pass",
"address_line1_check": "pass",
"address_zip_check": "pass",
"tokenization_method": null,
"dynamic_last4": null,
"customer": null,
"type": "Visa"
},
"balance_transaction": "txn_6p5Q4SibwxLFaA",
"failure_message": null,
"failure_code": null,
"amount_refunded": 0,
"customer": null,
"invoice": null,
"description": "",
"dispute": null,
"statement_descriptor": null,
"receipt_email": null,
"receipt_number": null,
"shipping": null,
"destination": null,
"application_fee": null,
"refunds": [],
"statement_description": null,
"fee": 239,
"fee_details": [
{
"amount": 239,
"currency": "usd",
"type": "stripe_fee",
"description": "Stripe processing fees",
"application": null,
"amount_refunded": 0
}
],
"uncaptured": null,
"disputed": false
},
"created_at": "2015-08-19T07:44:56.819Z",
"statusCode": 0,
"_id": "55d433f8194516d824af36f8"
}
],
"status": "complete",
"type": "sale"
},
{
"pended_at": "2015-08-20T07:45:15.629Z",
"_id": "55d4340a194516d824af36f9",
"amount": 50,
"created_at": "2015-08-19T07:45:14.406Z",
"currency": "AUD",
"service_logs": [
{
"req": {
"body": "ch_6p5Q1DvuPkMhgS"
},
"response_body": {
"id": "re_6p5QyNU9KEMqKG",
"amount": 5000,
"currency": "aud",
"created": 1439970315,
"object": "refund",
"balance_transaction": "txn_6p5Qx6Z61NwhKY",
"charge": "ch_6p5Q1DvuPkMhgS",
"receipt_number": null,
"reason": null
},
"created_at": "2015-08-19T07:45:15.620Z",
"statusCode": 0,
"_id": "55d4340b194516d824af36fa"
}
],
"status": "requested",
"type": "refund"
}
],
"one_off": true,
"customer": {
"first_name": "StripeF",
"last_name": "StripeL",
"email": "test@test.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Test Test",
"card_number_last4": "4242",
"expire_month": 5,
"expire_year": 17,
"address_line1": "TestL1",
"address_line2": "TestL2",
"address_city": "TestCity",
"address_postcode": "1234",
"address_state": "TestState",
"address_country": "AU",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_scheme": "visa",
"gateway_name": "strp",
"gateway_type": "Stripe"
}
},
"status": "refund_requested"
}
}
}
POST /v1/charges/{_id}/refunds
POST refund request of specified transaction.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
| amount | Amount to be refunded (must not exceed original transaction amount) | Float, optional |
Archive Charge
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges/:id';
$apiKey = 'user_secret_key';
$chargeId = 'charge_id';
$resultLink = str_replace(':id', $chargeId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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": "charge",
"data": {
"_id": "585ba834e45b75bc368087b3",
"created_at": "2016-12-22T10:17:24.504Z",
"updated_at": "2016-12-22T10:29:41.100Z",
"company_id": "582d930808277de017a2a3f4",
"user_id": "582d930808277de017a2a3f3",
"amount": 17,
"currency": "AUD",
"subscription_id": "585ba520e45b75bc368087ab",
"reference": "Custom reference",
"description": "Custom description",
"__v": 1,
"external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
"transactions": [
{
"created_at": "2016-12-22T10:17:24.495Z",
"amount": 17,
"currency": "AUD",
"_id": "585ba834e45b75bc368087b4",
"service_logs": [
{
"req": {
"account_id": "70b234c5-3af7-41b5-9992-96a014eab056",
"amount": 1700,
"zip": "3000",
"email": "chcsviginolegsdsd12f@gmail.com",
"currency": "AUD",
"country": "AUS",
"retain_account": "true"
},
"response_body": "{\"charges\":{\"id\":\"ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"name\":\"Charge ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"created_at\":\"2016-12-22T10:17:27.108Z\",\"updated_at\":\"2016-12-22T10:17:33.275Z\",\"state\":\"completed\",\"buyer_fees\":0,\"seller_fees\":0,\"credit_card_fee\":0,\"status\":22500,\"amount\":1700,\"custom_data\":null,\"account_id\":\"70b234c5-3af7-41b5-9992-96a014eab056\",\"account_type\":\"credit card\",\"promisepay_fee\":89,\"currency\":\"AUD\",\"payment_method\":\"charge\",\"buyer_name\":\"Oleg cCdekrigin\",\"buyer_email\":\"chcsviginolegsdsd12f@gmail.com\",\"buyer_zip\":\"3000\",\"buyer_country\":\"AUS\",\"related\":{\"buyers\":\"950074ce-bf25-4a8f-ac61-d4c3394ea14a\",\"sellers\":\"5fbeeee6fb58c2519703b115cde28573\"},\"links\":{\"self\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df\",\"buyers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/buyers\",\"sellers\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/sellers\",\"status\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/status\",\"fees\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/fees\",\"transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/transactions\",\"batch_transactions\":\"/charges/ec4592bc-77e4-40c0-82f7-6c6637efe6df/batch_transactions\"}}}",
"created_at": "2016-12-22T10:17:41.041Z",
"statusCode": 0,
"_id": "585ba845e45b75bc368087b5"
}
],
"status": "complete",
"type": "sale"
}
],
"one_off": false,
"archived": true,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"payment_source": {
"type": "card",
"card_name": "Test User",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_postcode": "3000",
"address_state": "Teststate",
"address_country": "AU",
"gateway_id": "5853e89c2bd79538605a3fb6"
}
},
"status": "complete"
}
}
}
DELETE /v1/charges/{_id}
Archive Charge to hide it it from charges list. You can still retrieve archived charges, see [Get charges list with parameters
](#get-charges-list-with-parameters)
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
Get archived charges list
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/?archived=true" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/?archived=true',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/charges';
$apiKey = 'user_secret_key';
$query = http_build_query([
'archived' => 'true'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "charges",
"data": [
{
"_id": "585ba834e45b75bc368087b3",
"created_at": "2016-12-22T10:17:24.504Z",
"updated_at": "2016-12-22T10:29:41.100Z",
"amount": 17,
"currency": "AUD",
"subscription_id": "585ba520e45b75bc368087ab",
"reference": "Custom reference",
"description": "Custom description",
"external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
"one_off": false,
"archived": true,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"payment_source": {
"type": "card",
"card_name": "Test User",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_postcode": "3000",
"address_state": "Teststate",
"address_country": "AU",
"gateway_id": "5853e89c2bd79538605a3fb6"
}
},
"status": "complete"
}
],
"count": 1,
"limit": 100,
"skip": 0
}
}
Get archived charges list
GET /v1/charges/?archived=true
Customers
A customer represents an individual who can make payments. Through the use of vaulted tokens, Customers store one or more payment sources, so that payment information doesn’t need to be collected again. Customers can also be associated with Subscriptions and can have Charges added against them.
A customer must have at least one payment source (eg. credit card) that can be used for payment.
Add customer
curl -X "POST" "https://api-sandbox.paydock.com/v1/customers" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"reference\":\"TestUniqueReference\",\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"email\":\"test@test.com\",\"phone\":\"+123451678910\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Testline1\", \"address_line2\":\"test@test.com\", \"address_city\":\"Testcity\", \"address_state\":\"Teststate\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Test User\", \"account_number\":\"1234\", \"account_bsb\":\"123123\"}}"
"Example using one-time token"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'POST',
body: {
"reference": "Custom user reference",
"token":"b76c51ed-9c00-4997-903d-54842826269a"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example using credit card details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'POST',
body: {
"reference":"TestUniqueReference",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"phone": "+123451678910",
"payment_source": {
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Test User",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"17",
"card_ccv":"123"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example using bsb details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'POST',
body: {
"reference":"TestUniqueReference",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"phone": "+123451678910",
"payment_source": {
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "586bb6f3bce8378c54a8ab99",
"type": "bsb",
"account_number": "45679",
"account_bsb": "123",
"account_name": "User name"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?
$apiLink = 'https://api-sandbox.paydock.com/v1/customers';
$apiKey = 'user_secret_key';
$data = json_encode([
'first_name' => 'Test_first_name',
'last_name' => 'Test_last_name',
'email' => 'Test@test.com',
'phone' => '+123451678910',
'payment_source' => [
'address_line1' => 'Testline1',
'address_line2' => 'Testline2',
'address_city' => 'Testcity',
'address_state' => 'Teststate',
'address_country' => 'AU',
'address_postcode' => '1234',
'gateway_id' => '551bb4af43daf16f355ab259',
'card_name' => 'Test User',
'card_number' => '4200000000000000',
'expire_month' => '05',
'expire_year' => '17',
'card_ccv' => '123',
],
]);
$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 (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "customer",
"data": {
"__v": 0,
"created_at": "2016-12-22T10:36:08.171Z",
"updated_at": "2016-12-22T10:36:08.171Z",
"status": "active",
"default_source": "585bac98e45b75bc368087b8",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"_id": "585bac95e45b75bc368087b7",
"payment_sources": [
{
"updated_at": "2016-12-22T10:36:08.170Z",
"vault_token": "94344342-a427-4b9f-9476-f64386d5bba9",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Test User",
"expire_month": 10,
"expire_year": 2020,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "754a2e68-32f9-437c-9544-afc6bef2beb8",
"status": "active",
"created_at": "2016-12-22T10:36:08.083Z",
"_id": "585bac98e45b75bc368087b8",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "5853e89c2bd79538605a3fb6"
}
}
}
}
"Example of response with bsb details (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "customer",
"data": {
"__v": 0,
"created_at": "2017-01-10T11:37:51.454Z",
"updated_at": "2017-01-10T11:37:51.454Z",
"status": "active",
"default_source": "5874c78f88146959c9f9a41c",
"reference": "TestUniqueReference",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"phone": "+123451678910",
"_id": "5874c78f88146959c9f9a41b",
"payment_sources": [
{
"updated_at": "2017-01-10T11:37:51.454Z",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "586bb6f3bce8378c54a8ab99",
"account_bsb": "123",
"account_name": "User name",
"ref_token": "CS-ECF35255704871D4",
"status": "active",
"created_at": "2017-01-10T11:37:51.450Z",
"_id": "5874c78f88146959c9f9a41c",
"type": "bsb"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "586bb6f3bce8378c54a8ab99"
}
}
}
}
POST /v1/customers
You can create a customer using:
- one-time token, which could be generated using Paydock.js or the iFrame
- credit card details
- direct debit details, using bank account or BSB
| Field Name | Description | Details |
|---|---|---|
| token | One-time token with all payment source information. Required for adding a customer with a one-time token | String required, if adding customer with token |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| reference | Customer unique reference. This is customer internal reference number for a customer | String, optional |
| payment_source | Object which includes all payment information | Object required, if adding customer direct debit or credit |
| gateway_id | Gateway ID | String required |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments | String, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String required bank account and bsb only |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String required bsb account only |
| account_routing | Account routing number. BSB/Routing/SWIFT/IBAN Number. | String required bank account only |
| account_number | Number of customer bank account. Parameter required when using Direct Debit only | String required bank account and bsb only |
| account_holder_type | Account type (‘personal’ or ‘business’) | String required bank account only |
| account_bank_name | Name of account bank | String required bank account only |
| card_name | Cardholder name (as on card) | String required card only |
| card_number | Card number | Integer required card only |
| expire_month | Card expiration month mm format | Integer required card only |
| expire_year | Card expiration year yyyy format | Integer required card only |
| card_ccv | Card CCV number. Depending on customer gateway and configuration, this may be required | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_city | Customer Address, City | String, optional |
| address_postcode | Customer Address, Postcade | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| meta | Object where can be specified optional information about customer | Object, optional |
| user_id | existing user on payment system side (used by Assembly payments). Paydock matches customer on Assembly payments by this id, and adds new payment source | String optional |
See also Required fields by Gateway
Get customer list
curl -X "GET https://api-sandbox.paydock.com/v1/customers" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/customers';
$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"
{
"status":201,
"error":null,
"resource":{
"type":"customer",
"data":[
{
"_id":"585bac95e45b75bc368087b7",
"created_at":"2016-12-22T10:36:08.171Z",
"updated_at":"2016-12-22T10:36:08.171Z",
"status":"active",
"_source_ip_address":"::1",
"default_source":"585bac98e45b75bc368087b8",
"company_id":"582d930808277de017a2a3f4",
"user_id":"582d930808277de017a2a3f3",
"first_name":"Oleg",
"last_name":"cCdekrigin",
"email":"chcsviginolegsdsd12f@gmail.com",
"phone":"+123451678910",
"payment_sources":[
{
"updated_at":"2016-12-22T10:36:08.170Z",
"vault_token":"94344342-a427-4b9f-9476-f64386d5bba9",
"address_line1":"Testline1",
"address_line2":"Testline2",
"address_city":"Testcity",
"address_state":"Teststate",
"address_country":"AU",
"address_postcode":"3000",
"gateway_id":"5853e89c2bd79538605a3fb6",
"card_name":"Test User",
"expire_month":10,
"expire_year":2020,
"card_number_last4":"1111",
"card_scheme":"visa",
"ref_token":"754a2e68-32f9-437c-9544-afc6bef2beb8",
"status":"active",
"created_at":"2016-12-22T10:36:08.083Z",
"_id":"585bac98e45b75bc368087b8",
"type":"card"
}
],
"archived":false,
"statistics":{
"total_collected_amount":0,
"successful_transactions":0
}
}
]
}
}
GET /v1/customers
Returns all customers for the account, limited to 100 records.
Get customer list with parameters
curl -X "GET https://api-sandbox.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/customers';
$apiKey = 'user_secret_key';
$query = http_build_query([
'search' => 'test',
'sortkey' => 'firstname'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "customers",
"data": [
{
"created_at": "2015-08-26T05:45:21.293Z",
"updated_at": "2015-08-26T05:45:32.587Z",
"status": "active",
"default_source": "55dd5271036a2d542c1efbfc",
"first_name": "test2",
"last_name": "test2",
"email": "test2@test.com",
"_id": "55dd5270036a2d542c1efbfb",
"__v": 0,
"payment_sources": [
{
"updated_at": "2015-08-26T05:45:32.586Z",
"address_line1": "test2",
"address_line2": "test2",
"address_city": "test2",
"address_state": "test2",
"address_country": "AU",
"address_postcode": "1233",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_name": "test2 test2",
"expire_month": 5,
"expire_year": 2017,
"card_number_last4": "4242",
"card_scheme": "visa",
"ref_token": "cus_6rg5sC4wp2My8I",
"status": "active",
"created_at": "2015-08-26T05:45:21.290Z",
"_id": "55dd5271036a2d542c1efbfc",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
},
{
"created_at": "2015-08-25T13:58:57.498Z",
"updated_at": "2015-08-25T13:59:16.884Z",
"status": "active",
"default_source": "55dc74a16379cd122541764e",
"first_name": "test",
"last_name": "test",
"email": "test@test.com",
"_id": "55dc74a06379cd122541764d",
"__v": 0,
"payment_sources": [
{
"updated_at": "2015-08-25T13:59:16.884Z",
"address_line1": "test",
"address_line2": "test",
"address_city": "test",
"address_state": "test",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_name": "test test",
"expire_month": 5,
"expire_year": 2017,
"card_number_last4": "4242",
"card_scheme": "visa",
"ref_token": "cus_6rQooHxT3HF3p6",
"status": "active",
"created_at": "2015-08-25T13:58:57.476Z",
"_id": "55dc74a16379cd122541764e",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}&payment_source_id={id}
Retrieving data on existing customers can be driven by number of action parameters set in URI path.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n customers from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| search | Text search parameter (search in fields firstname, lastname, email) | String, optional |
| sortkey | Sorting key parameter i.e. firstname, lastname, email, startdate, ASC direction by default | String, optional |
| sortdirection | Sorting order direction parameter (ASC by default, only value that affects is DESC) | String, optional |
| gateway_id | ID of a gateway with which customers default payments source was created | String, optional |
| payment_source_id | ID of a stored customers payment_source | String, optional |
| id | ID of particular customer | String, optional |
| reference | Reference of particular customer | String, optional |
| archived | Set to true to show all the archived (deleted) customers. Default: false | Boolean, optional |
Response:
| Field Name | Description | Details |
|---|---|---|
| type | Type of returned resource | String |
| data | Returned data | Array |
| query_token | Token witch content query data for further queries with filtered data | String |
| count | Pagination param. Count of all users | Integer |
| limit | Pagination param. Limit of users | Integer |
| skip | Pagination param. Skip users from start | Integer |
Get customer payment sources by query token
GET /v1/customers/payment_sources?query_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU4MjAyZTJmYzJlZTI1NzQzOTlkZTg0YiIsImxpbWl0IjpudWxsLCJza2lwIjpudWxsLCJpYXQiOjE1MDEyNDQ0MDh9.d9ToSDAWtF3zcP8B2ieej0EkFSCFYiHlLN5mimDCQQQ
Get payment sources of customers by query_token generated from getCustomers with params endpoint
Get customer item info
curl -X "GET https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?
$apiLink = 'https://api-sandbox.paydock.com/v1/customers/:id';
$apiKey = 'user_secret_key';
$customerId = 'customer_id';
$resultLink = str_replace(':id', $customerId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_id": "585ba514e45b75bc368087a8",
"created_at": "2016-12-22T10:04:06.418Z",
"updated_at": "2016-12-22T10:04:06.418Z",
"status": "active",
"default_source": "585ba516e45b75bc368087a9",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"__v": 0,
"payment_sources": [
{
"updated_at": "2016-12-22T10:04:06.417Z",
"vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Test User",
"expire_month": 10,
"expire_year": 2020,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "70b234c5-3af7-41b5-9992-96a014eab056",
"status": "active",
"created_at": "2016-12-22T10:04:06.370Z",
"_id": "585ba516e45b75bc368087a9",
"type": "card"
}
],
"statistics": {
"currency": {
"AUD": {
"count": 2,
"total_amount": 27
}
},
"total_collected_amount": 27,
"successful_transactions": 2
},
"_service": {
"default_gateway_id": "5853e89c2bd79538605a3fb6"
}
}
}
}
GET /v1/customers/{_id}
Retrieves data on the customer with specified ID.
| Field Name | Description | Details |
|---|---|---|
| _id | ID of particular customer you want to get full information | String, required |
Update customer
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"reference\":\"TestUniqueReference\",\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"email\":\"test@test.com\",\"phone\":\"+123451678910\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Testline1\", \"address_line2\":\"test@test.com\", \"address_city\":\"Testcity\", \"address_state\":\"Teststate\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Test User\", \"account_number\":\"1234\", \"account_bsb\":\"123123\"}}"
"Example update user using credit card details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"reference":"TestUniqueReference",
"first_name": "TestFirstNameEdit",
"last_name": "TestLastNameEdit",
"email": "test@test.com",
"default_source":"5565b4c5648a0df61455a689"
"payment_source": {
"address_line1": "TestAddrLine1Edit",
"address_line2": "TestAddrLine2Edit",
"address_city": "TestCityEdit",
"address_state": "TestStateEdit",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"card_name":"Test UserEdit",
"card_number":"4987654321098769",
"expire_month": "02",
"expire_year":"19",
"card_ccv":"223"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/customers/:id';
$apiKey = 'user_secret_key';
$customerId = 'customer_id';
$data = json_encode([
'reference' => 'Custom user reference',
'first_name' => 'TestFirstNameEdit',
'last_name' => 'TestLastNameEdit',
'email' => 'test@test.com',
'default_source' => '5565b4c5648a0df61455a689',
'payment_source' => [
'address_line1' => 'TestAddrLine1Edit',
'address_line2' => 'TestAddrLine2Edit',
'address_city' => 'TestCityEdit',
'address_state' => 'TestStateEdit',
'address_country' => 'AU',
'address_postcode' => '2234',
'gateway_id' => '55534a8ba28d339a100e741c',
'card_name' => 'Test UserEdit',
'card_number' => '4987654321098769',
'expire_month' => '02',
'expire_year' => '19',
'card_ccv' => '223'
]
]);
$resultLink = str_replace(':id', $customerId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $resultLink);
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 using credit card details"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_id": "5565b4c5648a0df61455a688",
"created_at": "2015-05-27T12:12:53.525Z",
"updated_at": "2015-05-27T13:26:22.401Z",
"status": "active",
"default_source": "5565b4c5648a0df61455a689",
"reference":"TestUniqueReference",
"first_name": "TestFirstNameEdit",
"last_name": "TestLastNameEdit",
"email": "test@test.com",
"__v": 2,
"payment_sources": [
{
"updated_at": "2015-05-27T13:26:22.403Z",
"address_line1": "Ttests1",
"address_line2": "Ttest2",
"address_city": "Testcity2",
"address_state": "Teststate2",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"card_name": "Test User2",
"expire_month": 5,
"expire_year": 2017,
"card_number_last4": "8769",
"card_scheme": "visa",
"ref_token": "746767",
"status": "active",
"created_at": "2015-05-27T12:12:53.523Z",
"_id": "5565b4c5648a0df61455a689",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
}
}
"Example update user using bsb details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"reference":"TestUniqueReference",
"first_name": "TestFirstNameEdit",
"last_name": "TestLastNameEdit",
"email": "test@test.com",
"default_source":"5565b4c5648a0df61455a689",
"payment_source": {
"gateway_id": "586bb6f3bce8378c54a8ab99",
"type": "bsb",
"account_number": "456778",
"account_bsb": "123",
"account_name": "User name edited"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example of response using bsb details"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_id": "5565b4c5648a0df61455a688",
"created_at": "2015-05-27T12:12:53.525Z",
"updated_at": "2015-05-27T13:26:22.401Z",
"status": "active",
"default_source": "5565b4c5648a0df61455a689",
"reference":"TestUniqueReference",
"first_name": "TestFirstNameEdit",
"last_name": "TestLastNameEdit",
"email": "test@test.com",
"__v": 2,
"payment_sources": [
{
"updated_at": "2015-05-27T13:26:22.403Z",
"address_line1": "Ttests1",
"address_line2": "Ttest2",
"address_city": "Testcity2",
"address_state": "Teststate2",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"account_number": "456778",
"account_bsb": "123",
"account_name": "User name edited",
"ref_token": "746767",
"status": "active",
"created_at": "2015-05-27T12:12:53.523Z",
"_id": "5565b4c5648a0df61455a689",
"type": "bsb"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
}
}
POST /v1/customers/{_id}
You can use this API to update customer information (eg email address) or add more payment sources to a customer.
Similar to creating or adding a customer or creating a charge, you can add a payment source using:
- one-time token, which could be generated using Paydock.js or the iFrame
- credit card details
- direct debit details, using bank account or BSB
| Field Name | Description | Details |
|---|---|---|
| token | One-time token with all payment source information, required only for updating customer with one-time token | Object, required if adding payment source using token |
| reference | Customer unique reference | String, optional |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| default_source | Default Payments Source ID. If changing payment customer information, new payment source becomes default. To change default payment source, please set this value to existing payments source | String, optional |
| payment_source | Object with payment information | Object, required |
| address_city | Customer Address, City | String, required |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb or bank account only |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb only |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required bank account and bsb only |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required bank account onlyuired |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required bank account only |
| account_bank_name | Name of account bank | String, required bank account only |
| card_name | Cardholder name (as on card) | String, required card only |
| card_number | Card number | Integer, required card only |
| expire_month | Card expiration month mm format | Integer, required card only |
| expire_year | Card expiration year yyyy format | Integer, required card only |
| card_ccv | Card CCV number | Integer, required card only |
| gateway_id | Gateway ID | String, required |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_postcode | Customer Address, Postcade | Integer, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| type | Type of payment. Use ‘bsb’ to post with bsb account and ‘card’ for payments with credit cards. Use ‘bank_account’ for using bank account credentials. Parameter required when using Direct Debit | String, optional |
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"token\":\"6a40af93-7410-4383-907f-b9d7b2594cd0\",\"reference\":\"Custom edit reference new\",\"default_source\":\"56418767811923162676983c\"}"
"Example update user using one time token"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"token":"6a40af93-7410-4383-907f-b9d7b2594cd0",
"reference":"Custom edit reference new",
"default_source":"56418767811923162676983c"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/customers/{_id}';
$apiKey = 'user_secret_key';
$data = json_encode([
'token' => '6a40af93-7410-4383-907f-b9d7b2594cd0',
'reference' => 'Custom edit reference new',
'default_source' => '56418767811923162676983c'
]);
$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 for updating customer with one time token (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"reference": "Custom edit reference new",
"_id": "5875e3990be0bb681d28cb8a",
"created_at": "2017-01-11T07:49:45.705Z",
"updated_at": "2017-01-11T07:53:05.875Z",
"email": "qwert@gmail.com",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"phone": "+12345678910",
"default_source": "5875e3740be0bb681d28cb85",
"__v": 1,
"payment_sources": [
{
"created_at": "2017-01-11T07:49:08.718Z",
"status": "active",
"ref_token": "9c04a9aa-5cdc-4e8d-b0a7-9ff5b9ba8747",
"card_scheme": "visa",
"card_number_last4": "1111",
"expire_year": 2019,
"expire_month": 9,
"card_name": "Test User",
"gateway_id": "58577f2788aaec54114b3376",
"address_postcode": "1234",
"address_country": "AU",
"address_state": "Teststate",
"address_city": "Testcity",
"address_line2": "Testline2",
"address_line1": "Testline1",
"vault_token": "8e59e161-de00-427b-89f8-9e761e377c5b",
"updated_at": "2017-01-11T07:53:05.873Z",
"_id": "5875e3740be0bb681d28cb85",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "58577f2788aaec54114b3376"
}
}
}
}
Archive customer
curl -X "DELETE https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/customers/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/customers/:id';
$apiKey = 'user_secret_key';
$customerId = 'customer_id';
$resultLink = str_replace(':id', $customerId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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": "customer",
"data": {
"_id": "585ba514e45b75bc368087a8",
"created_at": "2016-12-22T10:04:06.418Z",
"updated_at": "2016-12-22T10:42:20.199Z",
"status": "active",
"default_source": "585ba516e45b75bc368087a9",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910",
"__v": 0,
"payment_sources": [
{
"updated_at": "2016-12-22T10:42:20.198Z",
"vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Test User",
"expire_month": 10,
"expire_year": 2020,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "70b234c5-3af7-41b5-9992-96a014eab056",
"status": "active",
"created_at": "2016-12-22T10:04:06.370Z",
"_id": "585ba516e45b75bc368087a9",
"type": "card"
}
],
"statistics": {
"currency": {
"AUD": {
"count": 2,
"total_amount": 27
}
},
"total_collected_amount": 27,
"successful_transactions": 2
},
"_service": {
"default_gateway_id": "5853e89c2bd79538605a3fb6"
}
}
}
}
DELETE /v1/customers/{_id}
Customer with specified id will be archived. You can retrieve archived customers using Get customer list with parameters
| Field Name | Description | Details |
|---|---|---|
| _id | Customer unique id | String, required |
Subscriptions
Add Subscription
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"},\"customer\":\{\"first_name\": \"Test_first_name\",\"last_name": "Test_last_name\",\"email": "Test@test.com\",\"reference": "CustomReference\",\"payment_source\": {\"address_line1\": \"Testline1\",\"address_line2\": \"Testline2\",\"address_city\": \"Testcity\",\"address_state\": \"Teststate\",\"address_country\": \"AU\",\"address_postcode\": \"1234\",\"gateway_id\": \"55925037556cc23c1ed3773e\",\"card_name\":\"Test User\",\"card_number\":\"4200000000000000\",\"expire_month\":\"01\",\"expire_year\":\"17\",\"card_ccv\":\"123\"}}}"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions',
body: {
"amount": "10.00",
"currency": "AUD",
"reference": "Custom user reference",
"description": "Custom user description",
"customer": {
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "Test@test.com",
"reference": "CustomReference",
"payment_source": {
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "55925037556cc23c1ed3773e",
"card_name": "Test User",
"card_number": "4200000000000000",
"expire_month": "01",
"expire_year": "17",
"card_ccv": "123"
}
},
"schedule": {
"frequency": "1",
"interval": "day",
"start_date": "2015-07-20",
"end_date": "2016-07-25T07:35:11Z"
}
},
method: 'POST',
headers: {
'content-type': 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions';
$apiKey = 'user_secret_key';
$data = json_encode([
'schedule' => [
'start_date' => '2015-10-25',
'end_date' => '2018-07-24T11:51:30.211Z',
'interval' => 'week',
'frequency' => '1'
],
'amount' => '10.00',
'currency' => 'AUD',
'reference' => 'Custom user reference',
'description' => 'Custom user description',
'customer' => [
'first_name' => 'Test_first_name',
'last_name' => 'Test_last_name',
'email' => 'Test@test.com',
'reference' => 'CustomReference',
'payment_source' => [
'address_line1' => 'Testline1',
'address_line2' => 'Testline2',
'address_city' => 'Testcity',
'address_state' => 'Teststate',
'address_country' => 'AU',
'address_postcode' => '1234',
'gateway_id' => '589864e982c910153a41df7e',
'card_name' => 'Test User',
'card_number' => '4200000000000000',
'expire_month' => '05',
'expire_year' => '17',
'card_ccv' => '123',
],
],
]);
$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 (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "subscription",
"data": {
"__v": 0,
"created_at": "2015-07-24T11:27:44.504Z",
"updated_at": "2015-07-24T11:27:44.504Z",
"amount": 10,
"description": "Custom user description",
"reference": "Custom user reference",
"status": "active",
"_id": "55b2213073065f9423a45d78",
"archived": false,
"_service": {
"customer_default_gateway_id": "55925037556cc23c1ed3773e",
"tags": "test_first_name test_last_name test@test.com"
},
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"reference": "CustomReference"
},
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"schedule": {
"interval": "day",
"start_date": "2015-07-24T11:27:43.743Z",
"end_date": "2016-07-25T00:00:00.000Z",
"next_assessment": "2015-07-24T11:27:43.743Z",
"first_assessment": "2015-07-24T11:27:43.743Z",
"status": "inprogress",
"locked": false,
"completed_count": 0,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
POST /v1/subscriptions
Subscriptions are recurring billing events. These can be set up to take scheduled payments from a customer without having to re-enter the billing details.
In order to charge for a recurring subscription, it can be added with:
- credit card details or a bank account. This will also create a customer
- a customer id
- a one-time token. This will also create a customer
Subscriptions can run on different intervals (ie daily, weekly, monthly etc) and frequencies (ie ‘every X days’). You can also control the start date for a subscription.
Subscriptions can also be configured to end after:
- a certain number of transactions
- an amount (eg end before reaching $1000 or end after reaching $1000)
- a date
If a subscription is created without a customer ID, a new customer will be created and the customer ID will be returned in the response.
| Field Name | Description | Details |
|---|---|---|
| amount | Amount of payment | Float, required |
| currency | Currency code, AUD by default | String, required |
| customer_id | ID of PayDock customer | Object, required adding subscription with customer id |
| token | One-time token with all payment source information | String, required adding subscription using one time token |
| reference | Manually defined reference for payments in payment systems | String, optional |
| description | Manually defined description for payments in payment systems | String, optional |
| customer | Object with customers information | Object, required using customer information |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| reference | Manually defined reference for customer in payment systems | String, required |
| payment_source | Object with payment information | Object, required, if no customer provided |
| gateway_id | Gateway ID | String, required if no customer provided |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | Integer, required for card |
| expire_year | Card expiration year yyyy format | Integer, required for card |
| card_name | Card holder name | String, optional |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use 'bank_account’ for using direct debit payments. 'bsb’ can also be used for direct debit payment. | String, optional |
| card_ccv | Card CCV number | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_city | Customer Address, City | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| address_postcode | Customer Address, Postcode | Integer, optional |
| schedule | Object with subscription schedule information | Object, required |
| interval | Assessment interval one-off, week, month, year, day | String, required |
| frequency | Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) | Integer, required |
| start_date | Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, optional |
| end_date | End date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, optional |
| end_amount_after | Total amount of all successful transactions (equals or exceeds) | Float, optional |
| end_amount_before | Total amount of all successful transactions (not to exceed) | Float, optional |
| end_amount_total | Total amount to be payid with subscription (equals). NOTE: If last payment of subscription schedule will be less then $ 1.00, some gateways may respond with error and subscription status will become 'failed’. | Float, optional |
| end_transactions | Total count of all successful transactions | Integer, optional |
| meta | Optional object for stripe connect | Object, optional |
| account_id | Associated stripe account id to specify particular account | String, optional |
See also Required fields by Gateway
Add subscription using Customer ID
Charges can be added to a company only if there is a Billing Plan assigned to it. Customers can add a subscription through using the Customer ID.
Add subscription with one-time token
Subscriptions can be added to a company only if there is a Billing Plan assigned to it. Customers can use a Credit Card or Direct Debit information directly, or by creating a one-time token. One-time tokens are created on the customer side, using PayDock.js or by creating a token on the API side. Also, one-time tokens can created using iFrame. A result of the iFrame process is that the Customer will get a webhook with the “payment_source” value. Parameter “payment_source” is used as a “token” in future examples.
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"customer_id\":\"b76c51ed9c004997903d54842826269a\"}"
"Example of adding subscription using customer id"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions',
body: {
"amount":"10.00",
"currency":"AUD",
"reference": "Custom user reference",
"description": "Custom user description",
"customer_id":"b76c51ed9c004997903d54842826269a",
"schedule": {
"frequency":1,
"interval":"day",
"start_date":"2016-11-05",
"end_date":"2018-07-24T11:51:30.211Z"
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions';
$apiKey = 'user_secret_key';
$customerId = 'customer_id';
$data = json_encode([
'amount' => '17',
'currency' => 'AUD',
'reference' => 'Custom reference',
'description' => 'Custom description',
'customer_id' => $customerId,
'schedule' => [
'frequency' => 1,
'interval' => 'day',
'start_date' => '2016-11-05',
'end_date' => '2018-07-24T11:51:30.211Z'
]
]);
$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 (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "subscription",
"data": {
"__v": 0,
"created_at": "2016-11-07T15:34:44.837Z",
"updated_at": "2016-11-07T15:34:44.837Z",
"amount": 10,
"description": "Custom user description",
"reference": "Custom user reference",
"payment_source_id": "58209cc5c2ee2574399de888",
"status": "active",
"_id": "58209f14c2ee2574399de88c",
"archived": false,
"_service": {
"customer_default_gateway_id": "581c753a8f51564723663fe7",
"tags": "test_first_name test_last_name test@test.com"
},
"customer": {
"customer_id": "58209cc3c2ee2574399de887",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"reference": "CustomReferenceOfCustomer"
},
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"schedule": {
"interval": "day",
"start_date": "2016-11-07T15:34:44.827Z",
"end_date": "2017-07-25T00:00:00.000Z",
"next_assessment": "2016-11-07T15:34:44.827Z",
"next_assessment_planned": "2016-11-07T15:34:44.827Z",
"first_assessment": "2016-11-07T15:34:44.827Z",
"status": "inprogress",
"locked": false,
"completed_count": 0,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"schedule\": \ {\"frequency\":\1\,\"interval\":\"month\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"amount\":\"10.00\", \"currency\":\"AUD\", \"reference\":\"Custom subscription reference\", \"description\":\"Custom subscription description\", \"token\":\"b76c51ed-9c00-4997-903d-54842826269a\"}\"
"Example of adding subscription using one time token"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions',
body: {
"amount":"10.00",
"currency":"AUD",
"reference": "Custom subscription reference",
"description": "Custom subscription description",
"token":"b76c51ed-9c00-4997-903d-54842826269a",
"schedule":{
"interval":"month",
"frequency":"1",
"start_date":"2015-11-10",
"end_date":"2016-01-10"
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions';
$apiKey = 'user_secret_key';
$oneTimeToken = 'one_time_token';
$data = json_encode([
'amount' => '17',
'currency' => 'AUD',
'reference' => 'Custom reference',
'description' => 'Custom description',
'token' => $oneTimeToken,
'schedule' => [
'frequency' => 1,
'interval' => 'month',
'start_date' => '2016-11-05',
'end_date' => '2018-07-24T11:51:30.211Z'
],
]);
$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 (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "subscription",
"data": {
"__v": 0,
"created_at": "2015-11-10T11:27:44.504Z",
"updated_at": "2015-11-10T11:27:44.504Z",
"amount": 10,
"description": "Custom subscription description",
"reference": "Custom subscription reference",
"status": "active",
"_id": "55b2213073065f9423a45d78",
"archived": false,
"_service": {
"customer_default_gateway_id": "551bb4af43daf16f355ab259",
"tags": "test_first_name test_last_name test@test.com"
},
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com"
},
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"schedule": {
"interval": "month",
"start_date": "2015-11-10T11:27:43.743Z",
"end_date": "2016-01-10T00:00:00.000Z",
"next_assessment": "2015-12-10T11:27:43.743Z",
"first_assessment": "2015-11-10T11:27:43.743Z",
"status": "inprogress",
"locked": false,
"completed_count": 0,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
Update subscription details
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Custom user reference\",\"description\":\"Custom user description\",\"schedule\": \ {\"interval\":\"year\",\"start_date\":\"2015-07-20\"}"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions/{_id}',
body: {
"amount": "17",
"currency": "AUD",
"reference":"Custom reference",
"description":"Custom description"
"schedule":{
"interval":"year",
"start_date":"2015-08-01"
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions/:id';
$apiKey = 'user_secret_key';
$subscriptionId = 'subscription_id';
$data = json_encode([
'amount' => '88',
'currency' => 'AUD',
'reference' => 'Custom reference',
'description' => 'Custom description',
'schedule' => [
'interval' => 'year',
'start_date'=> '2015-08-01'
]
]);
$resultLink = str_replace(':id', $subscriptionId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $resultLink);
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": 200,
"error": null,
"resource": {
"type": "subscription",
"data": {
"_id": "55b2213073065f9423a45d78",
"amount": 167,
"company_id": "559241db556cc23c1ed3770b",
"created_at": "2015-07-24T11:27:44.504Z",
"description": "Custom description",
"reference": "Custom reference",
"status": "active",
"updated_at": "2015-07-24T11:31:34.697Z",
"user_id": "559241db556cc23c1ed3770a",
"archived": false,
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com"
},
"statistics": {
"total_collected_amount": 10,
"successful_transactions": 1
},
"schedule": {
"end_date": "2016-07-25T00:00:00.000Z",
"first_assessment": "2015-08-01T00:00:00.000Z",
"interval": "year",
"last_assessment": "2015-07-24T11:28:02.480Z",
"next_assessment": "2015-08-01T00:00:00.000Z",
"start_date": "2015-08-01T00:00:00.000Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD",
"gateway_type": "Pin",
"gateway_name": "Pin label",
"gateway_mode": "test"
}
}
}
POST /v1/subscriptions/{_id}
Updates an existing subscription to adjust payment schedule or end conditions.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
| amount | Amount of payment | Float, required |
| description | Manually defined description for payments in payment systems | String, optional |
| reference | Manually defined reference for payments in payment systems | String, optional |
| payment_source_id | The payment source to be used to pay for the subscription, generally use a payment source retrieved from a customer | String, optional |
| schedule | Object with subscription schedule information | Object, required |
| interval | Assessment interval week, month, year, day | String, required |
| frequency | Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) | Integer, required |
| start_date | Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, required |
| end_date | End date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, required |
| end_amount_after | Total amount of all successful transactions (equals or exceeds) | Float, optional |
| end_amount_before | Total amount of all successful transactions (not to exceed) | Float, optional |
| end_amount_total | Total amount to be paid with subscription (equals) | Float, optional |
| end_transactions | Total count of all successful transactions | Integer, optional |
Get subscription list
curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions';
$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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "subscriptions",
"data": [{
"_id": "56d84e98815b245d242b4996",
"amount": 10.70,
"company_id": "56a5e4e6489dc5402557d9b7",
"created_at": "2016-03-03T14:47:52.834Z",
"status": "expired",
"updated_at": "2016-03-03T14:48:00.579Z",
"user_id": "56a5e4e6489dc5402557d9b6",
"archived": false,
"customer": {
"customer_id": "56d84e97815b245d242b4991",
"first_name": "TEST_NEW_SUB55",
"last_name": "Number",
"email": "test@test.com",
"reference": "CustomReference"
},
"statistics": {
"total_collected_amount": 10.59,
"successful_transactions": 1
},
"schedule": {
"end_amount_total": 10.70,
"first_assessment": "2016-03-03T14:47:51.739Z",
"interval": "day",
"last_assessment": "2016-03-03T14:48:00.576Z",
"next_assessment": "2016-03-03T14:47:51.739Z",
"start_date": "2016-03-03T14:47:51.739Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD",
"gateway_type": "Stripe",
"gateway_name": "strp",
"gateway_mode": "test"
}, {
"_id": "56d84e7b815b245d242b494b",
"amount": 12.00,
"company_id": "56a5e4e6489dc5402557d9b7",
"created_at": "2016-03-03T14:47:23.051Z",
"status": "expired",
"updated_at": "2016-03-03T14:47:30.590Z",
"user_id": "56a5e4e6489dc5402557d9b6",
"archived": false,
"customer": {
"customer_id": "56d84e79815b245d242b4949",
"first_name": "TEST_NEW_SUB55",
"last_name": "Number",
"email": "test@test.com"
},
"statistics": {
"total_collected_amount": 10.59,
"successful_transactions": 1
},
"schedule": {
"end_amount_total": 12.00,
"first_assessment": "2016-03-03T14:47:21.805Z",
"interval": "day",
"last_assessment": "2016-03-03T14:47:30.588Z",
"next_assessment": "2016-03-03T14:47:21.805Z",
"start_date": "2016-03-03T14:47:21.805Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD",
"gateway_type": "Stripe",
"gateway_name": "strp",
"gateway_mode": "test"
}],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/subscriptions
Returns all subscriptions for the account, limited to 100 records.
Get subscription list with parameters
curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}',
body: {
"amount": "17",
"currency": "AUD",
"reference":"Custom reference",
"description":"Custom description"
"schedule":{
"interval":"year",
"start_date":"2015-08-01"
}
}
},
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions';
$apiKey = 'user_secret_key';
$query = http_build_query([
'search' => 'test',
'sortkey' => 'firstname'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "subscriptions",
"data": [
{
"_id": "55a62eb88d7127722432c69d",
"amount": 10,
"company_id": "559241db556cc23c1ed3770b",
"created_at": "2015-07-15T09:58:16.269Z",
"status": "active",
"updated_at": "2015-07-15T10:01:30.978Z",
"user_id": "559241db556cc23c1ed3770a",
"archived": false,
"customer": {
"customer_id": "55a62eb48d7127722432c69b",
"first_name": "Test",
"last_name": "Test",
"email": "test@test.com",
"reference": "CustomReference"
},
"statistics": {
"total_collected_amount": 10,
"successful_transactions": 1
},
"schedule": {
"first_assessment": "2015-07-15T09:58:12.441Z",
"interval": "day",
"last_assessment": "2015-07-15T09:58:19.120Z",
"next_assessment": "2015-07-16T09:58:12.441Z",
"start_date": "2015-07-15T09:58:12.441Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD",
"gateway_type": "Ezidebit",
"gateway_name": "Ezidebit label",
"gateway_mode": "test"
}, {
"_id": "55a51a57ec20ac8423273da3",
"amount": 90,
"company_id": "559241db556cc23c1ed3770b",
"created_at": "2015-07-14T14:19:03.378Z",
"status": "active",
"updated_at": "2015-07-14T14:19:11.368Z",
"user_id": "559241db556cc23c1ed3770a",
"archived": false,
"customer": {
"customer_id": "55a51a24ec20ac8423273d9e",
"first_name": "test",
"last_name": "test",
"email": "test@test.com"
},
"statistics": {
"total_collected_amount": 90,
"successful_transactions": 1
},
"schedule": {
"end_date": "2015-08-20T00:00:00.000Z",
"first_assessment": "2015-07-14T14:19:03.370Z",
"interval": "day",
"last_assessment": "2015-07-14T14:19:11.365Z",
"next_assessment": "2015-07-15T14:19:03.370Z",
"start_date": "2015-07-14T14:19:03.370Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD",
"gateway_type": "Authorize",
"gateway_name": "Authorize label",
"gateway_mode": "test"
}, {
"_id": "55a02ca8e0ssddf02395cf41",
"amount": 55,
"company_id": "559241db55ssc23c1ed3770b",
"created_at": "2015-07-10T20:35:52.593Z",
"status": "active",
"updated_at": "2015-07-10T20:36:14.386Z",
"user_id": "559241db556cc23c1ed3770a",
"archived": false,
"customer": {
"customer_id": "55a02c86e05cddf02395cf3c",
"first_name": "test",
"last_name": "test",
"email": "test@test.com",
"reference": "CustomReference"
},
"statistics": {
"total_collected_amount": 55,
"successful_transactions": 1
},
"schedule": {
"first_assessment": "2015-07-10T20:35:52.585Z",
"interval": "day",
"last_assessment": "2015-07-10T20:36:14.384Z",
"next_assessment": "2015-07-15T20:35:52.585Z",
"start_date": "2015-07-10T20:35:52.585Z",
"status": "complete",
"locked": false,
"completed_count": 1,
"retry_count": 0,
"frequency": 5
},
"currency": "AUD",
"gateway_type": "Securepay",
"gateway_name": "Secur label",
"gateway_mode": "test"
}
],
"count": 30,
"limit": 3,
"skip": 0
}
}
GET /v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}
Retrieving data on existing subscriptions can be driven by number of action parameters set in URI path.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n payments from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| search | Text search parameter (search in fields firstname, lastname, email) | String, optional |
| sortkey | Sorting key parameter i.e. firstname, lastname, email, startdate, ASC direction by default | String, optional |
| sortdirection | Sorting order direction parameter (ASC by default, only value that affects is DESC) | String, optional |
| customer_id | PayDock Customer’s ID | String, optional |
| gateway_id | ID of a gateway with which subscriptions were created | String, optional |
| status | Status could be: active, expired, failed, deleted | String, optional |
Get subscription item details
Retrieves data on subscription with specified ID.
GET /v1/subscriptions/{_id}
curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions/:id';
$apiKey = 'user_secret_key';
$subscriptionId = 'subscription_id';
$resultLink = str_replace(':id', $subscriptionId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "subscription",
"data": {
"created_at": "2015-07-24T11:51:30.211Z",
"updated_at": "2015-07-24T11:51:30.211Z",
"user_id": "559241db556cc23c1ed3770a",
"company_id": "559241db556cc23c1ed3770b",
"amount": 10,
"description": "Custom description",
"reference": "Custom reference",
"status": "active",
"_id": "55b226c273065f9423a45d8d",
"archived": false,
"customer": {
"customer_id": "55b226c173065f9423a45d8b",
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"reference": "CustomReference",
"payment_source": {
"gateway_name": "Ezidebit label",
"gateway_type": "Ezidebit",
"gateway_mode": "test",
"updated_at": "2015-07-24T11:51:30.207Z",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "5592499f556cc23c1ed37710",
"account_name": "Test",
"account_bsb": 32000,
"account_number": "XXXX00",
"ref_token": "762958",
"status": "active",
"created_at": "2015-07-24T11:51:30.205Z",
"_id": "55b226c273065f9423a45d8c",
"type": "bsb"
}
},
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"schedule": {
"interval": "day",
"start_date": "2015-07-25T00:00:00.000Z",
"end_date": "2016-08-25T00:00:00.000Z",
"next_assessment": "2015-07-25T00:00:00.000Z",
"first_assessment": "2015-07-25T00:00:00.000Z",
"status": "inprogress",
"locked": false,
"completed_count": 0,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
| Field Name | Description | Details |
|---|---|---|
| _id | Identifier of particular subscription | String, required |
Delete subscription
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions/{_id}',
method: "DELETE",
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/subscriptions/:id';
$apiKey = 'user_secret_key';
$subscriptionId = 'subscription_id';
$resultLink = str_replace(':id', $subscriptionId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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": "subscription",
"data": {
"_id": "585ba520e45b75bc368087ab",
"created_at": "2016-12-22T10:04:16.139Z",
"updated_at": "2016-12-22T10:18:57.948Z",
"amount": 17,
"description": "Custom description",
"reference": "Custom reference",
"payment_source_id": "585ba516e45b75bc368087a9",
"status": "deleted",
"archived": false,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Oleg",
"last_name": "cCdekrigin",
"email": "chcsviginolegsdsd12f@gmail.com",
"phone": "+123451678910"
},
"statistics": {
"total_collected_amount": 27,
"successful_transactions": 2
},
"schedule": {
"interval": "year",
"start_date": "2016-12-22T10:16:55.697Z",
"end_date": null,
"next_assessment": "2017-12-22T10:16:55.697Z",
"next_assessment_planned": "2017-12-22T10:16:55.697Z",
"first_assessment": "2016-12-22T10:16:55.697Z",
"status": "complete",
"last_assessment": "2016-12-22T10:17:41.088Z",
"end_amount_after": null,
"end_amount_before": null,
"end_amount_total": null,
"end_transactions": null,
"locked": false,
"completed_count": 2,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
DELETE /v1/subscriptions/{_id}
Removes a subscription with specified ID.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment identifier | String, required |
Notifications
Notifications are automated messages that are triggered in response to events within the system.
Within PayDock, notification triggers are set up to fire on different events. Notification triggers can have have different types (i.e. Webhook, Email, Sms) and events (i.e. Transaction Success).
Notifications for email and SMS require templates for the notification.
See also Examples of webhook payloads
Notification Templates also provide swap values (eg {{PHONE}} or {{EMAIL}}) that will be populated from the customer, charge or subscription that triggered the notification (See Swap Values for templates for the full list).
Add new notification template
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates',
body: {
"label":"Sms first template",
"notification_event":"transaction_success",
"body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
"destination":"{{{PHONE}}}",
"type":"sms"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/templates';
$apiKey = 'user_secret_key';
$data = json_encode([
'label' =>'Sms first template',
'notification_event' =>'transaction_success',
'body' =>'Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.',
'destination' =>'{{PHONE}}',
'type' =>'sms'
]);
$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));
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "template",
"data": {
"__v": 0,
"created_at": "2016-12-21T09:07:56.100Z",
"updated_at": "2016-12-21T09:07:56.100Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
"_id": "585a466c9af8e1811517afc3"
}
}
}
POST /v1/notifications/templates
Create a notification template (available only in email and SMS type of notifications).
| Name | Description | Details |
|---|---|---|
| body | Use custom text or/and predefined variables, in which PayDock automatically pulls values from customer, charge or subscription data objects. | String, required |
| label | Name of current template to identify it further | String, required |
| notification_event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
| html | Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is false | Boolean, optional |
Edit notification template
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
body: {
"label":"Sms first template",
"notification_event":"transaction_success",
"body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
"destination":"{{{PHONE}}}",
"type":"sms"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/templates/:id';
$apiKey = 'user_secret_key';
$templateId = 'template_id';
$data = json_encode([
'label' =>'Sms first template. Edit.',
'notification_event' =>'transaction_success',
'body' =>'Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created. Edit.',
'destination' =>'{{PHONE}}',
'type' =>'sms'
]);
$resultLink = str_replace(':id', $templateId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $resultLink);
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));
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "template",
"data": {
"created_at": "2016-12-22T09:19:35.577Z",
"updated_at": "2016-12-22T09:19:44.221Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
"_id": "585b9aa7bce8378c54a8a61e"
}
}
}
POST /v1/notifications/templates/{_id}
Update a notification template (available only in email and SMS type of notifications).
| Name | Description | Details |
|---|---|---|
| _id | ID of notification template | String, required |
| body | Use custom text or/and predefined variables, in which PayDock automatically pull values from customer, charge or subscription data objects. | String, required |
| label | Name of current template to identify it further | String, required |
| notification_event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
| html | Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is ‘false’ | Boolean, optional |
Delete notification template
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/templates/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/templates/:id';
$apiKey = 'user_secret_key';
$templateId = 'template_id';
$resultLink = str_replace(':id', $templateId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "template",
"data": {
"created_at": "2016-01-21T10:50:54.403Z",
"updated_at": "2016-01-21T10:52:32.665Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created. ",
"_id": "56a0b80e489dc5402557d5e3"
}
}
}
DELETE /v1/notifications/templates/{_id}
Delete a notification template.
| Name | Description | Details |
|---|---|---|
| _id | Template ID | String, required |
Add notification trigger
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications',
body: {
"event":"transaction_success",
"destination":"http://webhooks.com/",
"type":"webhook"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications';
$apiKey = 'user_secret_key';
$data = json_encode([
'event' => 'transaction_success',
'destination' => 'http://webhooks.com/',
'type' => 'webhook'
]);
$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));
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"event\":\"transaction_success\",\"destination\":\"http://webhooks.com\,\"type\":\"webhook\"
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "notification",
"data": {
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "55a634a48d7127722432c6a6"
}
}
}
POST /v1/notifications
Created a trigger to send a notification to a customer or endpoint. To send an email or SMS to a customer, use swap values (eg {{PHONE}} or {{EMAIL}}) which are loaded from the customer (See Swap Values for templates for the full list).
| Name | Description | Details |
|---|---|---|
| type | type of notification: ‘webhook’, ‘email’, ‘sms’ | String, required |
| destination | Where to send notification (URL for webhook, email address for email ({{EMAIL}} for current customer), phone number in international E.164 format ({{PHONE}} for current customer)) | String, required |
| template_id | Custom template, which can be used with email or sms notifications. | String, required for email or sms |
| event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
Get notification trigger list
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/notifications',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications';
$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));
?>
"Examle of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "notifications",
"data": [
{
"event": "transaction_failure",
"destination": "test@test.com",
"type": "email",
"_id": "55a00fe0aeb7e987239b47a9"
},
{
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "55a634a48d7127722432c6a6"
}
],
"count": 2,
"limit": 0,
"skip": 0
}
}
GET /v1/notifications
Returns all notification triggers for the account, limited to 100 records.
Get notification trigger
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/:id';
$apiKey = 'user_secret_key';
$notificationId = 'notification_id';
$resultLink = str_replace(':id', $notificationId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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": "notification",
"data": {
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "585ba240e45b75bc3680879e"
}
}
}
GET /v1/notifications/{_id}
Retrive details on a specific notification.
| Name | Description | Details |
|---|---|---|
| _id | Notification ID | String, required |
Delete notification trigger
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/notifications/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/:id';
$apiKey = 'user_secret_key';
$notificationId = 'notification_id';
$resultLink = str_replace(':id', $notificationId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "notification",
"data": {
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "585ba240e45b75bc3680879e"
}
}
}
DELETE /v1/notifications/{_id}
Remove a notification.
| Name | Description | Details |
|---|---|---|
| _id | Notification ID | String, required |
Get user notification log
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/logs?success=true&type=email&event=transaction_failure&created_at.from=2015-10-01&created_at.to=2016-11-09T10:17:39.016Z&parent_id=560e7abed81ed5da267cf3a6" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/logs?[params]',
body: {
"success": "boolean",
"type": "String",
"event": "String",
"_id": "String",
"parent_id": "String",
"created_at.from": "String",
"created_at.to": "String",
"destination": "String"
},
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/logs';
$apiKey = 'user_secret_key';
$query = http_build_query([
'created_at.from' => '2017-01-01',
'created_at.to' => '2018-01-31'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "notification_logs",
"data": [
{
"created_at": "2015-10-02T13:53:35.114Z",
"success": true,
"type": "email",
"destination": "envoynotific@gmail.com",
"notification_id": "560e7abed81ed5da267cf3a6",
"parent_id": "560e7abed81ed5da267cf3a6",
"event": "transaction_failure",
"response_status": "OK",
"_id": "560e8c5fd81ed5da267cf3af",
"archived": false
},
{
"created_at": "2015-10-02T13:53:31.253Z",
"success": true,
"type": "email",
"destination": "envoynotific@gmail.com",
"notification_id": "560e7abed81ed5da267cf3a6",
"parent_id": "560e7abed81ed5da267cf3a6",
"event": "transaction_failure",
"response_status": "OK",
"_id": "560e8c5bd81ed5da267cf3ae",
"archived": false
},
{
"created_at": "2015-10-02T13:53:25.579Z",
"success": true,
"type": "email",
"destination": "envoynotific@gmail.com",
"notification_id": "560e7abed81ed5da267cf3a6",
"parent_id": "560e7abed81ed5da267cf3a6",
"event": "transaction_failure",
"response_status": "OK",
"_id": "560e8c55d81ed5da267cf3ad",
"archived": false
}
],
"count": 3,
"limit": 100,
"skip": 0
}
}
GET /v1/notifications/logs?success=true&type=email&event=transaction_failure&created_at.from={yyyy-mm-dd}&created_at.to={yyyy-mm-dd}&parent_id={parent_id}
Retrieve list of all notifications, with parameter list
| Name | Description | Details |
|---|---|---|
| _id | Parameter to show specific notification details | String, optional |
| success | Parameter to filter success or failed notifications. Values: true/false | String, optional |
| event | Parameter to filter notification events. Values: transaction_success, transaction_failure, subscription_creation_succes , subscription_creation_failure, subscription_updated, refund_requested, refund_successful, refund_failure, card_expiration_warning | String, optional |
| type | Parameter to show notifications of specific type. Values: email, webhook | String, optional |
| created_at.from | Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | String, optional |
| created_at.to | Parameter to filter notifications date range. Format: ISO 8601 (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | String, optional |
| parent_id | Used to search for notifications that have been resent, represents the id of the failed notification | String, optional |
| destination | Shows email address or webhook URL. | String, optional |
Archive notification log
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/notifications/logs/:id';
$apiKey = 'user_secret_key';
$notificationLogId = 'notification_log_id';
$resultLink = str_replace(':id', $notificationLogId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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 (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "charge",
"data": {
"company_id": "5584018a27b2cf0b1e4f1a6c",
"created_at": "2015-10-05T06:03:14.121Z",
"success": true,
"type": "email",
"destination": "test@email.com",
"notification_id": "560fcc0dd81ed5da267cf4f3",
"parent_id": "560fcc0dd81ed5da267cf4f3",
"event": "transaction_failure",
"response_status": "OK",
"_id": "561212a2d81ed5da267cf688",
"__v": 0,
"archived": true
}
}
}
DELETE /v1/notifications/logs/{_id}
Archive remove a notification log.
| Name | Description | Details |
|---|---|---|
| _id | Notification ID | String, required |
Tokens
POST /v1/payment_sources/tokens?public_key=[your_public_key]
One-time token represents payment source information including Credit Сards or Direct Debit account details. It is a disposable token for creating charges/subscriptions/customers or updating customers.
Tokens can also be created using:
Here is an example of creating one-time token using direct API request:
curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"first_name\":\"Test_first_name\",\"last_name\":\"Test_last_name\",\"phone\":\"+12345678910\",\"address_line1\":\"Testline1\",\"address_line2\":\"Testline2\",\"address_city\":\"Testcity\",\"address_state\":\"Teststate\",\"address_country\":\"AU\",\"address_postcode\":\"1324\",\"gateway_id\":\"551bb4af43daf16f355ab259\",\"card_name\":\"Test User\",\"card_number\":\"4200000000000000\",\"expire_month\":\"01\",\"expire_year\":\"17\",\"card_ccv\":\"123\"}"
"Credit Сards example"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]',
method: 'POST',
body: {
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"phone":"+12345678910",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Test User",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"17",
"card_ccv":"123"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Direct Debit example"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]',
method: 'POST',
body: {
"first_name": "Test_first_name",
"last_name": "Test_last_name",
"email": "test@test.com",
"phone":"+12345678910",
"address_line1": "Testline1",
"address_line2": "Testline2",
"address_city": "Testcity",
"address_state": "Teststate",
"address_country": "AU",
"address_postcode": "1234",
"type":"bsb",
"gateway_id": "584125e4990f62cf1457996a",
"account_name":"Test User",
"account_number":"064000",
"account_bsb":"064000"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/payment_sources/tokens';
$apiPublicKey = 'user_public_key';
$query = http_build_query([
'public_key' => $apiPublicKey
]);
$data = json_encode([
'first_name' => 'Test_first_name',
'last_name' => 'Test_last_name',
'email' => 'test@test.com',
'phone' => '+12345678910',
'address_line1' => 'Testline1',
'address_line2' => 'Testline2',
'address_city' => 'Testcity',
'address_state' => 'Teststate',
'address_country' => 'AU',
'address_postcode' => '1234',
'gateway_id' => '551bb4af43daf16f355ab259',
'card_name' => 'Test User',
'card_number' => '4200000000000000',
'expire_month' => '05',
'expire_year' => '17',
'card_ccv' => '123'
]);
$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),
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "token",
"data": "b76c51ed-9c00-4997-903d-54842826269a"
}
}
| Field Name | Description | Detailsß |
|---|---|---|
| gateway_id | Gateway ID | String, required |
| type | Type of payment. Use ‘bsb’ to post with bsb account and ‘card’ for payments with credit cards. Use ‘bank_account’ for using bank account credentials. Parameter required when using direct Debit | String, required |
| card_name | Cardholder name (as on card) | String, required for card |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | Integer, required for card |
| expire_year | Card expiration year yyyy format | Integer, required for card |
| card_ccv | Card CCV number | Integer, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| address_city | Customer Address, City | String, optional |
| address_postcode | Customer Address, Postcade | Integer, optional |
See also Required fields by Gateway
Gateways
PayDock enables multiple gateways to be connected to a single PayDock account, see our list of Supported Gateways
Gateways can be added through the API where the third-party gateway supports it or through the PayDock Admin Portal.
Before assigning a gateway to a company, there should be an account registered with required gateway in their system, where specific data can be found (gateway token, merchant ID, etc.).
Add new payment gateway
curl -X "POST" "https://api-sandbox.paydock.com/v1/gateways" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"type\":\"Gateway Type\",\"name\":\"Gateway Name\",\"username\":\"Gateway Username\",\"password\":\"Gateway Password\"}"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways',
body: {
"type": "PromisePay",
"name": "Promise Pay",
"username": "username",
"password": "password",
"mode": "test"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways';
$apiKey = 'user_secret_key';
$data = json_encode([
'type' => 'PromisePay',
'name' => 'Promise Pay',
'username' => 'username',
'password' => 'password',
'mode' => 'test'
]);
$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 Response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "gateway",
"data": {
"created_at": "2017-01-11T07:00:28.869Z",
"updated_at": "2017-01-11T07:00:28.869Z",
"type": "PromisePay",
"name": "Promise Pay",
"username": "username",
"password": "user's password",
"_id": "5875d80c85ad563f58a9eebc",
"mode": "test"
}
}
}
POST /v1/gateways
You can add a gateway account more than once, by using a different name each time.
Each of the different gateways require a different set of parameters to add them, see the detailed list below.
eWay
| Name | Description | Details |
|---|---|---|
| type | value : ‘Eway’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Braintree
| Name | Description | Details |
|---|---|---|
| type | value : ‘Brain’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | The merchant account ID | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Ezidebit
| Name | Description | Details |
|---|---|---|
| type | value : ‘Ezidebit’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Stripe
| Name | Description | Details |
|---|---|---|
| type | value : ‘Stripe’ | String, required |
| name | Name which will be presented gateway | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
PayPal
| Name | Description | Details |
|---|---|---|
| type | value : ‘Paypal’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Pin
| Name | Description | Details |
|---|---|---|
| type | value : ‘Pin’ | String, required |
| name | Name which will be presented gateway | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
PayWay
| Name | Description | Details |
|---|---|---|
| type | value : ‘PaywayRest’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Merchant Code | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
SecurePay
| Name | Description | Details |
|---|---|---|
| type | value : ‘Securepay’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Authorize.net
| Name | Description | Details |
|---|---|---|
| type | value : ‘Authorize’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | User name of gateway side | String, required |
| key | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Payment Express
| Name | Description | Details |
|---|---|---|
| type | value : ‘Paymentexpress’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
WorldPay
| Name | Details | Description |
|---|---|---|
| type | value : ‘Worldpay’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
NAB
| Name | Description | Details |
|---|---|---|
| type | value : ‘Nab’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Merchant Warrior
| Name | Description | Details |
|---|---|---|
| type | value : ‘Merchantwarrior’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
SQID
| Name | Description | Details |
|---|---|---|
| type | value : ‘Sqid’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Merchant Code | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
PromisePay
| Name | Description | Details |
|---|---|---|
| type | value : ‘PromisePay’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Forte
| Name | Description | Details |
|---|---|---|
| type | value : ‘Forte’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| merchant | Merchant Id of gateway side | String, required |
| signature | Signature of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
IpPayments
| Name | Description | Details |
|---|---|---|
| type | value : ‘IpPayments’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | User name of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
Get payment gateway
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways/:id';
$apiKey = 'user_secret_key';
$gatewayId = 'gateway_id';
$resultLink = str_replace(':id', $gatewayId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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));
?>
curl -X "GET" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
"Example of Response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "gateway",
"data": {
"_id": "582eb40446ab09c34205bc82",
"created_at": "2016-11-18T07:55:48.007Z",
"merchant": "r7pcwvkbkgjfzk99",
"name": "Braintreee",
"password": "password",
"type": "Brain",
"updated_at": "2016-12-16T11:44:23.356Z",
"username": "username",
"mode": "test",
"active_subscriptions": 0
}
}
}
GET /v1/gateways/{_id}
Retrieves data on a gateway with specified ID.
Parametrs
| Name | Description | Details |
|---|---|---|
| _id | Gateway Identifier | String, required |
Update gateway
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways/{_id}',
body: {
"name": "String",
"username": "String",
"password": "String"
},
method: 'PUT',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways/:id';
$apiKey = 'user_secret_key';
$gatewayId = 'gateway_id';
$data = json_encode([
'name' => 'string',
'username' => 'username',
'password' => 'password'
]);
$resultLink = str_replace(':id', $gatewayId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $resultLink);
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));
?>
curl -X "PUT" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Gateway Name\",\"username\":\"Gateway Username\",\"password\":\"Gateway Password\"
"Example Response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "gateway",
"data": {
"created_at": "2016-12-22T09:02:35.491Z",
"updated_at": "2016-12-22T09:07:16.227Z",
"type": "PromisePay",
"name": "PromisePay Update",
"username": "username",
"password": "password",
"_id": "585b96abe45b75bc36808739",
"mode": "test"
}
}
}
PUT /v1/gateways/{_id}
Updates configuration for a gateway.
eWay
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Braintree
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Ezidebit
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Stripe
| Name | Details |
|---|---|
| name | String, required |
| password | String, required |
| mode | String, required |
PayPal
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Pin
| Name | Details |
|---|---|
| name | String, required |
| password | String, required |
| mode | String, required |
PayWay
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| username | String, required |
| password | String, required |
| Gateway Certificate PassPhrase | String, required |
| Gateway Certificate Id | String, required |
| mode | String, required |
| Certificate file | File, required |
SecurePay
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| password | String, required |
| mode | String, required |
Authorize.net
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| key | String, required |
| mode | String, required |
Payment Express
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
WorldPay
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
NAB
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Merchant Warrior
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| password | String, required |
| mode | String, required |
SQID
| Name | Details |
|---|---|
| name | String, required |
| merchant | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
PromisePay
| Name | Details |
|---|---|
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, required |
Forte
| Name | Details |
|---|---|
| type | String, required |
| name | String, required |
| username | String, required |
| merchant | String, required |
| signature | String, required |
| password | String, required |
| mode | String, optional |
IpPayments
| Name | Details |
|---|---|
| type | String, required |
| name | String, required |
| username | String, required |
| password | String, required |
| mode | String, optional |
Get gateway list
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways';
$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));
?>
curl -X "GET" "https://api-sandbox.paydock.com/v1/gateways" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "gateways",
"data": [
{
"_id": "582eb40446ab09c34205bc82",
"created_at": "2016-11-18T07:55:48.007Z",
"merchant": "r7pcwvkbkgjfzk99",
"name": "Braintreee",
"password": "password",
"type": "Brain",
"updated_at": "2016-12-21T08:11:36.260Z",
"username": "username",
"mode": "test"
},
{
"_id": "5853d3974f76d26c24e69165",
"created_at": "2016-12-16T11:44:23.356Z",
"name": "Promise Pay",
"password": "password",
"type": "PromisePay",
"updated_at": "2016-12-21T08:11:36.261Z",
"username": "username",
"mode": "test"
}
],
"count": 2,
"limit": 0,
"skip": 0
}
}
GET /v1/gateways
Returns all gateways for the account, limited to 100 records.
Delete gateway
var request = require('request');
request({
url: 'https://api.paydock.com/v1/gateways/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/gateways/:id';
$apiKey = 'user_secret_key';
$gatewayId = 'gateway_id';
$resultLink = str_replace(':id', $gatewayId, $apiLink);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_URL, $resultLink);
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));
?>
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "gateway",
"data": {
"created_at": "2016-12-22T09:02:35.491Z",
"updated_at": "2016-12-22T09:07:16.227Z",
"type": "PromisePay",
"name": "PromisePay Update",
"username": "username",
"password": "password",
"_id": "585b96abe45b75bc36808739",
"mode": "test"
}
}
}
DELETE /v1/gateways/{_id}
Removes gateway with specified ID. A gateway cannot be removed if it has subscriptions running through it.
| Name | Description | Details |
|---|---|---|
| _id | Gateway Identifier | String, required |
Development SDKs
PayDock provides SDKs or libaries for different programming languages to make integration as simple as possible.
Client side
Client SDK
The solution for convenient and easy work with iframe
The documentation by Client SDK
Also the Client SDK is available through npm
More detailed documentation by classes and methods available through: reference by class
PayDock.js
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.
The documentation by Client SDK
.Net SDK
The .Net SDK is available through nuget
This is also open sourced, 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 (see Authentication)
Also you will need added gateway (see API Reference by gateway)
Get started
Download from CDN
<script src="https://app.paydock.com/v1/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://app.paydock.com/v1/widget.umd.min.js
Full version for development and debug
https://app.paydock.com/v1/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 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', 'gatewayId');
widget.load();
// ES2015 | TypeScript
import { HtmlWidget } from '@paydock/client-sdk/widget';
var widget = new HtmlWidget('#widget', 'publicKey', 'gatewayId');
widget.load();
Then write only need 2 lines of code in js to initialize widget
Full example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<style>iframe {border: 0;width: 100%;height: 300px;}</style>
</head>
<body>
<div id="widget"></div>
<script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
<script>
var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
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>
<div id="widget"
widget-style="text-color: #FFFFAA; border-color: #yellow"
title="Payment form"
finish-text="Payment resource was successfully accepted"></div>
<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
widget.setSupportedCardIcons(['mastercard', 'visa']);
widget.setFormFields(['phone', 'email']);
widget.setRefId('custom-ref-id');
widget.load();
</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/widget';
var list = new HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
list.load();
Then write only need 2 lines of code in js to initialize widget
Full example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<style>iframe {border: 0;width: 40%;height: 300px;}</style>
</head>
<body>
<div id="list"></div>
<script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
<script>
var list = new paydock.HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
list.load();
</script>
</body>
</html>
Payment sources advanced example
Customization
list.setStyles({
icon_size: 'small'
});
This example shows how you can customize to your needs and design
Settings
list.filterByTypes(['card', 'checkout']); // filter by any payment source types
list.filterByGatewayIds(['gateway1']); // also other filters
list.setRefId('id'); // your unique identifier to identify the data
list.setLimit(4); // Pagination elements will show if count of elements more then argument passed
list.onSelectInsert('input[name="ps_id"]', 'payment_source_id'); // insert one-time-token to your input after finish checkout
list.on('select', function(data) {
console.log(data);
});
This example shows how you can use a lot of other methods to settings your form
Full example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<style>iframe {border: 0;width: 40%;height: 300px;}</style>
</head>
<body>
<div id="list"></div>
<input type="text" name="ps_id" />
<script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
<script>
var list = new paydock.HtmlPaymentSourceWidget('#list', 'publicKey', 'queryToken');
list.filterByTypes(['card', 'checkout']);
list.filterByGatewayIds(['gateway1']);
list.setRefId('id');
list.setLimit(4);
list.setStyles({
icon_size: 'small'
});
list.load();
list.onSelectInsert('input[name="ps_id"]', 'payment_source_id');
list.on('select', function(data) {
console.log(data);
});
</script>
</body>
</html>
Checkout button
You can find description of all methods and parameters here PayPal meta parameters description here PayPal 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.CheckoutButton('#button', 'publicKey', 'gatewayId');
// ES2015 | TypeScript
var button = new CheckoutButton('#widget', 'publicKey', 'gatewayId');
Then write only need 2 lines of code in js to initialize widget
Full example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<button type="button" id="button">checkout</button>
<script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
<script>
var button = new paydock.CheckoutButton('#button', 'publicKey', 'gatewayId');
</script>
</body>
</html>
Checkout button advanced example
Optional methods
button.onFinishInsert('input[name="pst"]', 'payment_source_token'); // insert one-time-token to your input after finish checkout
button.setMeta({
brand_name: 'Paydock',
reference: '15',
first_name: 'receiver-name',
last_name: 'receiver-last-name',
phone: '9379992'}); // settings for checkout pages
button.on('finish', function (data) { // Add handler of event
console.log('on:finish', data);
});
This example shows how you can use a lot of other methods to settings your button
Full Paypal example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<button type="button" id="button">
<img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" align="left" style="margin-right:7px;">
</button>
<input type="text" name="pst" />
<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
var button = new paydock.CheckoutButton('#button', 'publicKey', 'gatewayId');
button.onFinishInsert('input[name="pst"]', 'payment_source_token');
button.setMeta({
brand_name: 'Paydock',
reference: '15',
first_name: 'receiver-name',
last_name: 'receiver-last-name',
phone: '9379992'});
button.on('finish', function (data) {
console.log('on:finish', data);
});
</script>
</body>
</html>
Full ZipMoney example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
<button type="button" id="button">
<img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTVrrEYxDmq4WXv7hfHygKD9ltnOqv0K6soSAhmbKNllPNYWiLiJA" align="left" style="margin-right:7px;">
</button>
<input type="text" name="pst" />
<script src="https://app.paydock.com/v1/widget.umd.js" ></script>
<script>
var button = new paydock.ZipmoneyCheckoutButton('#button', 'publicKey', 'gatewayId');
button.onFinishInsert('input[name="pst"]', 'payment_source_token');
button.setMeta("first_name": "Test",
"tokenize": true,
"last_name": "Lname",
"email":"test@test.com",
"gender": "male",
"charge": {
"amount": "4",
"currency":"AUD",
"shipping_address": {
"first_name": "Test",
"last_name": "Lname",
"line1": "test",
"line2": "test",
"country": "AU",
"postcode": "3223",
"city": "Sydney",
"state": "LA"
},
"billing_address": {
"first_name": "Test",
"last_name": "Lname",
"line1": "test",
"line2": "test",
"country": "AU",
"postcode": "3223",
"city": "Sydney",
"state": "LA"
},
"items": [
{
"name":"Shoess",
"amount":"2",
"quantity": 1,
"reference":"sds"
},
{
"name":"Shoess2",
"amount":"2",
"quantity": 1,
"reference":"sds1"
}
]
},
"statistics": {
"account_created": "2017-05-05",
"sales_total_number": "5",
"sales_total_amount": "4",
"sales_avg_value": "45",
"sales_max_value": "400",
"refunds_total_amount": "21",
"previous_chargeback": "true",
"currency": "AUD",
"last_login": "2017-06-01"
});
button.on('finish', function (data) {
console.log('on:finish', data);
});
</script>
</body>
</html>
PayPal Integration
Our recommended approach for Paypal integration is to use our Client SDK. This handles most of the complexity of integrating Paypal into your plaform. You can implement PayPal manually, in the process below.
PayPal checkout allows your customers to pay using PayPal. The PayPal checkout process creates a one-time token that can be used to add a payment source to a customer, create a customer or charge a customer.
The process for taking a payment with PayPal checkout is:
- Call /v1/payment_sources/external_checkout with a redirect URL, which will return a custom PayPal checkout link. Provide a way for the customer to visit this URL (eg pay with pay pal button)
- When the customer visits this URL, they will be promoted to log into their PayPal account, then is sent to the redirect URL.
- Collect the PayPal token from the URL.
- Call /v1/payment_sources/tokens to create a single use token. This token can be used to add a payment source to a customer, create a customer or charge a customer.
Create checkout link
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
$apiLink = 'https://api-sandbox.paydock.com/v1/payment_sources/external_checkout';
$apiKey = 'user_secret_key';
$data = json_encode([
'mode' => 'test',
'gateway_id' => '583d7c75a1723f941b7137f4',
'success_redirect_url' => 'https://docs.paydock.com',
'error_redirect_url' => 'https://docs.paydock.com/charges.php',
'description' => 'Test Paydock description'
]);
$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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"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 |
| The consumer’s email | String, optional | |
| hdr_img | URL for the image you want to appear at the top left of the payment page | String, optional |
| logo_img | A URL to your logo image | String, optional |
| first_name | The consumer’s given names | String, optional |
| last_name | The consumer’s surname | String, optional |
| address_line | Street address | String, optional |
| address_line2 | Second line of the address | String, optional |
| address_city | City | String, optional |
| address_postcode | Postcode | String, optional |
| hide_shipping_address | Determines whether PayPal displays shipping address fields on the PayPal pages | String, optional |
| phone | The consumer’s phone number in E.164 international notation (Example: +12345678901) | String, optional |
Create PayDock one-time token using PayPal checkout token
curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]" \
-H "Content-Type: application/json" \
-d "{\"type\":\"checkout_token\",\"gateway_id\":\"583d78caa17233341b712bbc\",\"checkout_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I\"}"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]',
method: 'POST',
body: {
"type":"checkout_token",
"gateway_id":"583d78caa17233341b712bbc",
"checkout_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I"
},
headers: {
'content-type' : 'application/json'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[users_public_key]';
$apiPublicKey = 'user_public_key';
$query = http_build_query([
'public_key' => $apiPublicKey
]);
$data = json_encode([
'type' => 'checkout_token',
'gateway_id' => '583d78caa17233341b712bbc',
'checkout_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGF5cGFsIiwiZ2F0ZXdheV9pZCI6IjU4M2JlYjViYTIzMjc3ZjYxOTExZjg2YiIsImdhdGV3YXlfdHlwZSI6IlBheXBhbENsYXNzaWMiLCJzcGVjaWZpY0RhdGEiOnsiY2hlY2tvdXRfdG9rZW4iOiJFQy0xMkQ3NjUyN0JLMDM1OTEzWSJ9LCJtb2RlIjoidGVzdCIsImlhdCI6MTQ4MDQ1MjI5MH0.DN5eLG-VyAIcQJlkBRX0NHav5svPQ4jrM_u0V9QRD1I'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink . '?' . $query);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Content-Length: ". strlen($data),
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "token",
"data": "bb7fcdfc-1322-sdd8-adba-2c265adb8b25"
}
}
Before initiating a call to create a one-time token for PayPal, the user must have created a PayPal checkout token using the checkout link. The response returns a one-time token that can be used to:
POST /v1/payment_sources/tokens?public_key=[users_public_key]
| Field Name | Description | Details |
|---|---|---|
| type | Type of payment source gateway to be created. Available values: “checkout_token” | String, required |
| gateway_id | Id of a gateway, that was previously added to PayDock | String, required |
| public_key | PayDock users public key | String, required |
| checkout_token | Token, that was created on previously step. | String, required |
Afterpay Integration
Afterpay checkout allows your customers to pay using Afterpay. The Afterpay checkout process creates a one-time token that can be used to add a direct payment.
Before allowing a customer to checkout with Afterpay, check the configuration for Afterpay to ensure that this order will be accepted successfully. You can do this by calling (Afterpay configuration)[#afterpay-configuration]. The configuration does not need to be checked before every order, but it should be checked regularly (eg every day).
The process for taking a payment with Afterpay checkout is:
- Call /v1/payment_sources/external_checkout with a redirect URL, which will return a custom Afterpay checkout link. Provide a way for the customer to visit this URL (eg pay with Afterpay button)
- When the customer visits this URL, they will be promoted to log into their Afterpay account, then is sent to the redirect URL.
- Collect the Afterpay token from the URL.
- Call /v1/payment_sources/tokens to create a single use token. This token can be used to add a direct payment.
Create checkout link
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\”: \”test@test.com\”, \”first_name\”: \”testFirstName\”, \”last_name\”: \”testLastName\”, \”address_line1\”: \”AddrLine1\”, \”address_line2\”: \”AddrLine2\”, \”address_city\”: \”AddrCity\”, \”address_state\”: \”NSW\”, \”address_postcode\”: \“1234\”, \”address_country\”: \”AddrCountry\”, \”phone\”: \”040000000\”} }"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/payment_sources/external_checkout',
method: 'POST',
body: {
"error_redirect_url": "https://docs.paydock.com",
"success_redirect_url": "https://google.com",
"gateway_id":"59003f15eccac620e61aad6c",
"meta":
{
"amount": "20",
"currency": "AUD",
"items":[{
"name": "widget1",
"sku": "1234122346",
"quantity": 1,
"price": {
"amount": "10.00",
"currency": "AUD"
}
},
{ "name": "widget2",
"sku": "1234122345",
"quantity": 1,
"price": {
"amount": "10.00",
"currency": "AUD"
}
}
],
"reference": "testreference",
"email": "test@test.com",
"first_name": "testFirstName",
"last_name": "testLastName",
"address_line1": "AddrLine1",
"address_line2": "AddrLine2",
"address_city": "AddrCity",
"address_state": "NSW",
"address_postcode": "1234",
"address_country": "AddrCountry",
"phone": "040000000"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/payment_sources/external_checkout';
$apiKey = 'user_secret_key';
$data = json_encode([
'error_redirect_url' => 'https://docs.paydock.com',
'success_redirect_url' => 'https://google.com',
'gateway_id' => '59003f15eccac620e61aad6c',
'meta' => [
'amount' => '50',
'currency' => 'AUD',
'reference' => 'testreference',
'email' => 'test@test.com',
'first_name' => 'testFirstName',
'last_name' => 'testLastName',
'address_line1' => 'AddrLine1',
'address_line2' => 'AddrLine2',
'address_city' => 'AddrCity',
'address_state' => 'NSW',
'address_postcode' => '1234',
'address_country' => 'AddrCountry',
'phone' => '040000000'
]
]);
$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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"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 |
| 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:
- Refund transactions (including partial refunds) Refund Charge
- Get status for a single transaction Get Single Charge
- Search for transactions Transaction Search
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 for taking a payment with ZipMoney checkout is:
- Call /v1/payment_sources/external_checkout with a redirect URL, which will return a custom Zip Money checkout link. Provide a way for the customer to visit this URL (eg pay with ZipPay)
- When the customer visits this URL, they will be promoted to log into their Zip Money account or register for a new account. When they’ve completed this they will be sent is sent to the redirect URL.
- Collect the Zip Money token from the URL.
- Call /v1/payment_sources/tokens to create a single use token. This token can be used to add a direct payment or to use as a recurring payment token. Important note: When you set this up as a recurring payment token, this will take a payment for that items selected.
Create checkout link
curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/external_checkout" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"mode\": \"test\",\"gateway_id\":\"59637d35f2aa0c136b0128e2\",\"redirect_url\":\"https://docs.paydock.com\",\"reference\": \"transaction_reference_number\",\"meta\": {\"first_name\": \"Fname\",\"last_name\": \"Lname\",\"tokenize\": true,\"shipping_address\": { \"first_name\": \"Fname\", \"last_name\": \"Lname\", \"line1\": \"1 Help St\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" }, \"billing_address\": { \"first_name\": \"Fname\", \"last_name\": \"Lname\", \"line1\": \"1 Help St\", \"country\": \"AU\", \"postcode\": \"2000\", \"city\": \"Sydney\", \"state\": \"NSW\" },\"amount\": \"4\", \"currency\":\"AUD\",\"reference\":\"transaction_reference\",\"email\":\"email@email.com\",\"items\": [{\"name\":\"Shoes\",\"amount\":\"2\",\"quantity\": 1,\"reference\":\"sds\"},{\"name\":\"Shoes2\",\"amount\":\"2\",\"quantity\": 1,\"reference\":\"sds1\"}],\"statistics\": {\"account_created\": \"2017-05-05\",\"sales_total_number\": \"5\",\"sales_total_amount\": \"4\",\"sales_avg_value\": \"45\",\"sales_max_value\": \"400\",\"refunds_total_amount\": \"1\",\"previous_chargeback\": \"false\",\"currency\": \"AUD\",\"last_login\": \"2017-06-01\"}},\"description\": \"My test PayDock description\"}"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/payment_sources/external_checkout',
method: 'POST',
body: {
"mode": "test",
"gateway_id":"59637d35f2aa0c136b0128e2",
"redirect_url":"https://docs.paydock.com",
"reference": "transaction_reference_number",
"meta": {
"first_name": "Fname",
"last_name": "Lname",
"email":"email@email.com",
"tokenize": true,
"description": "My test PayDock description",
"charge": {
"shipping_address": {
"first_name": "Fname",
"last_name": "Lname",
"line1": "1 Help St",
"country": "AU",
"postcode": "2000",
"city": "Sydney",
"state": "NSW"
},
"billing_address": {
"first_name": "Fname",
"last_name": "Lname",
"line1": "1 Help St",
"country": "AU",
"postcode": "2000",
"city": "Sydney",
"state": "NSW"
},
"amount": "4",
"currency":"AUD",
"items": [{
"name":"Shoes",
"amount":"2",
"quantity": 1,
"reference":"sds"
},
{
"name":"Shoes2",
"amount":"2",
"quantity": 1,
"reference":"sds1"
}],
},
"statistics": {
"account_created": "2017-05-05",
"sales_total_number": "5",
"sales_total_amount": "4",
"sales_avg_value": "45",
"sales_max_value": "400",
"refunds_total_amount": "1",
"previous_chargeback": "false",
"currency": "AUD",
"last_login": "2017-06-01"
}
},
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/payment_sources/external_checkout';
$apiKey = 'user_secret_key';
$data = json_encode([
"mode"=> "test",
"gateway_id"=>"59637d35f2aa0c136b0128e2",
"redirect_url"=>"https=>//docs.paydock.com",
"reference"=> "transaction_reference_number",
"meta"=> [
"first_name"=> "Fname",
"last_name"=> "Lname",
"email"=>"email@email.com",
"tokenize"=> true,
"description"=> "My test PayDock description",
"charge"=> {
"shipping_address"=> [
"first_name"=> "Fname",
"last_name"=> "Lname",
"line1"=> "1 Help St",
"country"=> "AU",
"postcode"=> "2000",
"city"=> "Sydney",
"state"=> "NSW"
],
"billing_address"=> [
"first_name"=> "Fname",
"last_name"=> "Lname",
"line1"=> "1 Help St",
"country"=> "AU",
"postcode"=> "2000",
"city"=> "Sydney",
"state"=> "NSW"
],
"amount"=> "4",
"currency"=>"AUD",
"items"=> [[
"name"=>"Shoes",
"amount"=>"2",
"quantity"=> 1,
"reference"=>"sds"
],
[
"name"=>"Shoes2",
"amount"=>"2",
"quantity"=> 1,
"reference"=>"sds1"
]],
},
"statistics"=> [
"account_created"=> "2017-05-05",
"sales_total_number"=> "5",
"sales_total_amount"=> "4",
"sales_avg_value"=> "45",
"sales_max_value"=> "400",
"refunds_total_amount"=> "1",
"previous_chargeback"=> "false",
"currency"=> "AUD",
"last_login"=> "2017-06-01"
]
],
]);
$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",
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"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:
- Approved
- Delined
- Referred
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 |
| 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:
- Refund transactions (including partial refunds) Refund Charge
- Get status for a single transaction Get Single Charge
- Search for transactions Transaction Search
PayDock.js
Our recommended approach of collecting payment details is to use our Client SDK, which lets you collect payment details securely and maintain compliance. If this is not an option, Paydock.js can 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:
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 |
| 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
The best way to use our iFrame to collect payment details is through our Client SDK. This wraps some of the complexity of creating an iframe in an easy to use javascript library. You can implement the iFrame manually, in 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:
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:
- From Javascript events on the iframe
- From a redirect
- From webhook result
To see a full working example, have a look at this recipe
Creating configuration token from the Web application
You can generate an iframe configuration token through the PayDock Admin Portal:
From here, you can also style and preview your iframe:
Create configuration token with an API call
curl -X "POST https://api-sandbox.paydock.com/v1/remote-action/configs" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"purpose\":\"payment_source\",\"predefined_fields\": {\"gateway_id\":\"1\",\"type\":\"card\"},\"defined_form_fields\": [\"first_name\",\"last_name\",\"email\",\"phone\",\"address_line1\",\"address_line2\",\"address_country\",\"address_city\",\"address_postcode\"]}"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/remote-action/configs',
method: 'POST',
body: {
"purpose": "payment_source",
"defined_form_fields": [
"first_name",
"last_name",
"email",
"phone",
"address_line1",
"address_line2",
"address_country",
"address_city",
"address_postcode"
],
"allowed_response_data": {
"url": ["payment_source"],
"event": ["payment_source"]
},
"webhook_destination": "https://mywebsite.com/my-endpoint",
"success_redirect_url": "https://docs.paydock.com",
"error_redirect_url": "https://docs.paydock.com",
"fields_validation": true,
"supported_card_types": ['ausbc', 'visa', 'mastercard', 'diners', 'japcb', 'laser', 'solo', 'discover', 'amex'],
"hidden_elements": ['submit_button', 'tabs'],
"predefined_fields": {
"gateway_id": "1",
"type": "card"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
$apiLink = 'https://api-sandbox.paydock.com/v1/remote-action/configs';
$apiKey = 'user_secret_key';
$data = json_encode([
'purpose' => 'payment_source',
'predefined_fields' => [
'gateway_id' => '58377235377aea03343240cc',
'type' => 'card'
],
'defined_form_fields' => [
'first_name',
'last_name',
'email',
'phone',
'address_line1',
'address_line2',
'address_country',
'address_city',
'address_postcode'
],
'webhook_destination' => 'https://mywebsite.com/my-endpoint',
'success_redirect_url' => 'https://docs.paydock.com',
'error_redirect_url' => 'https://docs.paydock.com',
'fields_validation' => true,
'supported_card_types' => [
'ausbc',
'visa',
'mastercard',
'diners',
'japcb',
'laser',
'solo',
'discover',
'amex'
],
'hidden_elements' => [
'submit_button',
'tabs'
]
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_URL, $apiLink);
curl_setopt($ch, CURLOPT_ENCODING, "gzip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Content-Length: ". strlen($data),
"x-user-secret-key:". $apiKey,
]);
$res = json_decode(curl_exec($ch));
?>
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "configurationToken",
"data": {
"configuration_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJnYXRld2F5X2lkIjoiNTgxYzc1M2E4ZjUxNTY0NzIzNjYzZmU3IiwidHlwZSI6ImNhcmQifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vYmxhYmxhIiwiZGVmaW5lZF9mb3JtX2ZpZWxkcyI6WyJmaXJzdF9uYW1lIiwibGFzdF9uYW1lIiwiZW1haWwiLCJwaG9uZSIsImFkZHJlc3NfbGluZTEiLCJhZGRyZXNzX2xpbmUyIiwiYWRkcmVzc19jb3VudHJ5IiwiYWRkcmVzc19jaXR5IiwiYWRkcmVzc19wb3N0Y29kZSJdLCJpYXQiOjE0NzgyNzE0NTd9.YP-cAKsC3_pPBmuQdD17zHNj8B6dZ1SILj86h8IeQBQ"
}
}
}
Rather than using the PayDock Admin portal, you can automate creating a configuration token using our API. This is useful for custom usages of the iframe.
POST /v1/remote-action/configs
| Field Name | Description | Details |
|---|---|---|
| purpose | Purpose of iFrame form. Available parameters: ‘payment_source’ | string, required |
| webhook_destination | Destination, where customer will receive all successful responses. Response will contain “data” object with “payment_source” parameter. Parameter “payment_source” used as “token” in future requests and needed for | string, required |
| allowed_response_data | Object containing event information to send | Object optional |
| url | Array of parameters to send on redirect url, allowed values are ‘payment_source’. Pass empty array to avoid sending any events | Array optional |
| event | Array of parameters to send on javascript events, allowed values are ‘payment_source’. In case of empty array will be set as default | Array optional |
| success_redirect_url | URL to which the Customer will be redirected to after the processed operation | String, optional |
| error_redirect_url | URL to which the Customer will be redirected to if an error is triggered in the process of operation | String, optional |
| predefined_fields | Object with required information | Object, required |
| gateway_id | ID of a gateway connected to PayDock | String, required |
| type | Type of payment source which shows in iFrame form. Parameters : “card”, “bsb”. | String, required |
| defined_form_fields | Array with iFrame form field, which will be shown in form | Array, required |
| first_name | first_name | String, optional |
| last_name | last_name | String, optional |
| 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:
- Make string of Customer data object
- Encrypt secret key using ‘SHA-256’ algorithm.
- Combine string with Customer data string with encrypted secret key
- Encrypt string using ‘SHA-256’ algorithm which Customer get in step 3.
- Compare result with signature value from webhook
"Function to encrypt data in JavaScript using CryptoJS library"
var CryptoJS = require("crypto-js");
var secretHash = CryptoJS.SHA256('e38befe37f826fdcc103f44c0e661a4af16b925d').toString(CryptoJS.enc.Hex); // put secret-key
var bodyString = JSON.stringify({"payment_source":"162bfd33-212f-4546-8127-f9596e37d4d1","custom_reference":"testref","configuration_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJ0eXBlIjoiY2FyZCIsImdhdGV3YXlfaWQiOiI1ODEwNDFhYWFmNDZlZGIzMGMxZmE1OTkifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vcGNmYWl4cGMiLCJzdWNjZXNzX3JlZGlyZWN0X3VybCI6IiIsImVycm9yX3JlZGlyZWN0X3VybCI6IiIsImRlZmluZWRfZm9ybV9maWVsZHMiOltdLCJpYXQiOjE0Nzg1MzMzOTJ9.AINNuIWd5of3bPw9V8bcg7xi6vLMsFRdXoqLf7Rjk-A"}); // put data
var hash = CryptoJS.SHA256(bodyString + secretHash).toString(CryptoJS.enc.Hex);
// hash == 'c67de0091aae55ebe432309f957f42f39e93beb71f5d38267b4dc521b8db53cf';
<?php
$userSecretKeyHash = hash('sha256', "e38befe37f826fdcc103f44c0e661a4af16b925d");
$data = json_encode([
'payment_source' => '162bfd33-212f-4546-8127-f9596e37d4d1',
'custom_reference' => 'testref',
'configuration_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoicGF5bWVudF9zb3VyY2UiLCJwcmVkZWZpbmVkX2ZpZWxkcyI6eyJ0eXBlIjoiY2FyZCIsImdhdGV3YXlfaWQiOiI1ODEwNDFhYWFmNDZlZGIzMGMxZmE1OTkifSwid2ViaG9va19kZXN0aW5hdGlvbiI6Imh0dHBzOi8vcmVxdWVzdGIuaW4vcGNmYWl4cGMiLCJzdWNjZXNzX3JlZGlyZWN0X3VybCI6IiIsImVycm9yX3JlZGlyZWN0X3VybCI6IiIsImRlZmluZWRfZm9ybV9maWVsZHMiOltdLCJpYXQiOjE0Nzg1MzMzOTJ9.AINNuIWd5of3bPw9V8bcg7xi6vLMsFRdXoqLf7Rjk-A'
]);
$resultString = $data . $userSecretKeyHash;
$resultHash = hash('sha256', $resultString);
print_r($resultHash);
// $resultHash = 'c67de0091aae55ebe432309f957f42f39e93beb71f5d38267b4dc521b8db53cf'
?>
Other Resources
Required Fields by Gateway
Different gateways require different fields, see detailed listing below
| Field Name | Options |
|---|---|
| amount | required |
| currency | required |
| reference | optional |
| description | optional |
| first_name | optional |
| last_name | optional |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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": "Test reference",
"description": "Test reference",
"__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": "Test",
"last_name": "Test",
"email": "test@test.com",
"phone": "+61000000000",
"reference": "Test reference",
"payment_source": {
"type": "card",
"card_name": "Test Test",
"card_number_last4": "4444",
"expire_month": 1,
"expire_year": 2019,
"address_line1": "Test address",
"address_line2": "Test address",
"address_city": "Sydney",
"address_postcode": "111",
"address_state": null,
"address_country": "AU",
"gateway_id": "56a8ab12d6bd4e7d628576aa",
"card_scheme": "mastercard",
"gateway_name": "stripe",
"gateway_type": "Stripe"
}
},
"status": "complete"
}
}
Paydock supports the following webhook events (see payload examples to the right):
- Transaction Success
- Transaction by Subscription Success
- Transaction by Subscription Failed
- Subscription Creation Success
- Subscription Finished
- Subscription Updated
- Subscription Failed
- Refund Requested
- Refund Success
- Refund Failure
- Card Expiration Warning
"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": "Test",
"last_name": "Test",
"email": "test@test.com",
"phone": "+61000000000",
"payment_source": {
"type": "card",
"card_name": "Test Test",
"card_number_last4": "4445",
"expire_month": 1,
"expire_year": 2019,
"address_line1": "Test address",
"address_line2": "Test address",
"address_city": "Sydney",
"address_postcode": "111",
"address_state": null,
"address_country": "AU",
"gateway_id": "56a8ab12d6bd4e7d628576aa",
"card_scheme": "mastercard",
"gateway_name": "stripe",
"gateway_type": "Stripe"
}
},
"status": "failed"
}
}
"Example of Transaction by Subscription Success"
{
"event": "subscription_transaction",
"data": {
"_id": "589da11f1958cb42532f2463",
"created_at": "2017-02-10T11:16:47.538Z",
"updated_at"