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
- Using one of our SDKs, including PHP, .Net, Java or Android
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 connect services. If you do not already have services to connect, you can usually sign up for test accounts You can see a list of some of the services we support here.
Then add a gateway in Gateway –> Add New:
You can retrieve your API public and secret key from the admin portal in My Account –> API & Settings, which you’ll need to authenticate:
Once done, jump into one of our Recipes:
Key Concepts
There are a few key concepts that help understand how to get the most out of PayDock’s Platform
| Concept | Description |
|---|---|
| one-time token | This is a token that represents payment information. This is often generated on client (using Paydock.js or Client SDK). One time tokens expire after 3 hours. |
| payment source | A payment source represents a way of paying for something. This could be credit card details, bank account details or a PayPal account. There can be multiple payment sources associated with a customer. |
| gateway | A gateway is a payment gateway of any type that payments are routed to, eg Braintree, PayPal. |
| vault | The vault is PayDock’s PCI compliant storage vault of payment sources. |
| vault token | A vault token is the reference code for a payment source, eg a credit card and expiry date |
| subscription | A subscription is a scheduled payment plan for a customer. |
| sandbox | A sandbox environment is a place where test API calls can be made without charging customers. |
| customer | An individual who can make payments. |
| admin portal | Web interface to manage your PayDock account |
Endpoints
An endpoint is a unique URL that represents an object or collection of objects which serves as the base of all PayDock API interactions.
PayDock provides two different public environments to access. You can access the different environments from the following URLS:
| Environment | API | Admin portal |
|---|---|---|
| Sandbox | https://api-sandbox.paydock.com | https://app-sandbox.paydock.com |
| Production | https://api.paydock.com | https://app.paydock.com |
To set up API calls, prepend all calls with:
Sandbox - https://api-sandbox.paydock.com
Production - https://api.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
eg
GET /v1/gateways for Production, represents
GET https://api.paydock.com/v1/gateways
Authentication
Authenticate with our API is provided by providing either your API Public Key or API Secret Key, depending on how you are using the Paydock platform. These are 40 character strings which you can find in out web app:
Authentication is managed slightly differently depending on how you’re connecting to Paydock.
Connecting to the Paydock from the client side is managed through the Public Key. There are a couple of ways to use the public key:
- 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
All other authentication is through the API Secret Key. This is used to secure server side calls:
- using the API, the API Secret Key is added as a header
Response codes / Error codes
PayDock’s API follows REST principles on status codes returned from our API.
| Request type | Response code | Response description |
|---|---|---|
| POST | 201 | A charge (or any other resource) has been created successfully |
| GET | 200 | Call successful |
| POST | 400 | Error. The transaction has been declined because of error. Check the “error_summary” section for the details. |
| Any | 408 | The response from the .Net SDK when it can’t reach the API for some time |
| GET | 404 | The charge (or any other requested resource) not found |
| Any | 403 | Permission denied |
| Any | 500 | Server Error. |
In addition, the API will generally return a detailed error message and any downstream errors. See the right panel for examples
"Gateway processing error"
"error_summary": {
"message": "Transaction Declined",
"code": "transaction_declined",
"status_code": "05",
"status_code_description": "Do not honour",
"details": {
"gateway_specific_code": "DECLINED",
"gateway_specific_description": "The requested operation was not successful",
"messages": [
"Transaction Declined"
]
}
}
|
http code |
Cause |
Error Code |
Error Structure |
|---|---|---|---|
|
400 |
Internal validation |
|
{
message: string, code: string, details: { path?: string, messages: string[] } } |
|
400 |
gateway validation |
|
message: string, code: string, details: { path?: string, gateway_specific_code: string, gateway_specific_description: string messages: string[] } } |
|
400 |
gateway proccesing |
|
{
message: string,
code: string, status_code: string, status_code_description: string, details: { path?: string, gateway_specific_code: string, gateway_specific_description: string messages: string[] } } |
|
400 - 599 |
other |
|
{
message: string, code: string, details: { messages: string[] } } |
PayDock vault
"Example response with vault token"
{
"status": 201,
"error": null,
"resource": {
"type": "customer",
"data": {
"__v": 0,
"created_at": "2017-01-24T23:28:14.045Z",
"updated_at": "2017-01-24T23:28:14.045Z",
"status": "active",
"default_source": "5887e30d28e281756b883f64",
"reference": "Fuga consequuntur sint ab magnam",
"first_name": "Natalie",
"last_name": "Foster",
"email": "nwashington@gmail.com",
"_id": "5887e30c28e281756b883f63",
"payment_sources": [
{
"updated_at": "2017-01-24T23:28:14.045Z",
"vault_token": "dd634c0c-ea3b-4d82-b7fb-5ef2d2949ff6",
"gateway_id": "58377235377aea03343240cc",
"card_name": "Natalie Foster",
"expire_month": 1,
"expire_year": 2019,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "53774915",
"status": "active",
"created_at": "2017-01-24T23:28:13.826Z",
"_id": "5887e30d28e281756b883f64",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "58377235377aea03343240cc"
}
}
}
}
PayDock provides a PCI compliant vault for payment details. When the vault is enabled, all payment details are stored in the vault. The vault is enabled or disabled across a whole PayDock account, rather than for individual requests.
When the vault is enabled, any time a payment source is added, this information is stored in the vault. This most commonly happens when a payment source is added to a customer or a new customer is created. This is also visible in the response, which includes the id for the vault token, see example to the right (payment_sources -> vault_token).
Recipes
We are building a number of recipes that cover the most common use cases for the PayDock platform.
Recipes available:
Taking a single payment
The simplest use of the PayDock platform is also the most common: taking a payment. This example shows how to take a credit card payment using the Client SDK and Charges.
The best way to take a payment on PayDock is to:
Generate an iFrame using the Client SDK that collects the payment details from a customer - this will convert the payment details to a one-time token.
A “Charge” call will be submitted to PayDock’s API using the token and payment amount to make the payment.
Set up
You’ll need a page to display a payment form and your PayDock public key (How do I get my public key?).
Generating a one-time token using the Client SDK
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<title>Donate to save puppies</title>
<style>iframe {border: 0;width: 100%;height: 300px;}</style>
</head>
<body>
<div class="container">
<div class="col-sm-5">
<h1>Donate to save puppies</h1>
<form id="donation_form" method="post" action="form.php">
<div class="form-group">
<label>Donate </label>
<select class="form-control" name="donation">
<option value="100">$100</option>
<option value="50">$50</option>
</select>
</div>
<div class="form-group" id="iframeForm">
</div>
<input type="hidden" id="payment_source" name="payment_source">
</form>
</div>
</div>
<script src="https://app.paydock.com/v1/widget.umd.min.js"></script>
<script>
var widget = new paydock.HtmlWidget('#iframeForm', 'YOUR_PUBLIC_KEY', 'YOUR_GATEWAY_ID'); // public key, gateway_id here
widget.setEnv('sandbox');
widget.onFinishInsert('#payment_source', 'payment_source');
widget.on('finish', function (data) {
document.forms[0].submit();
});
widget.load();
</script>
</body>
</html>
In this example we’ll use the Client SDK to create a one-time token, which we’ll use to make the payment.
In this case, our payment page lets someone select an amount to donate and provides their credit card details. The payment details on the donation page are collected through the PayDock iFrame, which means that the payment details are never sent to through to your server.
The Client SDK attaches the one time token to the form, then submits the form.
Note: The form will not process the transaction until the backend infrastructure is set up to handle the token.
Taking a payment
<?php
$chargeSvc = new Charges();
$res = $chargeSvc->create(10, "AUD")
->withToken($_POST["payment_source"])
->call();
?>
Next, to take a payment, use the one-time token to add the charge.
When a customer submits the form to make a donation, this sends the token that represents their payment details to the server.
From there, this token and the amount needs to be sent to PayDock to make a payment.
Note: Toggle PHP in the top right to see an example code snippet on the right
Creating a subscription with PayPal Checkout
Another common use case for the PayDock platform is driving subscriptions through the platform with PayPal into your website.
We’re going to use the PayDock Client SDK to generate a payment form with the PayPal Checkout button that we’re going to create a subscription with.
We’ve set the subscription to end after 12 transactions, however you can change this by referring to our subscription parameters.
Add PayPal Checkout Gateway
First, you must connect the PayPal Checkout gateway to PayDock.
Please refer to our PayPal Checkout integration guide.
Generating a one-time token through PayPal Checkout
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<title>Title</title>
</head>
<body>
<div class="container">
<div class="col-sm-5">
<form id="button_form" method="post" action="https://app-1508376871.000webhostapp.com/form.php">
<div class="form-group">
<label>Amount</label>
<select class="form-control" name="amount">
<option value="100">$100</option>
<option value="50">$50</option>
</select>
</div>
<div class="form-group">
<label>Interval</label>
<select class="form-control" name="interval">
<option value="day">day</option>
<option value="week">week</option>
<option value="month">month</option>
<option value="year">year</option>
</select>
</div>
<button type="button" id="button">
<img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" align="left" style="margin-right:7px;">
</button>
<input type="hidden" id="payment_source_token" name="payment_source_token" />
</form>
<input type="text" name="pst" />
</div>
</div>
<script src="https://app.paydock.com/v1/widget.umd.js"></script>
<script>
var button = new paydock.CheckoutButton('#button', 'input public key', 'your paypal checkout gateway id');
button.onFinishInsert('input[name="pst"]', 'payment_source_token');
button.onFinishInsert('#payment_source_token', 'payment_source_token');
button.onFinishInsert('#amount', 'amount');
button.onFinishInsert('#interval', 'interval');
button.setMeta({
brand_name: 'Paydock',
reference: '15',
first_name: 'receiver-name',
last_name: 'receiver-last-name',
phone: '9379992'
});
button.on('finish', function(data) {
console.log('on:finish', data);
button_form.submit();
});
</script>
</body>
</html>
Use our Client SDK to generate a payment form that redirects the customer towards the external PayPal Checkout proces.
After the customer completes the PayPal Checkout process, we’ll generate a one time token that is used to create a subscription by calling the PayDock API.
The payment details on the donation page are collected through the PayPal Checkout process and then tokenised in PayDock meaning the payment details are never sent to your server.
Note: The form will not process the transaction until the backend infrastructure is set up to handle the token.
Creating the subscription
<?php
$subscriptionSvc = new Subscriptions();
$res = $subscriptionSvc->create(1$_POST["amount"], "AUD")
->withToken($_POST["payment_source_token"])
->withSchedule($_POST["interval"], 1, null, "2020-01-01")
->call();
//You can change the end conditions - please see https://docs.paydock.com/#add-subscription
?>
Next, use the one-time token to create a subscription.
After a customer submits the form, we’ll call the PayDock API and create a subscription using the payment token generated in the previous step.
Note: Toggle PHP in the top right to see an example code snippet on the right
API Reference
The PayDock API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.
To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate URL to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.
PayDock users can interact with the service in a number of ways.
| Name | Description |
|---|---|
| Charges | create and query payments |
| Customers | create and manage customer details, with payment information for future payments |
| Subscriptions | create and manage recurring payments |
| Transfers | create and query transfers |
| 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\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\", \"customer\": \ {\"first_name\":\"Samantha\",\"last_name\":\"Washington\", \"email\":\"samwashington@gmail.com\",\"reference\":\"CustomReferenceOfCustomer\", \"payment_source\":,\ {\"address_line1\":\"Suite 660\",\"address_line2\":\"822 Ruiz Square\",\"address_city\":\"Lake Edward\",\"address_state\":\"TAS\",\"address_country\":\"AU\",\"address_postcode\":\"1234\",\"gateway_id\":\"584577f7822c66541628fa69\",\"card_name\":\"Samantha Washington\",\"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": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"token":"b76c51ed-9c00-4997-903d-54842826269a",
"custom_fields": [
{"key": "name_of_a_key", "value":"test_value"},
{"key": "name_of_a_key2", "value":"test_value2"}
]
},
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":"Fuga consequuntur sint ab magnam",
"description":"Vitae commodi provident assumenda",
"customer":{
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"payment_source": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Samantha Washington",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"21",
"card_ccv":"123"
}
},
"custom_fields": [
{"key": "name_of_a_key", "value":"test_value"},
{"key": "name_of_a_key2", "value":"test_value2"}
]
},
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":"Fuga consequuntur sint ab magnam",
"customer":{
"first_name": "Chris",
"last_name": "Curtis",
"email": "samwashington@gmail.com",
"payment_source": {
"gateway_id": "58495c9490cde693374afc0c",
"type": "bank_account",
"account_name":"Samantha Washington",
"account_number":"411111111111111",
"address_postcode": "2997",
"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 a vault token"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount": "42",
"currency": "AUD",
"reference":"Fuga consequuntur sint ab magnam",
"customer":{
"first_name": "Chris",
"last_name": "Curtis",
"email": "ccurtis@gmail.com",
"payment_source": {
"vault_token": "c96b668e-12c6-4a69-b642-2cb02f57acc0",
"card_ccv": "111"
}
}
},
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": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"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": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"customer_id":"5857abb356f0cedd2d90a436",
"payment_source_id":"58209cc5c2ee2574399de888"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\", \"transfer\" : { \"stripe_transfer_group\" : \"stripe_group_id\", \"items\" : [{ \"amount\" : \"currency\" : \"AUD\", \"destination\" : \"<stripe_account_id>\"}, { \"amount\" : 5, \"currency\" : \"AUD\", \"destination\" : \"<stripe_account_id>\" }] }, \"customer\": \ {\"first_name\":\"Samantha\",\"last_name\":\"Washington\", \"email\":\"samwashington@gmail.com\",\"reference\":\"CustomReferenceOfCustomer\", \"payment_source\":,\ {\"address_line1\":\"Suite 660\",\"address_line2\":\"822 Ruiz Square\",\"address_city\":\"Lake Edward\",\"address_state\":\"TAS\",\"address_country\":\"AU\",\"address_postcode\":\"1234\",\"gateway_id\":\"584577f7822c66541628fa69\",\"card_name\":\"Samantha Washington\",\"card_number\":\"4444333322221111\",\"expire_month\":\"01\",\"expire_year\":\"19\",\"card_ccv\":\"123\"}}"
"Charge with credit card with stripe connect details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
body: {
"amount": "100.00",
"currency": "AUD",
"transfer" : {
"stripe_transfer_group" : "stripe_group_id",
"items" : [{
"amount" : 60,
"currency" : "AUD",
"destination" : "<stripe_account_id>"
}, {
"amount" : 20,
"currency" : "AUD",
"destination" : "<stripe_account_id>"
}]
},
"token": "b76c51ed-9c00-4997-903d-54842826269a"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges?capture=false" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\", \"transfer\" : { \"stripe_transfer_group\" : \"stripe_group_id\", \"items\" : [{ \"amount\" : \"currency\" : \"AUD\",\"customer_id\":\"584577f7822c66541628fa69\"}"
"Authorise charge with customer id"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges?capture=false',
body: {
"amount":"1350",
"currency":"AUD",
"reference": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"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 with one-time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withToken($tokenId)
->call();
?>
"Charge with credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Samantha Washington", "123")
->includeCustomerDetails("Samantha", "Washington", "samwashington@gmail.com", "+61414111111")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Charge with debit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withBankAccount("551bb4af43daf16f355ab259", "test", "012003", "456456")
->includeCustomerDetails("Samantha", "Washington", "samwashington@gmail.com", "+61414111111")
->call();
?>
"Charge with existing customer"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withCustomerId("551bb4af43daf16f355ab259")
->call();
?>
"Charge with existing customer with non-default payment source"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withCustomerId("551bb4af43daf16f355ab259", "551oo4ns43qns16s355no259")
->call();
?>
"Charge with credit card with stripe connect details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->create(100, "AUD")
->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Samantha Washington", "123")
->includeTransfer("stripe_group_id", [[
"amount" => 60,
"currency" => "AUD",
"destination" => "<stripe_account_id>"
], [
"amount" => 20,
"currency" => "AUD",
"destination" => "<stripe_account_id>"
]])
->call();
?>
"Charge with one time token"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
charge.token = "b76c51ed-9c00-4997-903d-54842826269a";
ChargeResponse response = new Charges().add(charge);
"Charge with credit card"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.amount = new BigDecimal(8);
Customer customer = new Customer();
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "551bb4af43daf16f355ab259";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "5520000000000000";
payment_source.expire_month = "10";
payment_source.expire_year = "2020";
payment_source.card_ccv = "123";
customer.payment_source = payment_source;
charge.customer = customer;
ChargeResponse response = new Charges().add(charge);
"Charge with bank account"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
Customer customer = new Customer();
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "551bb4af43daf16f355ab259";
payment_source.type = PaymentType.bsb;
payment_source.account_name = "Samantha Washington";
payment_source.account_number = "064000";
payment_source.account_bsb = "064000";
customer.payment_source = payment_source;
charge.customer = customer;
ChargeResponse response = new Charges().add(charge);
"Charge with customer id"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
charge.customer_id = "5a37513523441f4f07c011e4";
ChargeResponse response = new Charges().add(charge);
"Charge customer with non-default payment source"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
charge.customer_id = "5a37513523441f4f07c011e4";
charge.payment_source_id = "5a37513723441f4f07c011e5";
ChargeResponse response = new Charges().add(charge);
"Charge with credit card with stripe connect details"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRequestStripeConnect charge = new ChargeRequestStripeConnect();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
Customer customer = new Customer();
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a39b8e723441f4f07c045d3";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "4242424242424242";
payment_source.expire_month = "01";
payment_source.expire_year = "2019";
payment_source.card_ccv = "123";
customer.payment_source = payment_source;
charge.customer = customer;
ChargeRequestStripeConnect.MetaData meta = new ChargeRequestStripeConnect.MetaData();
meta.stripe_transfer_group = PayDock.StripeTransferGroup; // stripe transfer group id
ChargeRequestStripeConnect.Transfer transfer1 = new ChargeRequestStripeConnect.Transfer(); //set up first transfer in array
transfer1.amount = new BigDecimal(80);
transfer1.currency = "AUD";
transfer1.destination = PayDock.StripeDestinationAccount1;
ChargeRequestStripeConnect.Transfer transfer2 = new ChargeRequestStripeConnect.Transfer(); //set up second transfer in array
transfer2.amount = new BigDecimal(10);
transfer2.currency = "AUD";
transfer2.destination = PayDock.StripeDestinationAccount2;
meta.stripe_transfer = new ChargeRequestStripeConnect.Transfer[] {transfer1,transfer2};
charge.meta = meta;
ChargeResponse response = new Charges().add(charge);
"Authorise charge with customer id"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, PayDock.SecretKey, PayDock.PublicKey);
ChargeRequest charge = new ChargeRequest();
charge.currency = "AUD";
charge.description = "Quidem in ea maiores illo quos esse";
charge.amount = new BigDecimal(8);
charge.customer_id = "5a37513523441f4f07c011e4";
ChargeResponse response = new Charges().authorise(charge);
Assert.assertTrue(response.get_IsSuccess());
"Charge with one time token"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeRequest
{
amount = 8,
currency = "AUD",
token = "3c1e012e-5efa-45b6-82fe-3406ab2b84ce"
};
var response = await new Charges().Add(request);
"Charge with credit card"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var charge = new ChargeRequest
{
amount = 8,
currency = "AUD",
customer = new Customer
{
payment_source = new PaymentSource
{
gateway_id = "58377235377aea03343240cc",
card_name = "Samantha Washington",
card_number = "4111111111111111",
card_ccv = "123",
expire_month = "10",
expire_year = "2020"
}
}
};
var response = await new Charges().Add(charge);
"Charge with bank account"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var charge = new ChargeRequest
{
amount = 8,
currency = "AUD",
customer = new Customer
{
payment_source = new PaymentSource
{
gateway_id = "5a278586a527bf12a4c90521",
type = PaymentType.bsb,
account_name = "Jimmy Jones",
account_bank_name = "Bank of Australia",
account_bsb = "062184",
account_number = "12341234",
address_country = "Australia",
address_city = "Sydney",
}
}
};
var response = await new Charges().Add(charge);
"Charge with customer id"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var charge = new ChargeRequest
{
amount = 8,
currency = "AUD",
customer_id = "5a4dc4f71e56ef239fa17ca0"
};
var response = await new Charges().Add(charge);
"Charge customer with non-default payment source"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var charge = new ChargeRequest
{
amount = 8,
currency = "AUD",
customer_id = "5a4dc4f71e56ef239fa17ca0",
payment_source_id = "5a37513723441f4f07c011e5"
};
var response = await new Charges().Add(charge);
"Charge with credit card with stripe connect details"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeRequestStripeConnect
{
amount = 8,
currency = "AUD",
customer = new Customer
{
payment_source = new PaymentSource
{
gateway_id = "5a39b8e723441f4f07c045d3",
card_name = "Samantha Washington",
card_number = "4111111111111111",
card_ccv = "123",
expire_month = "10",
expire_year = "2020"
}
}
};
var response = await new Charges().Add(request);
"Authorise charge with customer id"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeRequest
{
amount = 8,
currency = "AUD",
customer_id = "5a4dc4f71e56ef239fa17ca0"
};
var result = await new Charges().Authorise(request);
"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": "Fuga consequuntur sint ab magnam",
"updated_at": "2016-12-21T11:22:49.322Z",
"user_id": "582d930808277de017a2a3f3",
"transactions": [
{
"_id": "585a65fe0daa499b1553c624",
"amount": 7750,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "sale"
},
{
"_id": "585a65fe0daa499b1553c634",
"amount": 10,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "transfer"
},
{
"_id": "585a65fe0daa499b1553c625",
"amount": 20,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "transfer"
}
],
"one_off": true,
"archived": false,
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "AUS",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 4,
"expire_year": 2020,
"address_postcode": "3000",
"gateway_id": "5853d3974f76d26c24e69165",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"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
- an existing customer with the vault token
- stripe connect transfer, using any of the payment options
For a one time charge, payments are made using a one-time token, credit card or direct debit. Otherwise if you are making a payment for an existing customer, it’s simpler to store the payment source with the customer and make a payment using the customer ID.
You can also use stripe connect through PayDock. You can support this by sending through transfer requests inside the transfer object, or by sending through meta parameters. Paydock fully supports all aspects of Stripe Connect, including Direct Charges, Destination Charges and Charges and transfers.
For an authorisation of a one time charge make POST request with query param ‘capture=false’. All authorised payments can be captured or cancelled in future.
| Field Name | Description | Details |
|---|---|---|
| amount | Amount of payment | Float, required |
| currency | Currency code, AUD by default | String, required |
| token | One-time token with all the payment source information | String, required for one-time token |
| description | Manually defined description for payments in payment systems | String, optional |
| reference | Manually defined reference for customer in payment systems | String, optional |
| transfer | Object, optional | |
| stripe_transfer_group | Stripe transfer group Id | String, optional |
| items | Stripe transfer items | Array, required |
| amount | Amount of a transfer | Number, required |
| currency | Currency of a transfer | String, required |
| destination | Stripe destination account Id | String, required |
| customer_id | Existing customer ID | String, required for creating charge with customer_id |
| payment_source_id | Payment source ID | String, optional for creating charge with non-default payment source |
| customer | Object with the customer’s information. Not required for one-time token | Object, required unless one-time token or customer_id is used |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| payment_source | Object with payment information | Object, required |
| gateway_id | Gateway ID | String, required |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments | String, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| card_name | Cardholder name (as on card) | String, required for card |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | String, required for card |
| expire_year | Card expiration year yyyy format | String, required for card |
| card_ccv | Card CCV number | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| address_city | Customer Address, City | String, optional |
| address_postcode | Customer Address, Postcode | Integer, optional |
| vault_token | Vault token | String, required for the vault token payemnts |
| card_ccv | Card CCV | Integer, depends on a gateway requirements |
| meta | Optional object for stripe connect | Object, optional |
| stripe_direct_account_id | ID of an existing, connected stripe account. Use to create Stripe connect Direct Charges | String, optional |
| stripe_application_fee | A fee in cents that will be applied to the charge and transferred to the application owner’s Stripe account | String, optional |
| stripe_destination_account_id | ID of an existing, connected stripe account. Use to create Stripe connect Destination Charges | String, optional |
| stripe_destination_amount | The amount to transfer to the destination account without creating an Application Fee | String, optional |
| securepay_fraud_guard | applies only for Secure Pay, enables SecurePay fraud guard for this transaction | bool, optional |
| ip_address | applies only for Secure Pay, pass through the client IP for fraud validation | String, optional |
| customer_storage_number | Bambora gateway only. This value dictates which account the card details will be stored against | string, optional |
| tokenise_algorithm | Bambora alorithm Id for creating charges. (Default - 8, if not specified.) | Number optional |
| custom_fields | Optional array of objects for sending custom fields to a payment gateway | Array, optional |
| key | Name of a key to send to gateway | String, required |
| value | Value of a key to send to a gateway | String, optional |
See also Required Fields by Gateway
Assign a charge to a subscription
"Assign charge to a subscription"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/5997acc356f0cedd2d87a111',
body: {
"subscription_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);
}
});
"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": "Fuga consequuntur sint ab magnam",
"updated_at": "2016-12-21T11:22:49.322Z",
"user_id": "582d930808277de017a2a3f3",
"subscription_id": "592d930808277de017a2b1d5",
"transactions": [
{
"_id": "585a65fe0daa499b1553c624",
"amount": 7750,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "sale"
},
{
"_id": "585a65fe0daa499b1553c634",
"amount": 10,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "transfer"
},
{
"_id": "585a65fe0daa499b1553c625",
"amount": 20,
"created_at": "2016-12-21T11:22:38.516Z",
"currency": "AUD",
"status": "complete",
"type": "transfer"
}
],
"one_off": false,
"archived": false,
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "AUS",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 4,
"expire_year": 2020,
"address_postcode": "3000",
"gateway_id": "5853d3974f76d26c24e69165",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "complete"
}
}
}
POST /v1/charges/{{charge_id}}
You can assign a single charge to a subscription
| Field Name | Description | Details |
|---|---|---|
| subscription_id | Subscription ID | String, required |
Capture charge
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges/{_id}/capture" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\"}"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}/capture',
body: {
"amount":"10.00"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->capture("123123123", 10)
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeResponse result = new Charges().capture("charge_id");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Charges().Capture("charge_id",8);
"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": "Fuga consequuntur sint ab magnam",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "AUS",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 4,
"expire_year": 2020,
"address_postcode": "3000",
"gateway_id": "5853d3974f76d26c24e69165",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "complete"
}
}
}
POST /v1/charges/{_id}/capture
For capturing an authorised charge, make a POST call.
| Field Name | Description | Details |
|---|---|---|
| amount | Amount of payment | Float, optional |
| _id | Payment Identifier | String, optional |
Cancel authorised charge
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/charges/{_id}/capture" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{}"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}/capture',
body: {},
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);
}
});
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeResponse result = new Charges().cancelauthorisation("charge_id");
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->cancelAuthorisation("123123123")
->call();
?>
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var CancelResponse = await new Charges().CancelAuthorisation("charge_id");
"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": "Fuga consequuntur sint ab magnam",
"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": "cancelled",
"type": "sale"
}
],
"one_off": true,
"archived": false,
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "AUS",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 4,
"expire_year": 2020,
"address_postcode": "3000",
"gateway_id": "5853d3974f76d26c24e69165",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "cancelled"
}
}
}
DELETE /v1/charges/{_id}/capture
For cancelling an authorised charge, make a DELETE call.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, optional |
Get charges list
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->get()
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeItemsResponse result = new Charges().get();
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Charges().Get();
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 5,
"expire_year": 2021,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "9576",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 5,
"expire_year": 2021,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "9576",
"address_state": "tas",
"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&updated_at.from=2020-01-31&updated_at.to=2020-02-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&updated_at.from=2020-01-31&updated_at.to=2020-02-31&one_off=true',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->get()
->withParameters(['created_at.from' => '2017-01-01', 'created_at.to' => '2018-01-31'])
->withParameters(['updated_at.from' => '2017-01-01', 'updated_at.to' => '2018-01-31'])
->withParameters(['one_off' => 'true')
->call();
?>
import com.paydock.javasdk.PayDock;
import java.time.Instant;
import java.util.Date;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeSearchRequest request = new ChargeSearchRequest();
request.created_at_from = Date.from(Instant.parse("2017-12-09T12:00:00Z"));
request.created_at_to = Date.from(Instant.parse("2018-01-02T12:00:00Z"));
request.updated_at_from = Date.from(Instant.parse("2017-12-09T12:00:00Z"));
request.updated_at_to = Date.from(Instant.parse("2018-01-02T12:00:00Z"));
request.one_off = true;
ChargeItemsResponse result = new Charges().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeSearchRequest
{
created_at_from = new DateTime(2017,12,03),
created_at_to = new DateTime(2018,01,02),
updated_at_from = new DateTime(2017,12,03),
updated_at_to = new DateTime(2018,01,02),
one_off = true
};
var response = await new Charges().Get(request);
"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": "Vitae commodi provident assumenda",
"external_id": "684000-Fuga consequuntur sint ab magnam",
"reference": "Fuga consequuntur sint ab magnam",
"updated_at": "2017-01-04T08:22:11.469Z",
"one_off": true,
"archived": false,
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 1,
"expire_year": 19,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "1234",
"address_state": "TAS",
"address_country": "AU",
"gateway_id": "586cb09dbce8378c54a8aba6",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "complete"
},
{
"_id": "586bba1abce8378c54a8ab9b",
"amount": 10,
"created_at": "2017-01-03T14:50:02.709Z",
"currency": "AUD",
"description": "Vitae commodi provident assumenda",
"external_id": "680246-Fuga consequuntur sint ab magnam",
"reference": "Fuga consequuntur sint ab magnam",
"updated_at": "2017-01-03T14:50:04.596Z",
"one_off": true,
"archived": false,
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"expire_month": 1,
"expire_year": 19,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "1234",
"address_state": "TAS",
"address_country": "AU",
"gateway_id": "586bba03bce8378c54a8ab9a",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "complete"
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/charges/?skip={skip}&limit={limit}&subscription_id={subscription_id}&gateway_id={gateway_id}&company_id={company_id}&created_at.from={created_at.from}&created_at.to={created_at.to}&updated_at.from={updated_at.from}&updated_at.to={updated_at.to}&search={search}&status={status}&archived={archived}&reference={reference}&one_off={one_off}
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 |
| updated_at.from | Parameter to set range of transactions updated from date (yyyy-mm-dd) | String, optional |
| updated_at.to | Parameter to set range of transactions updated to date ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | String, optional |
| search | Word of phrase Customer want to search in created charges (search works by fields: First, Last names and Emails) | String, optional |
| status | Status could be: complete, failed, archived, requested, refund_requested, refunded, inprogress | String, optional |
| archived | Set to true to show all the archived charges. Default: false | Boolean, optional |
| reference | Charge reference declared on creation. transaction_external_id can also be used to search by reference | String, optional |
| one_off | Set to true to get charges without a subscription only. Set to false to get charges created by subscriptions only. | Boolean, optional |
Get single charge
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->get()
->withChargeId("123123123")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeItemResponse result = new Charges().get("charge_id");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var ChargeResult = await new Charges().Get("charge_id");
"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": "Quidem in ea maiores illo quos esse",
"description": "Molestias fuga nobis numquam",
"__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": "samwashington@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\":\"Samantha Washington\",\"buyer_email\":\"samwashington@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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "3000",
"address_state": "TAS",
"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 |
Expand the Charges object with additional details
GET /v1/charges?one_off=true&expand=current_subscription_details,subscription
| Field Name | Details |
|---|---|
| current_subscription_details | Displays detailed information from the subscription history. This parameter returns a ‘snapshot’ of the Subscription at the point in time the Charge request was triggered. |
| subscription | Displays ‘live’ information from the Subscription service at the time of the API request. |
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges?one_off=true&expand=current_subscription_details,subscription" \
-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?one_off=true&expand=current_subscription_details,subscription',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->get()
->withParameters(['expand' => 'current_subscription_details,subscription'])
->withParameters(['one_off' => 'true')
->call();
?>
import com.paydock.javasdk.PayDock;
import java.time.Instant;
import java.util.Date;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeSearchRequest request = new ChargeSearchRequest();
request.expand = 'current_subscription_details,subscription';
request.one_off = true;
ChargeItemsResponse result = new Charges().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeSearchRequest
{
expand = "current_subscription_details,subscription",
one_off = true
};
var response = await new Charges().Get(request);
"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": "Quidem in ea maiores illo quos esse",
"description": "Molestias fuga nobis numquam",
"__v": 1,
"external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
"subscription": {
"created_at": "2020-02-11T11:32:34.424Z",
"updated_at": "2020-02-13T11:32:55.852Z",
"status": "active",
"statistics": {
"total_collected_amount": 333,
"successful_transactions": 3
},
"schedule": {
"interval": "day",
"start_date": "2020-02-11T11:32:33.139Z",
"end_transactions": 5,
"next_assessment": "2020-02-14T11:32:33.139Z",
"next_assessment_planned": "2020-02-14T11:32:33.139Z",
"last_assessment_planned": "2020-02-13T11:32:33.139Z",
"first_assessment": "2020-02-11T11:32:33.139Z",
"last_assessment": "2020-02-13T11:32:55.832Z",
"completed_count": 3,
"held_count": 0,
"retry_count": 0,
"frequency": 1,
"status": "complete"
}
},
"current_subscription_details": {
"status": "active",
"schedule": {
"interval": "day",
"frequency": 1,
"start_date": "2020-02-11T11:32:33.139Z",
"end_transactions": 5,
"next_assessment": "2020-02-14T11:32:33.139Z",
"last_assessment": "2020-02-13T11:32:55.832Z",
"next_assessment_planned": "2020-02-14T11:32:33.139Z",
"last_assessment_planned": "2020-02-13T11:32:33.139Z",
"first_assessment": "2020-02-11T11:32:33.139Z",
"retry_count": 0,
"status": "complete"
}
},
"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": "samwashington@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\":\"Samantha Washington\",\"buyer_email\":\"samwashington@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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "3000",
"address_state": "TAS",
"address_country": "AU",
"gateway_id": "5853e89c2bd79538605a3fb6"
}
},
"status": "complete"
}
}
}
Refund Charge
curl -X "POST" "https://api-sandbox.paydock.com/v1/charges/{_id}/refunds" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/charges/{_id}/refunds',
method: 'POST',
body: {"amount":"50"},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->refund()
->withChargeId("123123123")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRefundResponse response = new Charges().refund("charge_id", new BigDecimal(8));
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Charges().Refund("charge_id", 8);
"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": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_zip": "9576",
"address_state": "TAS",
"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": 2021,
"fingerprint": "tcKbROx2vZva0RVt",
"country": "US",
"name": "Samantha Washington",
"address_line1": "Suite 660",
"address_line2": " 822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"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": 2021,
"fingerprint": "tcKbROx2vZva0RVt",
"country": "US",
"name": "Samantha Washington",
"address_line1": "Suite 660",
"address_line2": " 822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReferenceOfCustomer",
"payment_source": {
"card_name": "Samantha Washington",
"card_number_last4": "4242",
"expire_month": 5,
"expire_year": 17,
"address_line1": "Suite 660",
"address_line2": " 822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "1234",
"address_state": "TAS",
"address_country": "AU",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_scheme": "visa",
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType"
}
},
"status": "refund_requested"
}
}
}
POST /v1/charges/{_id}/refunds
POST refund request of specified transaction.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
| amount | Amount to be refunded (must not exceed original transaction amount) | Float, optional |
Archive Charge
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/charges/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->archive("123123123")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeRefundResponse response = new Charges().archive("charge_id");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Charges().Archive("charge_id");
"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": "Quidem in ea maiores illo quos esse",
"description": "Molestias fuga nobis numquam",
"__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": "samwashington@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\":\"Samantha Washington\",\"buyer_email\":\"samwashington@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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "3000",
"address_state": "TAS",
"address_country": "AU",
"gateway_id": "5853e89c2bd79538605a3fb6"
}
},
"status": "complete"
}
}
}
DELETE /v1/charges/{_id}
Archive Charge to hide it it from charges list. You can still retrieve archived charges, see [Get charges list with parameters
](#get-charges-list-with-parameters)
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
Get archived charges list
curl -X "GET" "https://api-sandbox.paydock.com/v1/charges/?archived=true" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/charges/?archived=true',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Charges();
$res = $svc->get()
->withFilter(["archived" => "true"])
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
ChargeSearchRequest request = new ChargeSearchRequest();
request.archived = TRUE;
ChargeItemsResponse response = new Charges().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new ChargeSearchRequest
{
archived = true
};
var response = await new Charges().Get(request);
"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": "Quidem in ea maiores illo quos esse",
"description": "Molestias fuga nobis numquam",
"external_id": "ec4592bc-77e4-40c0-82f7-6c6637efe6df",
"one_off": false,
"archived": true,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"type": "card",
"card_name": "Samantha Washington",
"card_number_last4": "1111",
"card_scheme": "visa",
"expire_month": 10,
"expire_year": 2020,
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "3000",
"address_state": "TAS",
"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 or receive 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. Also, there is ability to use a Ccustomer as a destination for transferring money Transfers. A customer must have at least one payment source (eg. credit card) that can be used for payment or a payment destination that can be used fot transfers.
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\":\"Vitae commodi provident assumenda\",\"first_name\":\"Samantha\",\"last_name\":\"Washington\", \"company_name\":\"PayDock\", \"email\":\"samwashington@gmail.com\",\"phone\":\"+61779790496\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Suite 660\", \"address_line2\":\"samwashington@gmail.com\", \"address_city\":\"Lake Edward\", \"address_state\":\"TAS\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Samantha Washington\", \"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": "Fuga consequuntur sint ab magnam",
"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":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Samantha Washington",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"21",
"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":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_source": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "586bb6f3bce8378c54a8ab99",
"type": "bank_account",
"account_number": "45679",
"account_bsb": "123",
"account_name": "User name"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example, including payment destination using bsb details"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'POST',
body: {
"reference":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"payment_destination": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "586bb6f3bce8378c54a8ab99",
"account_number": "45679",
"account_routing": "123",
"account_name": "Samantha Washington"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example using one-time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc->create("Samantha", "Washington")
->withToken($tokenId)
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Example using credit card details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc->create("Samantha", "Washington")
->withCreditCard("586bb6f3bce8378c54a8ab99", "4111111111111111", "2020", "10", "Samantha Washington", "123")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Example using debit details"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc->create("Samantha", "Washington")
->withBankAccount("586bb6f3bce8378c54a8ab99", "test", "012003", "456456")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Example using one-time token"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerRequest customer = new CustomerRequest();
customer.first_name = "Samantha";
customer.last_name = "Washington";
customer.token = "b76c51ed-9c00-4997-903d-54842826269a";
CustomerResponse response = new Customers().add(customer);
"Example using credit card details"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerRequest customer = new CustomerRequest();
customer.first_name = "Samantha";
customer.last_name = "Washington";
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a272651a527bf12a4c904c9";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "5520000000000000";
payment_source.expire_month = "10";
payment_source.expire_year = "2020";
payment_source.card_ccv = "123";
customer.payment_source = (payment_source);
CustomerResponse response = new Customers().add(customer);
"Example using bsb details"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerRequest customer = new CustomerRequest();
customer.first_name = "Samantha";
customer.last_name = "Washington";
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a278586a527bf12a4c90521";
payment_source.type = PaymentType.bsb;
payment_source.account_name = "Samantha Washington";
payment_source.account_number = "064000";
payment_source.account_bsb = "064000";
customer.payment_source = (payment_source);
CustomerResponse response = new Customers().add(customer);
"Example using one-time token"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerRequest
{
first_name = "Samantha",
last_name = "Washington",
token = "1da8870d-ae52-4de4-9079-e105bf44ec74"
};
var response = await new Customers().Add(request);
"Example using credit card details"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var customer = new CustomerRequest
{
first_name = "Samantha",
last_name = "Washington",
email = "samwashington@gmail.com",
payment_source = new PaymentSource
{
gateway_id = TestConfig.GatewayId,
card_name = "Samantha Washington",
card_number = "4111111111111111",
card_ccv = "123",
expire_month = "10",
expire_year = "2020"
}
};
var response = await new Customers().Add(customer);
"Example using bsb details"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var customer = new CustomerRequest
{
first_name = "Samantha",
last_name = "Washington",
email = "samwashington@gmail.com",
payment_source = new PaymentSource
{
gateway_id = TestConfig.WestpacGatewayID,
type = PaymentType.bsb,
account_name = "Jimmy Jones",
account_bank_name = "Bank of Australia",
account_bsb = "062184",
account_number = "12341234"
}
};
var response = await new Customers().Add(customer);
"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": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"_id": "585bac95e45b75bc368087b7",
"payment_sources": [
{
"updated_at": "2016-12-22T10:36:08.170Z",
"vault_token": "94344342-a427-4b9f-9476-f64386d5bba9",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Samantha Washington",
"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": "Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"_id": "5874c78f88146959c9f9a41b",
"payment_sources": [
{
"updated_at": "2017-01-10T11:37:51.454Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "586bb6f3bce8378c54a8ab99",
"account_routing": "123",
"account_name": "Samantha Washington",
"ref_token": "CS-ECF35255704871D4",
"status": "active",
"created_at": "2017-01-10T11:37:51.450Z",
"_id": "5874c78f88146959c9f9a41c",
"type": "bank_account"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"_service": {
"default_gateway_id": "586bb6f3bce8378c54a8ab99"
}
}
}
}
"Example of response with payment destination and bank account details"
{
"status": 201,
"error": null,
"resource": {
"type": "customers",
"data": {
"_id": "5bcee7c7d4613a1a43153aca",
"created_at": "2018-10-23T09:20:07.140Z",
"updated_at": "2018-10-23T09:20:07.195Z",
"company_id": "5ab35841d9e2341e2d815861",
"user_id": "5ab35841d9e2341e2d815860",
"first_name": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"status": "active",
"_source_ip_address": "127.0.0.1",
"payment_destinations": [
{
"account_bsb": "615243",
"created_at": "2018-10-23T09:20:07.156Z",
"updated_at": "2018-10-23T09:20:07.195Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_postcode": "1234",
"address_state": "TAS",
"address_country": "AU",
"account_name": "Samantha Washington",
"account_number": "81726354",
"account_routing": "615243",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "active",
"ref_token": "34038480-75a4-4121-bb50-65907f271ee0",
"_id": "5bcee7c7d4613a1a43153acb",
"type": "bank_account"
}
],
"archived": false,
"__v": 1,
"default_payment_destination": "5bcee7c7d4613a1a43153acb",
"_service": {
"default_payment_destination_gateway_id": "5bab6b5c38834e6a841f6acc"
}
}
}
}
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 |
| company_name | Customer company 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 |
| description | Customer description. This is customer internal description | String, optional |
| payment_source | Object which includes all payment information | Object required, if adding customer direct debit or credit |
| gateway_id | Gateway ID | String required |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payments | String, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String required bank account and bsb only |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String required bsb account only |
| account_routing | Account routing number. BSB/Routing/SWIFT/IBAN Number. | String required bank account only |
| account_number | Number of customer bank account. Parameter required when using Direct Debit only | String required bank account and bsb only |
| account_holder_type | Account type (‘personal’ or ‘business’) | String required bank account only |
| account_bank_name | Name of account bank | String required bank account only |
| card_name | Cardholder name (as on card) | String required card only |
| card_number | Card number | Integer required card only |
| expire_month | Card expiration month mm format | String required card only |
| expire_year | Card expiration year yyyy format | String required card only |
| card_ccv | Card CCV number. Depending on customer gateway and configuration, this may be required | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_city | Customer Address, City | String, optional |
| address_postcode | Customer Address, Postcade | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| meta | Object where can be specified optional information about customer | Object, optional |
| customer_storage_number | Identification of a customer on a gateway side for future payments binding (used by Bambora gateway) | String optional |
| tokenise_algorithm | Bambora alorithm Id for creating customers. (Default - 2, if not specified.) | Number 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 |
| payment_destination | Object which includes all payment destination information | Object required, if adding customer for making transfers |
| gateway_id | Gateway ID | String required |
| account_name | Customer account name. Parameter required when using Direct Debit only | String required bank account and bsb 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 |
| 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 |
See also Required fields by Gateway
Get customer list
curl -X "GET https://api-sandbox.paydock.com/v1/customers" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->get()
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerItemsResponse result = new Customers().get();
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Customers().Get();
"Example of response"
{
"status":200,
"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":"Samantha",
"last_name":"Washington",
"company_name": "PayDock",
"email":"samwashington@gmail.com",
"phone":"+61779790496",
"payment_sources":[
{
"updated_at":"2016-12-22T10:36:08.170Z",
"vault_token":"94344342-a427-4b9f-9476-f64386d5bba9",
"address_line1":"Suite 660",
"address_line2":"822 Ruiz Square",
"address_city":"Lake Edward",
"address_state":"TAS",
"address_country":"AU",
"address_postcode":"3000",
"gateway_id":"5853e89c2bd79538605a3fb6",
"card_name":"Samantha Washington",
"expire_month":10,
"expire_year":2020,
"card_number_last4":"1111",
"card_scheme":"visa",
"ref_token":"754a2e68-32f9-437c-9544-afc6bef2beb8",
"status":"active",
"created_at":"2016-12-22T10:36:08.083Z",
"_id":"585bac98e45b75bc368087b8",
"type":"card"
}
],
"archived":false,
"statistics":{
"total_collected_amount":0,
"successful_transactions":0
}
}
]
}
}
GET /v1/customers
Returns all customers for the account, limited to 100 records.
Get customer list with parameters
curl -X "GET https://api-sandbox.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&archived={true/false}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->get()
->withParameters(["search" => "test", "sortkey" => "firstname"])
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerSearchRequest request = new CustomerSearchRequest();
request.gateway_id = "5a272651a527bf12a4c904c9";
request.search = "test";
request.sortkey = "firstname";
CustomerItemsResponse response = new Customers().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerSearchRequest
{
gateway_id = "5a27839c6650eb12a817f959",
search = "test",
sortkey = "firstname"
};
var result = await new Customers().Get(request);
"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": "Samantha",
"last_name": "Washington",
"company_name": "PayDock",
"email": "samwashington@gmail.com",
"_id": "55dd5270036a2d542c1efbfb",
"__v": 0,
"payment_sources": [
{
"updated_at": "2015-08-26T05:45:32.586Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "2997",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_name": "Samantha Washington",
"expire_month": 5,
"expire_year": 2021,
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"_id": "55dc74a06379cd122541764d",
"__v": 0,
"payment_sources": [
{
"updated_at": "2015-08-25T13:59:16.884Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "55840a4c27b2cf0b1e4f1a6f",
"card_name": "Samantha Washington",
"expire_month": 5,
"expire_year": 2021,
"card_number_last4": "4242",
"card_scheme": "visa",
"ref_token": "cus_6rQooHxT3HF3p6",
"status": "active",
"created_at": "2015-08-25T13:58:57.476Z",
"_id": "55dc74a16379cd122541764e",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/customers?skip={skip}&limit={limit}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&gateway_id={id}&payment_source_id={id}&id={id}&reference={reference}&archived={true/false}
Retrieving data on existing customers can be driven by number of action parameters set in URI path.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n customers from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| search | Text search parameter (search in fields firstname, lastname, email, company_name) | 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 |
| company_name | Company name | String, optional |
Response:
| Field Name | Description | Details |
|---|---|---|
| type | Type of returned resource | String |
| data | Returned data | Array |
| query_token | Token which contains query data used for further queries | String |
| count | Pagination param. Count of all users | Integer |
| limit | Pagination param. Limit of users | Integer |
| skip | Pagination param. Skip users from start | Integer |
Get customer payment sources by query token
curl -X "GET https://api-sandbox.paydock.com/v1/customers/payment_sources?query_token={query_token}&public_key={public_key}" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/customers/payment_sources?query_token={query_token}&public_key={public_key}',
method: 'GET',
headers: {
'content-type' : 'application/json'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->getPaymentSources("{query_token}")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerPaymentSourceSearchRequest request = new CustomerPaymentSourceSearchRequest();
request.query_token = "query_token";
CustomerPaymentSourceSearchResponse response = new Customers().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerSearchRequest
{
reference = "query_token"
};
var result = await new Customers().Get(request);
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "payment_sources",
"data": [
{
"_id": "59c0c403a6976f1037df4f6b",
"card_number_last4": "1111",
"card_scheme": "visa",
"type": "card",
"gateway_id": "58377235377aea03343240cc",
"customer_id": "59c0c402a6976f1037df4f6a",
"primary": true
}
],
"count": 1,
"limit": 100,
"skip": 0
}
}
GET /v1/customers/payment_sources?query_token={query_token}&public_key={public_key}
Get payment sources of customers by query_token generated from getCustomers with params endpoint
| Field Name | Description | Details |
|---|---|---|
| query_token | token that represents a customer | String |
| public_key | public key from your Paydock account | String |
Get single customer
curl -X "GET https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->get()
->withCustomerId("59c0c402a6976f1037df4f6a")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerSearchRequest request = new CustomerSearchRequest();
request._id = "5a3c7f6c73164812e2b46d69";
CustomerItemsResponse response = new Customers().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerSearchRequest
{
id = "5a3c7f6c73164812e2b46d69"
};
var result = await new Customers().Get(request);
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "customers",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"__v": 0,
"payment_sources": [
{
"updated_at": "2016-12-22T10:04:06.417Z",
"vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Samantha Washington",
"expire_month": 10,
"expire_year": 2020,
"card_number_last4": "1111",
"card_scheme": "visa",
"ref_token": "70b234c5-3af7-41b5-9992-96a014eab056",
"status": "active",
"created_at": "2016-12-22T10:04:06.370Z",
"_id": "585ba516e45b75bc368087a9",
"type": "card"
}
],
"statistics": {
"currency": {
"AUD": {
"count": 2,
"total_amount": 27
}
},
"total_collected_amount": 27,
"successful_transactions": 2
},
"_service": {
"default_gateway_id": "5853e89c2bd79538605a3fb6"
}
}
}
}
GET /v1/customers/{_id}
Retrieves data on the customer with specified ID.
| Field Name | Description | Details |
|---|---|---|
| _id | ID of particular customer you want to get full information | String, required |
Update customer
"add a new payment source from a one time token"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"token\":\"6a40af93-7410-4383-907f-b9d7b2594cd0\",\"reference\":\"Custom edit reference new\",\"default_source\":\"56418767811923162676983c\"}"
"add a new payment source from a one time token"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"token":"6a40af93-7410-4383-907f-b9d7b2594cd0",
"reference":"Custom edit reference new",
"default_source":"56418767811923162676983c"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"add a new payment source from a one time token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "Samantha", "Washington", "samwashington@gmail.com", "+61414123123")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->withToken("6a40af93-7410-4383-907f-b9d7b2594cd0")
->call();
?>
"add a new payment source from a one time token"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerUpdateRequest request = new CustomerUpdateRequest();
request.customer_id = "5565b4c5648a0df61455a688";
request.token = "c7dc4d31-771b-4e78-8c94-b6a9267b70b6";
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a2784836650eb12a817f95a";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "5520000000000000";
payment_source.expire_month = "10";
payment_source.expire_year = "2020";
payment_source.card_ccv = "123";
request.payment_source = payment_source;
CustomerItemResponse response = new Customers().update(request);
"add a new payment source from a one time token"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerUpdateRequest
{
customer_id = "5565b4c5648a0df61455a688",
token = "c7dc4d31-771b-4e78-8c94-b6a9267b70b6",
payment_source = new PaymentSource
{
gateway_id = TestConfig.PaypalGatewayId,
card_name = "Samantha Washington",
card_number = "4242424242424242",
expire_month = "04",
expire_year = "20",
card_ccv = "123"
}
};
var response = await new Customers().Update(request);
"add a new credit card"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"reference\":\"Vitae commodi provident assumenda\",\"first_name\":\"Samantha\",\"last_name\":\"Washington\",\"email\":\"samwashington@gmail.com\",\"phone\":\"+61779790496\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Suite 660\", \"address_line2\":\"samwashington@gmail.com\", \"address_city\":\"Lake Edward\", \"address_state\":\"TAS\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"card_name\":\"Samantha WashingtonEdit\",\"card_number\":\"4987654321098769\",\"expire_month\": \"02\",\"expire_year\":\"19\",\"card_ccv\":\"223\"}}"
"add a new credit card"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"reference":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"default_source":"5565b4c5648a0df61455a689"
"payment_source": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TASEdit",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"card_name":"Samantha Washington",
"card_number":"4987654321098769",
"expire_month": "02",
"expire_year":"19",
"card_ccv":"223"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"add a new credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "Samantha", "Washington", "samwashington@gmail.com", "+61414123123")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->withCreditCard("55534a8ba28d339a100e741c", "4111111111111111", "2020", "10", "Samantha Washington", "123")
->call();
?>
"add a new credit card"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerUpdateRequest request = new CustomerUpdateRequest();
request.customer_id = "5565b4c5648a0df61455a688";
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a2784836650eb12a817f95a";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "5520000000000000";
payment_source.expire_month = "10";
payment_source.expire_year = "2020";
payment_source.card_ccv = "123";
request.payment_source = payment_source;
CustomerItemResponse response = new Customers().update(request);
"add a new credit card"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerUpdateRequest
{
customer_id = "5565b4c5648a0df61455a688",
payment_source = new PaymentSource
{
gateway_id = "5a2784836650eb12a817f95a",
card_name = "Samantha Washington",
card_number = "4242424242424242",
expire_month = "04",
expire_year = "20",
card_ccv = "123"
}
};
var result = await new Customers().Update(request);
"add a new bank account"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"reference\":\"Vitae commodi provident assumenda\",\"first_name\":\"Samantha\",\"last_name\":\"Washington\",\"email\":\"samwashington@gmail.com\",\"phone\":\"+61779790496\",\"payment_source\":\ {\"type\":\"card\", \"address_line1\":\"Suite 660\", \"address_line2\":\"samwashington@gmail.com\", \"address_city\":\"Lake Edward\", \"address_state\":\"TAS\", \"address_country\":\"AU\", \"address_postcode\":\"1234\", \"gateway_id\":\"551bb4af43daf16f355ab259\", \"account_name\":\"Samantha Washington\", \"account_number\":\"1234\", \"account_bsb\":\"123123\"}}"
"add a new bank account"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"reference":"Aut id culpa architecto",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"default_source":"5565b4c5648a0df61455a689",
"payment_source": {
"gateway_id": "586bb6f3bce8378c54a8ab99",
"type": "bank_account",
"account_number": "456778",
"account_bsb": "123",
"account_name": "Samantha Washington"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"add a new bank account"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8", "Samantha", "Washington", "samwashington@gmail.com", "+61414123123")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->withBankAccount(586bb6f3bce8378c54a8ab99, "test", "012003", "456456")
->call();
?>
"add a new bank account"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
CustomerUpdateRequest request = new CustomerUpdateRequest();
request.customer_id = "5565b4c5648a0df61455a688";
PaymentSource payment_source = new PaymentSource();
payment_source.gateway_id = "5a39b8e723441f4f07c045d3";
payment_source.account_bsb = "012003";
payment_source.account_number = "586bb6f3bce8378c54a8ab99";
request.payment_source = payment_source;
CustomerItemResponse response = new Customers().update(request);
"add a new bank account"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new CustomerUpdateRequest
{
customer_id = "5565b4c5648a0df61455a688",
payment_source = new PaymentSource
{
gateway_id = "5a278586a527bf12a4c90521",
type = PaymentType.bsb,
account_name = "Jimmy Jones",
account_bank_name = "Bank of Australia",
account_bsb = "062184",
account_number = "12341234"
}
};
var result = await new Customers().Update(request);
"convert token from another payment gateway"
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"payment_source\":\ {\"gateway_id\":\"551bb4af43daf16f355ab259\", \"vault_token\":\"dd193f39-519d-41b2-8396-097d9e76eec0\"}}"
"convert token from another payment gateway"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/customers/{_id}',
method: 'POST',
body: {
"payment_source": {
"gateway_id": "586bb6f3bce8378c54a8ab99",
"vault_token": "dd193f39-519d-41b2-8396-097d9e76eec0"
}
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"convert token from another payment gateway"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$customerSvc = new Customers();
$res = $customerSvc$svc->update("585ba514e45b75bc368087a8")
->withVaultToken("586bb6f3bce8378c54a8ab99", "dd193f39-519d-41b2-8396-097d9e76eec0")
->call();
?>
"Example of response using bsb details"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_id": "5565b4c5648a0df61455a688",
"created_at": "2015-05-27T12:12:53.525Z",
"updated_at": "2015-05-27T13:26:22.401Z",
"status": "active",
"default_source": "5565b4c5648a0df61455a689",
"reference":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"__v": 2,
"payment_sources": [
{
"updated_at": "2015-05-27T13:26:22.403Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"account_number": "456778",
"account_bsb": "123",
"account_name": "Samantha Washington",
"ref_token": "746767",
"status": "active",
"created_at": "2015-05-27T12:12:53.523Z",
"_id": "5565b4c5648a0df61455a689",
"type": "bank_account"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
}
}
"Example of response using credit card details"
{
"status": 200,
"error": null,
"resource": {
"type": "customer",
"data": {
"_id": "5565b4c5648a0df61455a688",
"created_at": "2015-05-27T12:12:53.525Z",
"updated_at": "2015-05-27T13:26:22.401Z",
"status": "active",
"default_source": "5565b4c5648a0df61455a689",
"reference":"Vitae commodi provident assumenda",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"__v": 2,
"payment_sources": [
{
"updated_at": "2015-05-27T13:26:22.403Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "2234",
"gateway_id": "55534a8ba28d339a100e741c",
"card_name": "Samantha Washington",
"expire_month": 5,
"expire_year": 2021,
"card_number_last4": "8769",
"card_scheme": "visa",
"ref_token": "746767",
"status": "active",
"created_at": "2015-05-27T12:12:53.523Z",
"_id": "5565b4c5648a0df61455a689",
"type": "card"
}
],
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
}
}
}
}
POST /v1/customers/{_id}
You can use this API to update customer information (eg email address) or add more payment sources to a customer.
Similar to creating or adding a customer or creating a charge, you can add a payment source using:
- one-time token, which could be generated using Paydock.js or the iFrame
- credit card details
- direct debit details, using bank account or BSB
- convert token from another payment gateway
| 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 |
| description | Customer description | 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 |
| default_payment_destination | Default Payments Destination ID. If changing payment customer information, new payment destination becomes default. To change default payment destination, please set this value to existing payments destination | String, optional |
| payment_source | Object with payment information | Object, required |
| payment_destination | Object which includes all payment destination information | Object required, if updating customer for making transfers |
| address_city | Customer Address, City | String, required |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb or bank account only |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb only |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required bank account and bsb only |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required bank account onlyuired |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required bank account only |
| account_bank_name | Name of account bank | String, required bank account only |
| card_name | Cardholder name (as on card) | String, required card only |
| card_number | Card number | Integer, required card only |
| expire_month | Card expiration month mm format | Integer, required card only |
| expire_year | Card expiration year yyyy format | Integer, required card only |
| card_ccv | Card CCV number | Integer, required card only |
| gateway_id | Gateway ID. For adding new payment source by transferring token from another gateway, add the new gateway ID you want the token to be attributed to here | String, required |
| vault_token | Payment vault token id of existing payment source | String, required for adding payment source by conversion from another gateway |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_postcode | Customer Address, Postcade | Integer, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| type | Type of payment. Use ‘bank_account’ to post with bank account account and ‘card’ for payments with credit cards. Parameter required when using Direct Debit | String, optional |
When adding a new payment source by converting a vault token from another gateway: You will see a new payment source added and the “default_source” field for the customer changed to the new payment source
Update expiry date for customers payment source
curl -X "POST https://api-sandbox.paydock.com/v1/customers/{_id}/payment_sources/{payment_source_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}/payment_sources/{payment_source_id}',
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
},
body: {
"vault_token": "dd193f39-519d-41b2-8396-097d9e76eec0"
},
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
POST /v1/customers/{_id}/payment_sources/{payment_source_id}
You can use this API to update customer payment source information using vault token.
| Field Name | Description | Details |
|---|---|---|
| _id | Id of a customer | Object, required if adding payment source using token |
| payment_source_id | Payment source id which needs to be updated using vault token | String, optional |
| vault_token | Vault token which is used to update payment_source | String, required |
| card_ccv | Ccv for a payment_source card | String, optional |
Delete 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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496",
"__v": 0,
"payment_sources": [
{
"updated_at": "2016-12-22T10:42:20.198Z",
"vault_token": "26338ebc-cc76-4eaa-a189-b0c3c27d0a69",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "3000",
"gateway_id": "5853e89c2bd79538605a3fb6",
"card_name": "Samantha Washington",
"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\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"},\"customer\":\{\"first_name\": \"Samantha\",\"last_name": "Washington\",\"email": "samwashington@gmail.com\",\"reference": "CustomReference\",\"payment_source\": {\"address_line1\": \"Suite 660\",\"address_line2\": \"822 Ruiz Square\",\"address_city\": \"Lake Edward\",\"address_state\": \"TAS\",\"address_country\": \"AU\",\"address_postcode\": \"1234\",\"gateway_id\": \"55925037556cc23c1ed3773e\",\"card_name\":\"Samantha Washington\",\"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": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"customer": {
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReference",
"payment_source": {
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "55925037556cc23c1ed3773e",
"card_name": "Samantha Washington",
"card_number": "4200000000000000",
"expire_month": "01",
"expire_year": "17",
"card_ccv": "123"
}
},
"schedule": {
"frequency": "1",
"interval": "day",
"start_date": "2015-07-20",
"end_date": "2016-07-25T07:35:11Z"
}
},
method: 'POST',
headers: {
'content-type': 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Add with credit card"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
->withCreditCard(self::creditGateway, "4111111111111111", "2020", "10", "Samantha Washington", "123")
->withSchedule("month", 1)
->call();
?>
"Add with credit card"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionRequest subscription = new SubscriptionRequest();
Customer customer = new Customer();
PaymentSource payment_source = new PaymentSource();
SubscriptionSchedule schedule = new SubscriptionSchedule();
subscription.currency = "AUD";
subscription.amount = new BigDecimal(8);
payment_source.gateway_id = "5a272651a527bf12a4c904c9";
payment_source.card_name = "Samantha Washington";
payment_source.card_number = "5520000000000000";
payment_source.expire_month = "10";
payment_source.expire_year = "2020";
payment_source.card_ccv = "123";
customer.payment_source = payment_source;
subscription.customer = customer;
schedule.interval = "day";
schedule.frequency = 1;
schedule.start_date = new Date();
schedule.end_transactions = 2;
subscription.schedule = schedule;
SubscriptionResponse response = new Subscriptions().add(subscription);
"Add with credit card"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var subscription = new SubscriptionRequest
{
amount = 20.0,
currency = "AUD",
description = "Vitae commodi provident assumenda",
customer = new Customer
{
first_name = "Samantha",
last_name = "Washington",
email = "samwashington@gmail.com",
payment_source = new PaymentSource
{
gateway_id = "5a272651a527bf12a4c904c9",
card_name = "Samantha Washington",
card_number = "4111111111111111",
card_ccv = "123",
expire_month = "10",
expire_year = "2020"
}
},
schedule = new SubscriptionSchedule
{
interval = "month",
frequency = 1
}
};
var response = await new Subscriptions().Add(subscription);
"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": "Vitae commodi provident assumenda",
"reference": "Fuga consequuntur sint ab magnam",
"status": "active",
"_id": "55b2213073065f9423a45d78",
"archived": false,
"_service": {
"customer_default_gateway_id": "55925037556cc23c1ed3773e",
"tags": "Samantha Washington samwashington@gmail.com"
},
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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.
There are a number of different statuses for a subscription:
- Active - A subscription that is active and has more payments to be collected
- Expired - A subscription that is complete, where all payments have been collected
- Failed - This typically occurs when the number of failed payments has been exceeded
- Archived - A subscription has been removed
| Field Name | Description | Details |
|---|---|---|
| amount | Amount of payment | Float, required |
| currency | Currency code, AUD by default | String, optional |
| customer_id | ID of PayDock customer | Object, required adding subscription with customer id |
| token | One-time token with all payment source information | String, required adding subscription using one time token |
| reference | Manually defined reference for payments in payment systems | String, optional |
| description | Manually defined description for payments in payment systems | String, optional |
| customer | Object with customers information | Object, required using customer information |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| Customer email | String, optional | |
| phone | Customer phone in E.164 international notation (Example: +12345678901) | String, optional |
| reference | Manually defined reference for customer in payment systems | String, optional |
| payment_source | Object with payment information | Object, required, if no customer provided |
| gateway_id | Gateway ID | String, required if no customer provided |
| type | Type of payment, default value is ‘card’. Use ‘card’ for payment with credit card. Use ‘bank_account’ for using direct debit payments. ‘bsb’ can also be used for direct debit payment. | String, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| card_name | Card holder name | String, optional |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | String, required for card |
| expire_year | Card expiration year yyyy format | String, required for card |
| card_ccv | Card CCV number | Integer, optional |
| address_line1 | Customer Address, line 1 | String, optional |
| address_line2 | Customer Address, line 2 | String, optional |
| address_city | Customer Address, City | String, optional |
| address_state | Customer Address, State | String, optional |
| address_country | Customer Address, Country Code | String, optional |
| address_postcode | Customer Address, Postcode | Integer, optional |
| schedule | Object with subscription schedule information | Object, required |
| interval | Assessment interval one-off, week, month, year, day | String, required |
| frequency | Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) | Integer, required |
| start_date | Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, optional |
| end_date | End date, ISO 8601 format (yyyy-mm-ddThh:mm:ssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) | Date, optional |
| end_amount_after | Total amount of all successful transactions (equals or exceeds) | Float, optional |
| end_amount_before | Total amount of all successful transactions (not to exceed) | Float, optional |
| end_amount_total | Total amount to be paid with subscription (equals). NOTE: If last payment of subscription schedule will be less then $ 1.00, some gateways may respond with error and subscription status will become ‘failed’. | Float, optional |
| end_transactions | Total count of all successful transactions | Integer, optional |
| meta | Optional object for stripe connect | Object, optional |
| stripe_direct_account_id | ID of an existing, connected stripe account. Use to create Stripe connect Direct Charges | String, optional |
| stripe_application_fee | A fee in cents that will be applied to the charge and transferred to the application owner’s Stripe account | String, optional |
| stripe_destination_account_id | ID of an existing, connected stripe account. Use to create Stripe connect Destination Charges | String, optional |
| stripe_destination_amount | The amount to transfer to the destination account without creating an Application Fee | String, optional |
| customer_storage_number | Bambora gateway only. This value dictates which account the card details will be stored against | string, optional |
See also Required fields by Gateway
Add subscription using Customer ID
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\",\"schedule\": \ {\"frequency\":\1\,\"interval\":\"day\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"customer_id\":\"b76c51ed9c004997903d54842826269a\"}"
"add with customer id"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
->withCustomerId("b76c51ed9c004997903d54842826269a")
->withSchedule("month", 1)
->call();
?>
"Example of adding subscription using customer id"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions',
body: {
"amount":"10.00",
"currency":"AUD",
"reference": "Fuga consequuntur sint ab magnam",
"description": "Vitae commodi provident assumenda",
"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);
}
});
"add with customer id"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionRequest subscription = new SubscriptionRequest();
subscription.customer_id = "b76c51ed9c004997903d54842826269a";
Customer customer = new Customer();
SubscriptionSchedule schedule = new SubscriptionSchedule();
subscription.currency = "AUD";
subscription.amount = new BigDecimal(8);
subscription.customer = customer;
schedule.interval = "day";
schedule.frequency = 1;
schedule.start_date = new Date();
schedule.end_date = Date.from(Instant.parse("2019-05-05T12:00:00Z"));
subscription.schedule = schedule;
SubscriptionResponse result = new Subscriptions().add(subscription);
"add with customer id"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var subscription = new SubscriptionRequest
{
amount = 20.0,
currency = "AUD",
description = "Vitae commodi provident assumenda",
customer_id = "b76c51ed9c004997903d54842826269a",
schedule = new SubscriptionSchedule
{
interval = "month",
frequency = 1
}
};
var result = await new Subscriptions().Add(subscription);
"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": "Vitae commodi provident assumenda",
"reference": "Fuga consequuntur sint ab magnam",
"payment_source_id": "58209cc5c2ee2574399de888",
"status": "active",
"_id": "58209f14c2ee2574399de88c",
"archived": false,
"_service": {
"customer_default_gateway_id": "581c753a8f51564723663fe7",
"tags": "Samantha Washington samwashington@gmail.com"
},
"customer": {
"customer_id": "58209cc3c2ee2574399de887",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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"
}
}
}
Charges can be added to a company only if there is a Billing Plan assigned to it. Customers can add a subscription through using the Customer ID.
Add subscription with one-time token
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"schedule\": \ {\"frequency\":\1\,\"interval\":\"month\",\"start_date\":\"2015-07-20\",\"end_date\":\"2016-07-25T07:35:11Z\"}\,\"amount\":\"10.00\", \"currency\":\"AUD\", \"reference\":\"Custom subscription reference\", \"description\":\"Custom subscription description\", \"token\":\"b76c51ed-9c00-4997-903d-54842826269a\"}\"
"add with token"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->create(100, "AUD")
->withToken("b76c51ed-9c00-4997-903d-54842826269a")
->withSchedule("month", 1)
->call();
?>
"Example of adding subscription using one time token"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions',
body: {
"amount":"10.00",
"currency":"AUD",
"reference": "Vitae commodi provident assumenda",
"description": "Quidem in ea maiores illo quos esse",
"token":"b76c51ed-9c00-4997-903d-54842826269a",
"schedule":{
"interval":"month",
"frequency":"1",
"start_date":"2015-11-10",
"end_date":"2016-01-10"
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example of adding subscription using one time token"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var subscription = new SubscriptionRequest
{
token = "b76c51ed-9c00-4997-903d-54842826269a",
amount = 8,
currency = "AUD",
schedule = new SubscriptionSchedule
{
interval = "month",
frequency = 1
}
};
var result = await new Subscriptions().Add(subscription);
"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": "Vitae commodi provident assumenda",
"reference": "Quidem in ea maiores illo quos esse",
"status": "active",
"_id": "55b2213073065f9423a45d78",
"archived": false,
"_service": {
"customer_default_gateway_id": "551bb4af43daf16f355ab259",
"tags": "Samantha Washington samwashington@gmail.com"
},
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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"
}
}
}
Subscriptions can be added to a company only if there is a Billing Plan assigned to it. Customers can use a Credit Card or Direct Debit information directly, or by creating a one-time token. One-time tokens are created on the customer side, using PayDock.js or by creating a token on the API side. Also, one-time tokens can created using iFrame. A result of the iFrame process is that the Customer will get a webhook with the “payment_source” value. Parameter “payment_source” is used as a “token” in future examples.
Update subscription details
curl -X "POST" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"amount\": \"10.00\",\"currency\": \"AUD\",\"reference\":\"Fuga consequuntur sint ab magnam\",\"description\":\"Vitae commodi provident assumenda\",\"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":"Quidem in ea maiores illo quos esse",
"description":"Molestias fuga nobis numquam"
"schedule":{
"interval":"year",
"start_date":"2015-08-01"
}
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->update(200)
->withSchedule("month", 2)
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionUpdateRequest request = new SubscriptionUpdateRequest();
request._id = "subscription_id";
request.description = "Veniam animi assumenda saepe quasi pariatur est non";
SubscriptionResponse update = new Subscriptions().update(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Subscriptions().Add(subscription);
var request = new SubscriptionUpdateRequest
{
_id = "subscription_id",
description = "Custome Subscription description"
};
var result = await new Subscriptions().Update(request);
"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": "Molestias fuga nobis numquam",
"reference": "Quidem in ea maiores illo quos esse",
"status": "active",
"updated_at": "2015-07-24T11:31:34.697Z",
"user_id": "559241db556cc23c1ed3770a",
"archived": false,
"customer": {
"customer_id": "55b2212f73065f9423a45d76",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"gateway_mode": "test"
}
}
}
POST /v1/subscriptions/{_id}
Updates an existing subscription to adjust payment schedule or end conditions.
| Field Name | Description | Details |
|---|---|---|
| _id | Payment Identifier | String, required |
| amount | Amount of payment | Float, required |
| currency | Currency code, AUD by default | String, optional |
| description | Manually defined description for payments in payment systems | String, optional |
| reference | Manually defined reference for payments in payment systems | String, optional |
| payment_source_id | The payment source to be used to pay for the subscription, generally use a payment source retrieved from a customer | String, optional |
| status | Set “active” to reactivate failed subscription | String, optional |
| schedule | Object with subscription schedule information | Object, optional |
| 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, optional |
| end_amount_after | Total amount of all successful transactions (equals or exceeds) | Float, optional |
| end_amount_before | Total amount of all successful transactions (not to exceed) | Float, optional |
| end_amount_total | Total amount to be paid with subscription (equals) | Float, optional |
| end_transactions | Total count of all successful transactions | Integer, optional |
Get subscription list
curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->get()
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionItemsResponse result = new Subscriptions().get();
"Example of adding subscription using one time token"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Subscriptions().Get();
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"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}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->get()
->withParameters(["search" => "test", "sortkey" => "firstname"])
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionSearchRequest request = new SubscriptionSearchRequest();
request.gateway_id = "5a272651a527bf12a4c904c9";
request.sortkey = "firstname";
SubscriptionItemsResponse response = new Subscriptions().get(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new SubscriptionSearchRequest
{
gateway_id = "5a27839c6650eb12a817f959",
sortkey = "firstname"
};
var subscriptionresult = new Subscriptions().Get(request);
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.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": "GatewayType",
"gateway_name": "Gateway Name",
"gateway_mode": "test"
}
],
"count": 30,
"limit": 3,
"skip": 0
}
}
GET /v1/subscriptions/?skip={skip}&limit={limit}&customer_id={customer_id}&gateway_id={gateways_id}&search={search}&sortkey={sortkey}&sortdirection={sortdirection}&status={status}
Retrieving data on existing subscriptions can be driven by number of action parameters set in URI path.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n payments from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| search | Text search parameter (search in fields firstname, lastname, email) | String, optional |
| sortkey | Sorting key parameter i.e. firstname, lastname, email, startdate, ASC direction by default | String, optional |
| sortdirection | Sorting order direction parameter (ASC by default, only value that affects is DESC) | String, optional |
| customer_id | PayDock Customer’s ID | String, optional |
| gateway_id | ID of a gateway with which subscriptions were created | String, optional |
| status | Status could be: active, expired, failed, deleted | String, optional |
Get subscription item details
Retrieves data on subscription with specified ID.
GET /v1/subscriptions/{_id}
curl -X "GET" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/subscriptions/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->get()
->withSubscriptionId("55b226c273065f9423a45d8d")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionItemResponse result = new Subscriptions().get("55b226c273065f9423a45d8d");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = new Subscriptions().Get("55b226c273065f9423a45d8d");
"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": "Molestias fuga nobis numquam",
"reference": "Quidem in ea maiores illo quos esse",
"status": "active",
"_id": "55b226c273065f9423a45d8d",
"archived": false,
"customer": {
"customer_id": "55b226c173065f9423a45d8b",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"reference": "CustomReference",
"payment_source": {
"gateway_name": "Gateway Name",
"gateway_type": "GatewayType",
"gateway_mode": "test",
"updated_at": "2015-07-24T11:51:30.207Z",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"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": "bank_account"
}
},
"statistics": {
"total_collected_amount": 0,
"successful_transactions": 0
},
"schedule": {
"interval": "day",
"start_date": "2015-07-25T00:00:00.000Z",
"end_date": "2016-08-25T00:00:00.000Z",
"next_assessment": "2015-07-25T00:00:00.000Z",
"first_assessment": "2015-07-25T00:00:00.000Z",
"status": "inprogress",
"locked": false,
"completed_count": 0,
"retry_count": 0,
"frequency": 1
},
"currency": "AUD"
}
}
}
| Field Name | Description | Details |
|---|---|---|
| _id | Identifier of particular subscription | String, required |
Delete subscription
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/subscriptions/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/subscriptions/{_id}',
method: "DELETE",
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Subscriptions();
$res = $svc->delete("55b226c273065f9423a45d8d")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
SubscriptionItemResponse delete = new Subscriptions().delete("subscription_id");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = new Subscriptions().Delete("55b226c273065f9423a45d8d");
"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": "Molestias fuga nobis numquam",
"reference": "Quidem in ea maiores illo quos esse",
"payment_source_id": "585ba516e45b75bc368087a9",
"status": "deleted",
"archived": false,
"customer": {
"customer_id": "585ba514e45b75bc368087a8",
"first_name": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone": "+61779790496"
},
"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 |
Transfers
Transfers help sending money from a connected payment services to a bank account and retrieve transfers details.
Create a transfer
"Transfer with two payouts"
var request = require('request');
request({
url: 'https://api.paydock.com/v1/transfers',
body: {
"reference":"Fuga consequuntur sint ab magnam",
"description":"Vitae commodi provident assumenda",
"gateway_id":"5bab6b5c38834e6a841f6acc",
"capture": false,
"payouts": [{
"customer_id": "5bcee7c7d4613a1a43153aca",
"amount": 3,
"currency": "AUD"
},
{
"customer_id": "5a3b6b5c38834e6a841f7aff",
"amount": 5,
"currency": "AUD"
}
]
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "transfers",
"data": {
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:24:57.191Z",
"description": "Quia recusandae velit qui ullam adipisci",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "pending",
"__v": 0,
"payouts": [
{
"_id": "5bcee8e9d4613a1a43153ae1",
"created_at": "2018-10-23T09:24:57.197Z",
"updated_at": "2018-10-23T09:24:57.197Z",
"amount": 3,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "pending",
"__v": 0,
"transactions": []
},
{
"_id": "5bcee8e9d4613a1a43153ae2",
"created_at": "2018-10-23T09:24:57.203Z",
"updated_at": "2018-10-23T09:24:57.203Z",
"amount": 5,
"currency": "AUD",
"customer_id": "5a3b6b5c38834e6a841f7aff",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "pending",
"__v": 0,
"transactions": []
}
],
"capture": false
}
}
}
POST /v1/transfers
You can create a transfer using direct debit payment destination. Transfers are creating in two steps: prepare a transfer and then capture it. All prepared transfers can be captured or archived in future.
| Field Name | Description | Details |
|---|---|---|
| description | Manually defined description for a transfer in payment services | String, optional |
| reference | Manually defined reference for a transfer | String, optional |
| gateway_id | Gateway ID | String, required |
| payouts | Array of destinations with amount and currency information | Array, required |
| amount | Amount of a transfer | Number, required |
| currency | Currency of a transfer | String, required |
| customer_id | Existing customer ID, which should contain “payment_destination” parameter | String, required |
Capture a transfer
curl -X "POST" "https://api-sandbox.paydock.com/v1/transfers/{_id}/capture" \
-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/transfers/{_id}/capture',
body: {},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "transfers",
"data": {
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:30:39.915Z",
"description": "Molestias fuga nobis numquam",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h72",
"payouts": [
{
"_id": "5bcee8e9d4613a1a43153ae1",
"created_at": "2018-10-23T09:24:57.197Z",
"updated_at": "2018-10-23T09:30:39.938Z",
"amount": 3,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2ly",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.892Z",
"amount": 3,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae3",
"external_id": "D.2ly",
"_source_ip_address": "127.0.0.1"
}
]
},
{
"_id": "5bcee8e9d4613a1a43153ae2",
"created_at": "2018-10-23T09:24:57.203Z",
"updated_at": "2018-10-23T09:30:39.962Z",
"amount": 5,
"currency": "AUD",
"customer_id": "5a3b6b5c38834e6a841f7aff",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2lz",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.901Z",
"amount": 5,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae4",
"external_id": "D.2lz",
"_source_ip_address": "127.0.0.1"
}
]
}
],
"capture": false
}
}
}
POST /v1/transfers/{_id}/capture
For capturing a prepared transfer, make a POST call.
| Field Name | Description | Details |
|---|---|---|
| _id | Transfer Identifier | String, required |
Get transfers list
curl -X "GET" "https://api-sandbox.paydock.com/v1/transfers" \
-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/transfers',
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);
}
});
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "transfers",
"data": [
{
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:30:39.915Z",
"description": "Vitae commodi provident assumenda",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h72",
"payouts": [],
"capture": false
},
{
"_id": "5bcdc19bd7c009567b347448",
"created_at": "2018-10-22T12:24:59.374Z",
"updated_at": "2018-10-22T12:26:11.699Z",
"description": "Vitae commodi provident assumenda",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bacccdae2f087760d758f20",
"status": "capture_failed",
"__v": 0,
"payouts": [],
"capture": false
},
{
"_id": "5bcdbed0d7c009567b34742f",
"created_at": "2018-10-22T12:13:04.661Z",
"updated_at": "2018-10-22T12:13:04.661Z",
"description": "Vitae commodi provident assumenda",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bacccdae2f087760d758f20",
"status": "pending",
"__v": 0,
"payouts": [],
"capture": false
}
],
"skip": 0,
"limit": 100,
"sortkey": "created_at",
"sortdirection": "DESC",
"count": 3
}
GET /v1/transfers
Returns all transfers for the account, limited to 100 records. Query params can be specified.
| Field Name | Description | Details |
|---|---|---|
| skip | Pagination parameter to skip first n transfers from list, default = 0 | Number, optional |
| limit | Pagination parameter to limit output to n , default = 100 , maximum value = 1000 | Number, optional |
| archived | Available value “true” or “false” | String, optional |
Get a single transfer
curl -X "GET" "https://api-sandbox.paydock.com/v1/transfers/{_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/transfers/{_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);
}
});
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "transfers",
"data": {
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:30:39.915Z",
"description": "Quia recusandae velit qui ullam adipisci",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h72",
"payouts": [
{
"_id": "5bcee8e9d4613a1a43153ae1",
"created_at": "2018-10-23T09:24:57.197Z",
"updated_at": "2018-10-23T09:30:39.938Z",
"amount": 3,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2ly",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.892Z",
"amount": 3,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae3",
"external_id": "D.2ly",
"_source_ip_address": "127.0.0.1"
}
]
},
{
"_id": "5bcee8e9d4613a1a43153ae2",
"created_at": "2018-10-23T09:24:57.203Z",
"updated_at": "2018-10-23T09:30:39.962Z",
"amount": 5,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2lz",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.901Z",
"amount": 5,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae4",
"external_id": "D.2lz",
"_source_ip_address": "127.0.0.1"
}
]
}
],
"capture": false,
"logs": [
{
"_id": "5bceea3fa861601a6092c516",
"created_at": "2018-10-23T09:30:39.901Z",
"updated_at": "2018-10-23T09:30:39.901Z",
"tcp_status": null,
"status": "201",
"action": "create_transfer",
"relation_entity": "transfer",
"relation_id": "5bcee8e9d4613a1a43153ae0",
"url": "https://api-sandbox.split.cash/payments",
"__v": 0,
"response": {
"format": "JSON",
"body": "{\"data\":{\"ref\":\"PB.h72\",\"payouts\":[{\"ref\":\"D.2lz\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"batch_description\":\"Quia recusandae velit qui ullam adipisci\",\"matures_at\":\"2018-10-23T09:30:37Z\",\"created_at\":\"2018-10-23T09:30:39Z\",\"status\":\"matured\",\"amount\":500,\"description\":\"Quia recusandae velit qui ullam adipisci\",\"from_id\":\"7abbdf06-7157-476e-83eb-dd50d0200c18\",\"to_id\":\"0a463fb9-571c-41c7-bb79-dab4e4fa9ce1\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae4\"}},{\"ref\":\"D.2ly\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"batch_description\":\"Quidem in ea maiores illo quos esse\",\"matures_at\":\"2018-10-23T09:30:37Z\",\"created_at\":\"2018-10-23T09:30:39Z\",\"status\":\"matured\",\"amount\":300,\"description\":\"Quidem in ea maiores illo quos esse\",\"from_id\":\"7abbdf06-7157-476e-83eb-dd50d0200c18\",\"to_id\":\"0a463fb9-571c-41c7-bb79-dab4e4fa9ce1\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae3\"}}]}}"
},
"request": {
"format": "JSON",
"body": "{\"description\":\"Quidem in ea maiores illo quos esse\",\"matures_at\":\"2018-10-23T09:30:37.935Z\",\"payouts\":[{\"amount\":300,\"description\":\"Quidem in ea maiores illo quos esse\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae3\"}},{\"amount\":500,\"description\":\"Quidem in ea maiores illo quos esse\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae4\"}}]}"
}
}
]
}
}
}
GET /v1/transfers/{_id}
Retrieves data on a transfer with specified ID.
| Field Name | Description | Details |
|---|---|---|
| _id | Transfer Identifier | String, required |
Archive a transfer
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/transfers/{_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/transfers/{_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);
}
});
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "transfers",
"data": {
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:37:37.090Z",
"description": "Quidem in ea maiores illo quos esse",
"reference": "Quia recusandae velit qui ullam adipisci",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h72",
"payouts": [
{
"_id": "5bcee8e9d4613a1a43153ae1",
"created_at": "2018-10-23T09:24:57.197Z",
"updated_at": "2018-10-23T09:30:39.938Z",
"amount": 3,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2ly",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.892Z",
"amount": 3,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae3",
"external_id": "D.2ly",
"_source_ip_address": "127.0.0.1"
}
]
},
{
"_id": "5bcee8e9d4613a1a43153ae2",
"created_at": "2018-10-23T09:24:57.203Z",
"updated_at": "2018-10-23T09:30:39.962Z",
"amount": 5,
"currency": "AUD",
"customer_id": "5bcee7c7d4613a1a43153aca",
"payment_destination_id": "5bcee7c7d4613a1a43153acb",
"transfer_id": "5bcee8e9d4613a1a43153ae0",
"status": "requested",
"__v": 1,
"external_id": "D.2lz",
"transactions": [
{
"created_at": "2018-10-23T09:30:37.901Z",
"amount": 5,
"currency": "AUD",
"type": "transfer",
"status": "requested",
"_id": "5bceea3dd4613a1a43153ae4",
"external_id": "D.2lz",
"_source_ip_address": "127.0.0.1"
}
]
}
],
"capture": false,
"logs": [
{
"_id": "5bceea3fa861601a6092c516",
"created_at": "2018-10-23T09:30:39.901Z",
"updated_at": "2018-10-23T09:30:39.901Z",
"tcp_status": null,
"status": "201",
"action": "create_transfer",
"relation_entity": "transfer",
"relation_id": "5bcee8e9d4613a1a43153ae0",
"url": "https://api-sandbox.split.cash/payments",
"__v": 0,
"response": {
"format": "JSON",
"body": "{\"data\":{\"ref\":\"PB.h72\",\"payouts\":[{\"ref\":\"D.2lz\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"batch_description\":\"Quia recusandae velit qui ullam adipisci\",\"matures_at\":\"2018-10-23T09:30:37Z\",\"created_at\":\"2018-10-23T09:30:39Z\",\"status\":\"matured\",\"amount\":500,\"description\":\"Quia recusandae velit qui ullam adipisci\",\"from_id\":\"7abbdf06-7157-476e-83eb-dd50d0200c18\",\"to_id\":\"0a463fb9-571c-41c7-bb79-dab4e4fa9ce1\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae4\"}},{\"ref\":\"D.2ly\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"batch_description\":\"Quia recusandae velit qui ullam adipisci\",\"matures_at\":\"2018-10-23T09:30:37Z\",\"created_at\":\"2018-10-23T09:30:39Z\",\"status\":\"matured\",\"amount\":300,\"description\":\"Quia recusandae velit qui ullam adipisci\",\"from_id\":\"7abbdf06-7157-476e-83eb-dd50d0200c18\",\"to_id\":\"0a463fb9-571c-41c7-bb79-dab4e4fa9ce1\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae3\"}}]}}"
},
"request": {
"format": "JSON",
"body": "{\"description\":\"Quia recusandae velit qui ullam adipisci\",\"matures_at\":\"2018-10-23T09:30:37.935Z\",\"payouts\":[{\"amount\":300,\"description\":\"Quia recusandae velit qui ullam adipisci\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae3\"}},{\"amount\":500,\"description\":\"Quia recusandae velit qui ullam adipisci\",\"recipient_contact_id\":\"34038480-75a4-4121-bb50-65907f271ee0\",\"metadata\":{\"paydock_transaction_id\":\"5bceea3dd4613a1a43153ae4\"}}]}"
}
}
]
}
}
}
DELETE /v1/transfers/{_id}
Archive a transfer to hide it it from a transfers list. You can still retrieve archived transfers, see Get archived transfers
| Field Name | Description | Details |
|---|---|---|
| _id | Transfer Identifier | String, required |
Get archived transfers list
curl -X "GET" "https://api-sandbox.paydock.com/v1/transfers/?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/transfers/?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);
}
});
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "transfers",
"data": [
{
"_id": "5bcee8e9d4613a1a43153ae0",
"created_at": "2018-10-23T09:24:57.191Z",
"updated_at": "2018-10-23T09:37:37.090Z",
"description": "Quia recusandae velit qui ullam adipisci",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h72",
"payouts": [],
"capture": false
},
{
"_id": "5bcd6f47d7c009567b3472fc",
"created_at": "2018-10-22T06:33:43.440Z",
"updated_at": "2018-10-22T06:34:06.479Z",
"description": "Quidem in ea maiores illo quos esse",
"reference": "Quidem in ea maiores illo quos esse",
"gateway_id": "5bab6b5c38834e6a841f6acc",
"status": "requested",
"__v": 0,
"external_id": "PB.h6x",
"payouts": [],
"capture": false
}
],
"skip": 0,
"limit": 100,
"sortkey": "created_at",
"sortdirection": "DESC",
"count": 2
}
Get archived transfers list
GET /v1/transfers/?archived=true
Notifications
Notifications are automated messages that are triggered in response to events within the system.
Within PayDock, notification triggers are set up to fire on different events. Notification triggers can have have different types (i.e. Webhook, Email, Sms) and events (i.e. Transaction Success).
Notifications for email and SMS require templates for the notification.
See also Examples of webhook payloads
Notification Templates also provide swap values (eg {{PHONE}} or {{EMAIL}}) that will be populated from the customer, charge or subscription that triggered the notification (See Swap Values for templates for the full list).
Add new notification template
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates',
body: {
"label":"Sms first template",
"notification_event":"transaction_success",
"body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
"destination":"{{{PHONE}}}",
"type":"sms"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc->createTemplate("Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.", "label", "refund_failure")
->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTemplateRequest request = new NotificationTemplateRequest();
request.body = "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.";
request.label = "test_template";
request.notification_event = NotificationEvent.transaction_success;
request.html = false;
NotificationTemplateResponse response = new Notifications().addTemplate(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new NotificationTemplateRequest
{
body = "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
label = "test_template",
notification_event = NotificationEvent.transaction_success,
html = false
};
var response = await new Notifications().AddTemplate(request);
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "template",
"data": {
"__v": 0,
"created_at": "2016-12-21T09:07:56.100Z",
"updated_at": "2016-12-21T09:07:56.100Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
"_id": "585a466c9af8e1811517afc3"
}
}
}
POST /v1/notifications/templates
Create a notification template (available only in email and SMS type of notifications).
| Name | Description | Details |
|---|---|---|
| body | Use custom text or/and predefined variables, in which PayDock automatically pulls values from customer, charge or subscription data objects. | String, required |
| label | Name of current template to identify it further | String, required |
| notification_event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
| html | Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is false | Boolean, optional |
Edit notification template
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
body: {
"label":"Sms first template",
"notification_event":"transaction_success",
"body":"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
"destination":"{{{PHONE}}}",
"type":"sms"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc->updateTemplate("585b9aa7bce8378c54a8a61e", "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.", "label", "refund_failure")
->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications/templates" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"label\":\"Sms first template\",\"notification_event\":\"transaction_success\",\"body\":\"Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.\,\"destination\":\"{{{PHONE}}}\,\"type\":\"sms\"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTemplateUpdateRequest request = new NotificationTemplateUpdateRequest();
request._id = "585b9aa7bce8378c54a8a61e";
request.body = "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.";
request.label = "refund_failure";
request.notification_event = NotificationEvent.transaction_success;
request.html = false;
NotificationTemplateResponse result = new Notifications().updateTemplate(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var notificationRequest = new NotificationTemplateUpdateRequest
{
_id = "585b9aa7bce8378c54a8a61e",
body = "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created.",
label = "refund_failure",
notification_event = NotificationEvent.transaction_success,
html = false
};
var result = await new Notifications().UpdateTemplate(notificationRequest);
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "template",
"data": {
"created_at": "2016-12-22T09:19:35.577Z",
"updated_at": "2016-12-22T09:19:44.221Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} edited",
"_id": "585b9aa7bce8378c54a8a61e"
}
}
}
POST /v1/notifications/templates/{_id}
Update a notification template (available only in email and SMS type of notifications).
| Name | Description | Details |
|---|---|---|
| _id | ID of notification template | String, required |
| body | Use custom text or/and predefined variables, in which PayDock automatically pull values from customer, charge or subscription data objects. | String, required |
| label | Name of current template to identify it further | String, required |
| notification_event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
| html | Body could be in html or plain text format. Allowed values ‘true’, ‘false’, default is ‘false’ | Boolean, optional |
Get notification template
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/templates" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc->getTemplates()
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTemplatesResponse response = new Notifications().getTemplates();
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Notifications().GetTemplates();
"Example of response"
{
"status": 200,
"error": null,
"resource": {
"type": "templates",
"data": [
{
"_id": "59cc90516021e26d049037aa",
"created_at": "2017-09-28T06:01:53.483Z",
"updated_at": "2017-09-28T06:01:53.483Z",
"body": "Your subscription transaction has failed - email support@paydock.com now!",
"label": "Subscription Transaction Failed Template",
"notification_event": "subscription_transaction_failure",
"html": false
},
{
"_id": "59c4ade26021e26d048fb090",
"created_at": "2017-09-22T06:29:54.343Z",
"updated_at": "2017-09-22T06:29:54.343Z",
"body": "Transaction success!",
"label": "Transaction success template",
"notification_event": "transaction_success",
"html": true
}
],
"count": 2,
"limit": 100,
"skip": 0
}
}
GET /v1/notifications/templates/
Returns notification templates limited to 100.
Get notification template by id
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications/templates/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc->getTemplates()
->withTemplateId("56a0b80e489dc5402557d5e3")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTemplateResponse response = new Notifications().getTemplate("56a0b80e489dc5402557d5e3");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().GetTemplate("56a0b80e489dc5402557d5e3");
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "template",
"data": {
"_id": "59deb0f243852f0fa39e73cd",
"created_at": "2017-10-12T00:01:54.996Z",
"updated_at": "2017-10-12T00:01:54.996Z",
"body": "This is an example Transaction Success Notification Template",
"label": "Transaction Success Notification Template",
"notification_event": "transaction_success",
"html": true
}
}
}
GET /v1/notifications/templates/{id}
Get specific notification template by template id.
Delete notification template
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/templates/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/templates/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc->deleteTemplate("56a0b80e489dc5402557d5e3")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTemplateResponse response = new Notifications().deleteTemplate("56a0b80e489dc5402557d5e3");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().DeleteTemplate("56a0b80e489dc5402557d5e3");
"Example of response (201)"
{
"status": 200,
"error": null,
"resource": {
"type": "template",
"data": {
"created_at": "2016-01-21T10:50:54.403Z",
"updated_at": "2016-01-21T10:52:32.665Z",
"label": "Sms first template",
"notification_event": "transaction_success",
"body": "Charge {{CHARGE_ID}} with {{AMOUNT}} {{CURRENCY}} created. ",
"_id": "56a0b80e489dc5402557d5e3"
}
}
}
DELETE /v1/notifications/templates/{_id}
Delete a notification template.
| Name | Description | Details |
|---|---|---|
| _id | Template ID | String, required |
Add notification trigger
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications',
body: {
"event":"transaction_success",
"destination":"http://webhooks.com/",
"type":"webhook"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-addTrigger("webhook", "https://www.paydock.com", "56a0b80e489dc5402557d5e3", "refund_failure")
->call();
?>
curl -X "POST" "https://api-sandbox.paydock.com/v1/notifications" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"event\":\"transaction_success\",\"destination\":\"http://webhooks.com\,\"type\":\"webhook\"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTriggerRequest request = new NotificationTriggerRequest();
request.type = NotificationTriggerType.webhook;
request.destination = "https://www.paydock.com";
request.template_id = "56a0b80e489dc5402557d5e3";
request.event = NotificationEvent.transaction_success;
NotificationTriggerResponse response = new Notifications().addTrigger(request);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new NotificationTriggerRequest
{
type = NotificationTriggerType.webhook,
destination = "https://www.paydock.com",
template_id = "56a0b80e489dc5402557d5e3",
eventTrigger = NotificationEvent.transaction_success
};
var response = await new Notifications().AddTrigger(request);
"Example of response (201)"
{
"status": 201,
"error": null,
"resource": {
"type": "notification",
"data": {
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "55a634a48d7127722432c6a6"
}
}
}
POST /v1/notifications
Created a trigger to send a notification to a customer or endpoint. To send an email or SMS to a customer, use swap values (eg {{PHONE}} or {{EMAIL}}) which are loaded from the customer (See Swap Values for templates for the full list).
| Name | Description | Details |
|---|---|---|
| type | type of notification: ‘webhook’, ‘email’, ‘sms’ | String, required |
| destination | Where to send notification (URL for webhook, email address for email ({{EMAIL}} for current customer), phone number in international E.164 format ({{PHONE}} for current customer)) | String, required |
| template_id | Custom template, which can be used with email or sms notifications. | String, required for email or sms |
| event | Event to trigger notification: ‘transaction_success’, ‘transaction_failure’, ‘subscription_transaction’, ‘subscription_transaction_failure’, ‘subscription_creation_success ’, ‘subscription_creation_failure’, ‘subscription_updated’, ‘subscription_finished’, ‘subscription_failed’, ‘refund_requested’, ‘refund_successful’, ‘refund_failure’, ‘card_expiration_warning’ | String, required |
Get notification trigger list
curl -X "GET" "https://api-sandbox.paydock.com/v1/notifications" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/notifications',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-getTriggers()
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTriggerItemsResponse response = new Notifications().getTriggers();
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var response = await new Notifications().GetTriggers();
"Examle of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "notifications",
"data": [
{
"event": "transaction_failure",
"destination": "samwashington@gmail.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);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-getTriggers()
->withTriggerId("55a634a48d7127722432c6a6")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTriggerResponse response = new Notifications().getTrigger("55a634a48d7127722432c6a6");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().GetTrigger("55a634a48d7127722432c6a6");
"Example of response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "notification",
"data": {
"event": "transaction_success",
"destination": "http://webhooks.com/",
"type": "webhook",
"_id": "585ba240e45b75bc3680879e"
}
}
}
GET /v1/notifications/{_id}
Retrive details on a specific notification.
| Name | Description | Details |
|---|---|---|
| _id | Notification ID | String, required |
Delete notification trigger
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/notifications/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-deleteTrigger("55a634a48d7127722432c6a6")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationTriggerResponse response = new Notifications().deleteTrigger("55a634a48d7127722432c6a6");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().DeleteTrigger("55a634a48d7127722432c6a6");
"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&relation_id=6942a240e45b75bc3680881e" \
-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",
"relation_id": "6942a240e45b75bc3680881e"
},
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-getLog(["created_at.from" => "2017-01-01", "created_at.to" => "2018-01-01"])
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationLogResponse response = new Notifications().getLog("5a4c1e9e1e56ef239fa1776a");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new NotificationLogRequest
{
success = true,
created_at_from = new DateTime(2017,12,03),
created_at_to = new DateTime(2018,01,04)
};
var result = await new Notifications().GetLogs(request);
"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": "samwashington@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": "samwashington@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": "samwashington@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}&relation_id={relation_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 |
| relation_id | Related Subscription/Charge/Transaction ID | String, optional |
Archive notification log
curl -X "DELETE" "https://api-sandbox.paydock.com/v1/notifications/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
var request = require('request');
request({
url: 'https://api.paydock.com/v1/notifications/{_id}',
method: 'DELETE',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$res = $svc-archiveLog("12342347567562")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationLogResponse response = new Notifications().deleteLog("5a4c1e9e1e56ef239fa1776a");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().DeleteLog("5a5558437b46251e2d1d69e3");
"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": "samwashington@gmail.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 |
Resend webhook notification
curl -X "PUT" "https://api-sandbox.paydock.com/v1/notifications/logs/{_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/logs/{_id}',
method: 'PUT',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Notifications();
$response = $svc->resend("5a5ff68c592e9f5af60ce0db")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
NotificationLogResponse response = new Notifications().resendNotification("5a5ff68c592e9f5af60ce0db");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Notifications().ResendNotification("5a5ff68c592e9f5af60ce0db");
{
"status": 200,
"error": null,
"resource": {
"type": "notification_log",
"data": {
"__v": 0,
"company_id": "5a24d538dfaa611293b23e0a",
"created_at": "2018-01-17T05:48:50.817Z",
"success": true,
"type": "webhook",
"destination": "https://www.paydock.com",
"notification_id": "5a5edb87ead9d068b848c76f",
"parent_id": "5a5edb87ead9d068b848c76f",
"event": "transaction_success",
"response_status": "200",
"_id": "5a5ee3c23ec544470e02441c",
"archived": false
}
}
}
PUT /v1/notifications/logs/{_id}
Resend webhook notification.
| 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 cards or Direct Debit account details. It is a disposable token for creating charges/subscriptions/customers or updating customers. One-time tokens expire after 3 hours.
Tokens can also be created using:
Here is an example of creating one-time token using direct API request:
curl -X "POST https://api-sandbox.paydock.com/v1/payment_sources/tokens?public_key=[your_public_key]" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
-d "{\"first_name\":\"Samantha\",\"last_name\":\"Washington\",\"phone\":\"+12345678910\",\"address_line1\":\"Suite 660\",\"address_line2\":\"822 Ruiz Square\",\"address_city\":\"Lake Edward\",\"address_state\":\"TAS\",\"address_country\":\"AU\",\"address_postcode\":\"1324\",\"gateway_id\":\"551bb4af43daf16f355ab259\",\"card_name\":\"Samantha Washington\",\"card_number\":\"4200000000000000\",\"expire_month\":\"01\",\"expire_year\":\"17\",\"card_ccv\":\"123\"}"
"Credit cards 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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone":"+12345678910",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"gateway_id": "551bb4af43daf16f355ab259",
"card_name":"Samantha Washington",
"card_number":"4200000000000000",
"expire_month":"01",
"expire_year":"21",
"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": "Samantha",
"last_name": "Washington",
"email": "samwashington@gmail.com",
"phone":"+12345678910",
"address_line1": "Suite 660",
"address_line2": "822 Ruiz Square",
"address_city": "Lake Edward",
"address_state": "TAS",
"address_country": "AU",
"address_postcode": "1234",
"type":"bank_account",
"gateway_id": "584125e4990f62cf1457996a",
"account_name":"Samantha Washington",
"account_number":"064000",
"account_bsb":"064000"
},
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
"Credit ??ards example"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Tokens();
return $svc->create("Samantha", "Washington")
->withCreditCard("551bb4af43daf16f355ab259", "4111111111111111", "2020", "10", "Samantha Washington", "123")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Direct Debit example"
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Tokens();
return $svc->create("Samantha", "Washington")
->withBankAccount("551bb4af43daf16f355ab259", "test", "012003", "456456")
->includeAddress("822 Ruiz Square", "", "NSW", "Australia", "Sydney", "2000")
->call();
?>
"Credit ??ards example"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
TokenRequest tokenRequest = new TokenRequest();
tokenRequest.gateway_id = "5a272651a527bf12a4c904c9";
tokenRequest.email = "samwashington@gmail.com";
tokenRequest.card_name = "Samantha Washington";
tokenRequest.card_number = "5520000000000000";
tokenRequest.expire_month = "05";
tokenRequest.expire_year = "2018";
tokenRequest.card_ccv = "123";
TokenResponse token = new Tokens().create(tokenRequest);
"Direct Debit example"
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
TokenRequest tokenRequest = new TokenRequest();
tokenRequest.gateway_id = "5a497ece1e56ef239fa16345";
tokenRequest.type = PaymentType.bsb;
tokenRequest.account_bsb = "064000";
tokenRequest.account_number = "064000";
TokenResponse token = new Tokens().create(tokenRequest);
"Credit ??ards example"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new TokenRequest
{
gateway_id = "5a272651a527bf12a4c904c9",
card_name = "Samantha Washington",
card_number = "4111111111111111",
card_ccv = "123",
expire_month = "10",
expire_year = "2020"
};
var result = await new Tokens().Create(request);
"Direct Debit example"
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new TokenRequest
{
gateway_id = "5a278586a527bf12a4c90521",
type = PaymentType.bsb,
account_name = "Jimmy Jones",
account_bank_name = "Bank of Australia",
account_bsb = "062184",
account_number = "12341234"
};
var result = await new Tokens().Create(request);
"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 ‘card’ for payments with credit cards. Use ‘bank_account’ for using bank account credentials. Parameter required when using direct Debit | String, required |
| card_name | Cardholder name (as on card) | String, required for card |
| card_number | Card number | Integer, required for card |
| expire_month | Card expiration month mm format | String, required for card |
| expire_year | Card expiration year yyyy format | String, required for card |
| card_ccv | Card CCV number | Integer, optional |
| account_name | Customer account name. Parameter required when using Direct Debit only | String, required for bsb |
| account_bsb | Customer bank state branch number. Parameter required when using Direct Debit only | String, required for bsb |
| account_number | Number of Customer account. Parameter required when using Direct Debit only | String, required for bsb and bank account |
| account_routing | Number of Customer account. BSB/Routing/SWIFT/IBAN Number. | String, required for bank account |
| account_holder_type | Account type (‘personal’ or ‘business’) | String, required for bank account |
| account_bank_name | Name of account bank | String, required for bank account |
| first_name | Customer first name | String, optional |
| last_name | Customer last name | String, optional |
| 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 |
| meta | Additional params | Object, optional |
| customer_storage_number | Identification of a customer on a gateway side for future payments binding (used by Bambora gateway) | String optional |
| tokenise_algorithm | Bambora alorithm Id for creating customers. (Default - 2, if not specified.) | Number 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\":\"GatewayType\",\"name\":\"Gateway Name\",\"username\":\"Gateway Username\",\"password\":\"Gateway Password\"}"
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways',
body: {
"type": "GatewayType",
"name": "Gateway Name",
"username": "username",
"password": "password",
"mode": "test"
},
method: 'POST',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Gateways();
$res = $svc->create("GatewayType", "Gateway Name", "<merchantid>", "<username>", "<password>", "test")
->call();
?>
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
GatewayRequest gateway = new GatewayRequest();
gateway.type = "GatewayType";
gateway.name = "Gateway Name";
gateway.merchant = "r7pcwvkbkgjfzk99";
gateway.username = "n8nktcb42fy8ttgt";
gateway.password = "c865e194d750148b93284c0c026e5f2a";
GatewayResponse response = new Gateways().add(gateway);
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var request = new GatewayRequest
{
type = "GatewayType",
name = "Gateway Name",
merchant = "r7pcwvkbkgjfzk99",
username = "n8nktcb42fy8ttgt",
password = "c865e194d750148b93284c0c026e5f2a"
};
var response = await new Gateways().Add(request);
"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": "GatewayType",
"name": "Gateway Name",
"username": "username",
"password": "password",
"_id": "5875d80c85ad563f58a9eebc",
"mode": "test",
"default": false
}
}
}
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 | API Key | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Braintree
| Name | Description | Details |
|---|---|---|
| type | value : ‘Brain’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | The merchant account ID | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Ezidebit
| Name | Description | Details |
|---|---|---|
| type | value : ‘Ezidebit’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Ezidebit 3.5 Version
| Name | Description | Details |
|---|---|---|
| type | value : ‘Ezidebit35’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Stripe
| Name | Description | Details |
|---|---|---|
| type | value : ‘Stripe’ | String, required |
| name | Name which will be presented gateway | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
PayPal
| Name | Description | Details |
|---|---|---|
| type | value : ‘Paypal’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
PayPal Express
| Name | Description | Details |
|---|---|---|
| type | value : ‘PaypalClassic’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of a gateway side | String, required |
| password | Password for gateway | String, required |
| signature | Signature of a gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Pin
| Name | Description | Details |
|---|---|---|
| type | value : ‘Pin’ | String, required |
| name | Name which will be presented gateway | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
PayWay
| Name | Description | Details |
|---|---|---|
| type | value : ‘PaywayRest’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Merchant Code | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
SecurePay
| Name | Description | Details |
|---|---|---|
| type | value : ‘Securepay’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
| default | Set gateway as default | Boolean, optional |
Authorize.net
| Name | Description | Details |
|---|---|---|
| type | value : ‘Authorize’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | API Login ID of gateway side | String, required |
| password | Transaction Key for a gateway | String, required |
| meta | Additional parameters | Object, optional |
| test_mode | Parameter to switch validaionMode parameter of a gateway. Use true to forcibly set validationMode “testMode” | Boolean optional |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Payment Express
| Name | Description | Details |
|---|---|---|
| type | value : ‘Paymentexpress’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| meta | Object with additional parameters | Object optional |
| meta.currency | Parameter need to specify currency for creating customers | String, optional |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
WorldPay
| Name | Details | Description |
|---|---|---|
| type | value : ‘Worldpay’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
NAB
| Name | Description | Details |
|---|---|---|
| type | value : ‘Nab’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Merchant Warrior
| Name | Description | Details |
|---|---|---|
| type | value : ‘Merchantwarrior’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
SQID
| Name | Description | Details |
|---|---|---|
| type | value : ‘Sqid’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Merchant Code | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
PromisePay
| Name | Description | Details |
|---|---|---|
| type | value : ‘PromisePay’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Forte
| Name | Description | Details |
|---|---|---|
| type | value : ‘Forte’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| merchant | Merchant Id of gateway side | String, required |
| signature | Signature of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Bambora
| Name | Description | Details |
|---|---|---|
| type | value : ‘IpPayments’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of gateway side | String, required |
| password | Password for gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Payeezy
| Name | Description | Details |
|---|---|---|
| type | value : ‘Payeezy’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Apikey on gateway side | String, required |
| password | Token on gateway side | String, required |
| signature | Security key on gateway side | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
| default | Set gateway as default | Boolean, optional |
FatZebra
| Name | Description | Details |
|---|---|---|
| type | value : ‘FatZebra’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username on gateway side | String, required |
| password | Token on gateway side | String, required |
| mode | defaults to test and in case for production mode is have to be live | String, optional |
| default | Set gateway as default | Boolean, optional |
Paperless
| Name | Description | Details |
|---|---|---|
| type | value : ‘Paperless’ | String, required |
| name | Name which will be presented gateway | String, required |
| merchant | Merchant of a gateway | String, required |
| username | Terminal ID of a gateway side | String, required |
| password | Terminal key for a gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
ZipMoney
| Name | Description | Details |
|---|---|---|
| type | value : ‘Zipmoney’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of a gateway side | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Afterpay
| Name | Description | Details |
|---|---|---|
| type | value : ‘Afterpay’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of a gateway side | String, required |
| password | Password of a gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Flo2Cash
| Name | Description | Details |
|---|---|---|
| type | value : ‘Flo2Cash’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of a gateway side | String, required |
| password | Password of a gateway | String, required |
| merchant | Merchant ID of a gateway | String, required |
| signature | Sub Account Id of a gateway side | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Split Payments
| Name | Description | Details |
|---|---|---|
| type | value : ‘SplitPayments’ | String, required |
| name | Name which will be presented gateway | String, required |
| password | Personal access token. Can be found in “Your applications” on a gateway side | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
| default | Set gateway as default | Boolean, optional |
Bpoint
| Name | Description | Details |
|---|---|---|
| type | value : ‘Bpoint’ | String, required |
| name | Name which will be presented gateway | String, required |
| username | Username of a gateway side | String, required |
| password | Password of a gateway | String, required |
| merchant | Merchant of a gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
Mastercard Payment Gateway Services
| Name | Description | Details |
|---|---|---|
| type | value : ‘MasterCard’ | String, required |
| name | Gateway Label | String, required |
| username | MasterCard Merchant ID | String, required |
| password | Password of a gateway | String, required |
| merchant | Merchant of a gateway | String, required |
| mode | Defaults to ‘test’, must be ‘live’ for production mode | String, optional |
Get payment gateway
var request = require('request');
request({
url: 'https://api-sandbox.paydock.com/v1/gateways/{_id}',
method: 'GET',
headers: {
'content-type' : 'application/json',
'x-user-secret-key': 'user_secret_key'
}
}, function(error, response, body){
if(error) {
console.log(error);
} else {
console.log(response.statusCode, body);
}
});
<?php
Config::initialise("sandbox", "<secret key>", "<public key>");
$svc = new Gateways();
$res = $svc->get()
->withId("582eb40446ab09c34205bc82")
->call();
?>
curl -X "GET" "https://api-sandbox.paydock.com/v1/gateways/{_id}" \
-H "x-user-secret-key: x-user-secret-key" \
-H "Content-Type: application/json" \
import com.paydock.javasdk.PayDock;
Config.initialise(Environment.Sandbox, "SecretKey", "PublicKey");
GatewayItemResponse result = new Gateways().get("582eb40446ab09c34205bc82");
using Paydock_dotnet_sdk.Services;
Config.Initialise(Environment.Sandbox, "SecretKey", "PublicKey");
var result = await new Gateways().Get("582eb40446ab09c34205bc82");
"Example of Response (200)"
{
"status": 200,
"error": null,
"resource": {
"type": "gateway",
"data": {
"_id": "582eb40446ab09c34205bc82",
</