The Ezypay Developer Hub

Welcome to the Ezypay developer hub. You'll find comprehensive guides and documentation to help you start working with Ezypay as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

About Us

 

Welcome to Ezypay’s API documentation. Here you have access to an open suite of APIs and technical documentation that will enable a seamless integration of Ezypay’s subscription billing services into your business software.

Ezypay is a cloud based payment platform specialising in the provision of subscription and recurring direct debit payments. We automate the collection of recurring payment and recover lost revenue from failed and outstanding payments to help improve your revenue collection rate.

Developers can use the APIs to leverage our core services:

  • Set up flexible payment plans across multiple business sites
  • Schedule automated routine processes to collect recurring payments for a variety of payment methods
  • Set up automated failed payment settings to handle automatic rebilling
  • Get a variety of reports (settlement, tax invoices) for your reporting needs

The Ezypay platform is PCI DSS (Payment Card Industry Data Security Standard) accredited, ensuring that all your customer debit and credit card handling, billing and payments processed via our APIs are achieved at the highest level of security.

Get in touch to partner with us.

Need more information about Ezypay? Visit our About Us page or send us an enquiry.

Authentication

 

The Ezypay APIs use bearer tokens for authorization. To get your token for the first time, make a request to our Get Access Token endpoint:

curl -X POST \
  https://identity-sandbox.ezypay.com/token \
  -H 'Authorization: application/x-www-form-urlencoded' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={username}&password={password}&client_id={client_id}&client_secret={client_secret}&scope=integrator%20billing_profile%20create_payment_method%20offline_access'

You can get your username, password, clientId and clientSecret from the Welcome Email that was sent to you when you signed up. To use your tokens, include it in the header of your requests:

-H "Authorization: Bearer {access_token}"

For security reasons, tokens expire in an hour. To refresh a token, call our Refresh Token endpoint:

curl -X POST \
  https://identity-sandbox.ezypay.com/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id={clientId}&client_secret={clientSecret}&refresh_token={refreshToken}'

All requests must be sent over HTTPS

If no token is provided, or an invalid one is provided, an Authentication Error is returned. That error should be in the following format:

{
    "type": "authentication_error",
    "code": 400,
    "message": "400 - {\"error\":\"invalid_grant\",\"error_description\":\"The credentials provided were invalid.\"}"
}

Sandbox

 

To help you build your integration, we have setup a full sandbox environment for you. Test out our APIs in your code, or right here on this page. Once you're ready to go live, simply switch all your integration points to the following:

  • identity-sandbox.ezypay.com/the_api to identity.ezypay.com/the_api
  • vault-sandbox.ezypay.com/the_api to vault.ezypay.com/the_api
  • api-sandbox.ezypay.com/the_api to api-global.ezypay.com/the_api

Remember

Sandbox is a scaled down replica of our production environment. Please use the sandbox environment for testing purposes only.

Customer

 

Create a customer

Create a customer. The system does not check for duplications when a new customer is created.

 
posthttps://api-sandbox.ezypay.com/v2/billing/customers
{  
   "firstName":"Jane",
   "lastName":"Doe",
   "customerNumber":null,
   "email":"Jane.Doe@gmail.com",
   "gender":null,
   "address":null,
   "homePhone":null,
   "mobilePhone":null,
   "companyName":null,
   "dateOfBirth":null,
   "referenceCode":null,
   "metadata": {
        "foo": "bar"
    }
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"55220ffc-bc5a-4f50-adaf-fa58c061ebd1",
   "number":"EZY213000",
   "referenceCode":null,
   "firstName":"Jane",
   "lastName":"Doe",
   "email":"Jane.Doe@gmail.com",
   "companyName":null,
   "mobilePhone":null,
   "homePhone":null,
   "gender":null,
   "dateOfBirth":null,
   "createdOn":"2019-03-10T20:10:54.895",
   "address":null,
   "metadata": {
        "foo": "bar"
    }
}

Body Params

firstName
string
required

Customer's first name. Max of 50 characters.

lastName
string
required

Customer's last name. Max of 50 characters.

email
string
required

A valid email address that belongs to customer. Max of 255 characters.

gender
string

Customer gender. Supported values are male or female.

address
object

The customer's address object that holds address details.

address.address1
string

The first line of the address. Max of 100 characters.

address.address2
string

The second line of the address. If there are no details for this field, you may leave this field blank. Max of 100 characters.

address.postalCode
string

The postal code of the address. Max of 20 characters.

address.city
string

The town/city of the address. Max of 100 characters.

address.state
string

The state of the address. Max of 100 characters.

address.countryCode
string

Two letter ISO 3166-1 alpha-2 country code.

homePhone
string

Customer home phone number. Max of 50 characters.

mobilePhone
string

Customer mobile phone number. Max of 50 characters.

companyName
string

The company name if the company is registered as a customer. Max of 100 characters.

dateOfBirth
string

Customer's date of birth. Supported format is YYYY-MM-DD.

referenceCode
string

Reference code that can be defined by you. This can be used to store a code used by your application to identify the customer. Max of 30 characters.

metadata
object

Store additional data about the customer object using key/value pairs format.

customerNumber
string

Specify an existing unique customer number to associate this customer with an existing customer of the same number. If this is a new customer, leave this field blank and a new unique customer number will be auto-generated and associated to this customer.

Headers

merchant
string
required

Merchant ID

 

List customers

Retrieve a list of customers that belong to the merchant.

 
gethttps://api-sandbox.ezypay.com/v2/billing/customers
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/customers \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/customers',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/customers");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "4396988a-d8f4-4d29-a211-8be5ca2b7877",
            "number": "EZY1000374672",
            "referenceCode": "xxx",
            "firstName": "John",
            "lastName": "Doe",
            "email": "John.Doe@gmail.com",
            "companyName": "Ezypay",
            "mobilePhone": "0402141110",
            "homePhone": null,
            "gender": "male",
            "dateOfBirth": null,
            "createdOn": "2018-08-13T06:21:19.899",
            "address": {
                "address1": "Test address 1",
                "address2": null,
                "postalCode": null,
                "state": null,
                "countryCode": "AU",
                "city": null
            },
            "metadata": null
        },
        {
            "id": "1c1c346a-4ff7-4233-a9d2-452b53610196",
            "number": "EZY1000568071",
            "referenceCode": null,
            "firstName": "Jane",
            "lastName": "Doe",
            "email": "Jane.Doe@gmail.com",
            "companyName": null,
            "mobilePhone": null,
            "homePhone": null,
            "gender": null,
            "dateOfBirth": null,
            "createdOn": "2019-03-05T04:14:40.883",
            "address": null,
            "metadata": null
        }
      ]
}

Query Params

name
string

Customer's name. Max 100 characters.

firstName
string

Customer's first name. Max 50 characters.

lastName
string

Customer's last name. Max 50 characters.

companyName
string

The company name if the company is registered as a customer.

referenceCode
string

The reference code of the customer. A unique identifier from a third-party software integration.

customerNumber
string

Auto-generated unique customer number. This unique identifier is customer facing and used to uniquely identify a customer across merchants.

createdDate
string

The date the customer's record was created.

sortExpression
string

Apply the expression to sort the customer's list based on the preferred argument. For e.g., enter lastname,ASC to sort the customer list in alphabetical order based on the lastname parameter.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Retrieve a customer

Retrieve the personal details of a customer.

 
gethttps://api-sandbox.ezypay.com/v2/billing/customers/customerId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "031d6fd8-f181-402a-82a3-68056639f3c0",
    "number": "EZY1000670942",
    "referenceCode": null,
    "firstName": "John",
    "lastName": "Tester",
    "email": "John.Tester@gmail.com",
    "companyName": null,
    "mobilePhone": null,
    "homePhone": null,
    "gender": "male",
    "dateOfBirth": "1980-06-13",
    "createdOn": "2019-06-25T02:33:07.264",
    "address": {
        "address1": "13 Testaburger Road",
        "address2": null,
        "postalCode": "90210",
        "state": "New South Wales",
        "countryCode": "AU",
        "city": "Testville"
    },
    "metadata": {
        "foo": "bar"
    }
}

Path Params

customerId
string
required

Auto-generated identifier of the customer.

Headers

merchant
string
required

Merchant ID

 

Update a customer

Update an existing customer's personal details.

 
puthttps://api-sandbox.ezypay.com/v2/billing/customers/customerId
{  
   "firstName":"Jane",
   "lastName":"Doe",
   "customerNumber":null,
   "email":"Jane.Doe@gmail.com",
   "gender":null,
   "address":null,
   "homePhone":null,
   "mobilePhone":null,
   "companyName":null,
   "dateOfBirth":"1980-12-08",
   "referenceCode":null,
   "metadata": {
        "foo": "bar"
    }
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"55220ffc-bc5a-4f50-adaf-fa58c061ebd1",
   "number":"EZY213000",
   "referenceCode":null,
   "firstName":"Jane",
   "lastName":"Doe",
   "email":"Jane.Doe@gmail.com",
   "companyName":null,
   "mobilePhone":null,
   "homePhone":null,
   "gender":null,
   "dateOfBirth":"1980-12-08",
   "createdOn":"2019-03-10T20:10:54.895",
   "address":null,
   "metadata": {
        "foo": "bar"
    }
}

Path Params

customerId
string
required

Auto-generated identifier of the customer.

Body Params

email
string
required

A valid email address that belongs to the customer. Max of 255 characters.

firstName
string
required

Customer's first name. Max of 50 characters.

lastName
string
required

Customer's last name. Max of 50 characters.

gender
string

Customer gender. Supported values are male or female.

homePhone
string

Customer home phone number. Max of 50 characters.

mobilePhone
string

Customer mobile phone number. Max of 50 characters.

referenceCode
string

The reference code of the customer. A unique identifier from a third-party software integration. Max of 30 characters.

companyName
string

The company name if the company is registered as a customer. Max of 100 characters.

dateOfBirth
string

Customer's date of birth. Supported format is YYYY-MM-DD.

address
object

The customer's address object that holds address details.

address.address1
string

The first line of the address. Max of 100 characters.

address.address2
string

The second line of the address. If there are no details for this field, you may leave this field blank. Max of 100 characters.

address.postalCode
string

The postal code of the address. Max of 20 characters.

address.city
string

The town/city of the address. Max of 100 characters.

address.state
string

The state of the address. Max of 100 characters.

address.countryCode
string

Two letter ISO 3166-1 alpha-2 country code.

Headers

merchant
string
required

Merchant ID

 

Payment Methods

 

List payment methods

Retrieve a list of payment methods and the details for an existing customer. The list would include both valid and invalid payment methods.

 
gethttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "paymentMethodToken": "96c77042-abe6-4cb0-8369-020687f1eeab",
            "customerId": "031d6fd8-f181-402a-82a3-68056639f3c0",
            "type": "CARD",
            "bank": null,
            "card": {
                "first6": "411111",
                "last4": "1111",
                "accountHolderName": "AU Test User",
                "type": "VISA",
                "expiryMonth": "01",
                "expiryYear": "99"
            },
            "invalidReason": null,
            "lastUsedOn": null,
            "valid": true,
            "primary": true
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Path Params

customerId
string
required

Auto-generated unique identifier of the customer.

Query Params

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Create a payment method

Links a new payment method token to an existing customer. If the customer has no primary payment method specified, then the new token will become the primary payment method by default. No verification is performed during the linking of payment method.

 
posthttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods
{  
   "paymentMethodToken":"187b485f-1f40-4c35-8c0d-81f87888ffcd",
   "primary":true
}
A binary file was returned

You couldn't be authenticated

{  
   "paymentMethodToken":"187b485f-1f40-4c35-8c0d-81f87888ffcd",
   "customerId":"37a2e1dd-c1d9-4fda-a077-6908877aa84c",
   "type":"CARD",
   "bank":null,
   "card":{  
      "first6":"498765",
      "last4":"8769",
      "accountHolderName":"JaneDoe",
      "type":"VISA",
      "expiryMonth":"12",
      "expiryYear":"25"
   },
   "invalidReason":null,
   "lastUsedOn":null,
   "valid":true,
   "primary":true
}

Path Params

customerId
string
required

Auto-generated unique identifier of the customer that will be associated with the payment method token.

Body Params

paymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by the Ezypay Vault.

primary
boolean

Specifies this token as the customer's preferred token for making payments. Supported values are true and false. If the customer has no primary payment method specified, then the new token will become the primary payment method by default. However, if the owner already has a primary payment method, then it will not change unless primary is set to true.

Headers

merchant
string
required

Merchant ID

 

Retrieve primary payment method

Retrieve the payment method details of the customer's primary payment method.

 
gethttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "paymentMethodToken":"187b485f-1f40-4c35-8c0d-81f87888ffcd",
   "customerId":"37a2e1dd-c1d9-4fda-a077-6908877aa84c",
   "type":"CARD",
   "bank":null,
   "card":{  
      "first6":"498765",
      "last4":"8769",
      "accountHolderName":"JaneDoe",
      "type":"VISA",
      "expiryMonth":"12",
      "expiryYear":"25"
   },
   "invalidReason":null,
   "lastUsedOn":null,
   "valid":true,
   "primary":true
}

Path Params

customerId
string
required

Auto-generated unique identifier of the customer.

Headers

merchant
string

Merchant ID

 

Retrieve a payment method

Retrieves the payment method token details that belong to a customer.

 
gethttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "paymentMethodToken": "96c77042-abe6-4cb0-8369-020687f1eeab",
    "customerId": "031d6fd8-f181-402a-82a3-68056639f3c0",
    "type": "CARD",
    "bank": null,
    "card": {
        "first6": "411111",
        "last4": "1111",
        "accountHolderName": "AU Test User",
        "type": "VISA",
        "expiryMonth": "01",
        "expiryYear": "99"
    },
    "invalidReason": null,
    "lastUsedOn": null,
    "valid": true,
    "primary": true
}

Path Params

paymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by the Ezypay Vault.

customerId
string
required

Auto-generated unique identifier of the customer.

Headers

merchant
string
required

Merchant ID

 

Delete a payment method

Remove an obsolete or invalid payment method from a customer. Removing a payment method will also delete the payment method token from the Ezypay Vault if no other customers are linked to that token. However, a payment method with an active subscription or is the customer’s only (i.e. primary) payment method cannot be removed.

 
deletehttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken
curl --request DELETE \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken
var request = require("request");

var options = { method: 'DELETE',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

paymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by vault.

customerId
string
required

Auto-generated unique identifier of the customer.

Headers

merchant
string

Merchant ID

 

Replace a payment method

Replace a payment method with another payment method while keeping all existing customer, subscription and invoice links. This is useful when replacing invalid payment methods to existing customers without needing to additionally update their subscription and invoice details.

 
puthttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "paymentMethodToken":"187b485f-1f40-4c35-8c0d-81f87888ffcd",
   "customerId":"37a2e1dd-c1d9-4fda-a077-6908877aa84c",
   "type":"CARD",
   "bank":null,
   "card":{  
      "first6":"498765",
      "last4":"8769",
      "accountHolderName":"JaneDoe",
      "type":"VISA",
      "expiryMonth":"12",
      "expiryYear":"25"
   },
   "invalidReason":null,
   "lastUsedOn":null,
   "valid":true,
   "primary":true
}

Path Params

paymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by vault.

customerId
string
required

Auto-generated unique identifier of the customer.

Body Params

newPaymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by vault.

primary
string

Indicator to set this payment method as Customer's preferred Payment Method

Headers

merchant
string
required

Merchant ID

 

Update primary payment method

Change the primary payment method token for an existing customer. Ensure that the new primary token is valid prior to the request.

 
puthttps://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "paymentMethodToken":"187b485f-1f40-4c35-8c0d-81f87888ffcd",
   "customerId":"37a2e1dd-c1d9-4fda-a077-6908877aa84c",
   "type":"CARD",
   "bank":null,
   "card":{  
      "first6":"498765",
      "last4":"8769",
      "accountHolderName":"JaneDoe",
      "type":"VISA",
      "expiryMonth":"12",
      "expiryYear":"25"
   },
   "invalidReason":null,
   "lastUsedOn":null,
   "valid":true,
   "primary":true
}

Path Params

paymentMethodToken
string
required

Auto-generated unique identifier of the payment method token generated by vault.

customerId
string
required

Auto-generated unique identifier of the customer.

Headers

merchant
string
required

Merchant ID

 

Invoices

 

List invoices

Get a list of invoices for a specific merchant, customer or subscription. The invoices are returned sorted by creation date, with the most recently created invoice appearing first.

 
gethttps://api-sandbox.ezypay.com/v2/billing/invoices
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/invoices',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/invoices");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
            "documentNumber": "IN0000000000000628",
            "date": "2019-07-01",
            "dueDate": "2019-07-01",
            "scheduledPaymentDate": null,
            "status": "REFUNDED",
            "memo": null,
            "items": [
                {
                    "description": "testing",
                    "amount": {
                        "currency": "NZD",
                        "value": 100,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
                    "type": "on_demand_payment",
                    "discounted": {
                        "currency": "NZD",
                        "value": 0,
                        "type": null
                    },
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "amountWithoutDiscount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "totalDiscounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "totalRefunded": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "subscriptionId": null,
            "subscriptionName": null,
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
            "autoPayment": true,
            "createdOn": "2019-07-01T00:33:42.562"
        },
        {
            "id": "74ab6d8b-ed69-49f7-aee9-9214ef89512d",
            "documentNumber": "IN0000000000000597",
            "date": "2019-06-26",
            "dueDate": "2019-06-26",
            "scheduledPaymentDate": null,
            "status": "REFUNDED",
            "memo": null,
            "items": [
                {
                    "description": "testing",
                    "amount": {
                        "currency": "NZD",
                        "value": 100,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "id": "93052bff-21c2-4b5a-8227-88817b5acec8",
                    "type": "on_demand_payment",
                    "discounted": {
                        "currency": "NZD",
                        "value": 0,
                        "type": null
                    },
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "amountWithoutDiscount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "totalDiscounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "totalRefunded": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "subscriptionId": null,
            "subscriptionName": null,
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
            "autoPayment": true,
            "createdOn": "2019-06-26T05:13:22.955"
        },
    ],
    "paging": {
        "nextUrl": "https://api-staging.ezypay.com/v2/billing/invoices?limit=10&cursor=10",
        "nextCursor": 10,
        "limit": 10,
        "totalCount": 2
    }
}

Query Params

customerId
string

Filter by unique identifier of the customer.

subscriptionId
string

Filter by unique identifier of the subscription.

externalInvoiceId
string

Filter by unique identifier of the externalInvoiceId from integrator's system.

status
string

Filter by invoice status. Supported values are PAID, PROCESSING, PAST_DUE,UNPAID, REFUNDED and WRITTEN_OFF.

from
string

Start date for range of invoices to view. Filter by date defined in the invoice date.

until
string

Apply a limit to the number of objects to be returned. Supported limit range is 1 to 100. Defaults to 10.

limit
string

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
string

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Create an invoice

Create an ad-hoc invoice to bill a customer on an on-demand basis. Invoices created from this end point are not associated to any subscriptions.

 
posthttps://api-sandbox.ezypay.com/v2/billing/invoices
{  
   "customerId":"4c999653-9473-472e-b478-d56d2a7572a9",
   "paymentMethodToken":"d178cea3-fdf9-4743-90d8-856af429ab18",
   "items":[  
      {  
         "description":"testing",
         "amount":{  
            "currency":"NZD",
            "value":100
         },
         "accountingCode":null,
         "tax":{  
            "rate":0
         }
      }
   ],
   "processingModel":"cardonfile"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
    "documentNumber": "IN0000000000000628",
    "date": "2019-07-01",
    "dueDate": "2019-07-01",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "testing",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "autoPayment": true,
    "createdOn": "2019-07-01T00:33:42.562",      
    "processingModel": "CARD_ON_FILE"
    
}

Body Params

customerId
string
required

Identifier of the customer the invoice is billed to.

paymentMethodToken
string

An existing payment method token that was generated by the Ezypay Vault. If no value is provided the system will attempt to use the current default payment token associated with the customer. In the event that no value is provided and no default payment method is associated with the customer the system will create an invoice with a status of past_due.

memo
string

Description of the invoice item. Max of 100 characters.

items
array of objects
required

Details of the individual items that are included in the invoice.

autoPayment
string

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are: true - Default value. Invoices generated will automatically proceed to payment processing. false - Invoices are generated but will not automatically proceed to payment processing.

scheduledPaymentDate
string

Set the next scheduled payment date to have payment automatically attempted in the future. Must be at least one day after today's date but no more than one year (365 days). If null or no value is provided, attempts payment on invoice issue date. However, payment processing will only be attempted if autoPayment = true. Supported format is YYYY-MM-DD.

externalInvoiceId
string

An invoice id from integrator's system that works as a correlation id with the invoice from Ezypay's system, which helps to identify the invoice. It should be unique per merchant

processingModel
string

The processing model used when attempting payment against the invoice. Set to cardonfile when processing on-demand payments, and recurring if the invoice is associated with a recurring scheduled payment agreement. If no value is provided, the default value is recurring.

Headers

merchant
string
required

Merchant ID

 

Retrieve an invoice

Get the full details of an invoice.

 
gethttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "28d734bd-0cc5-4289-8129-d4b6a75d384b",
    "documentNumber": "IN0000000000004171",
    "date": "2019-06-25",
    "dueDate": "2019-06-28",
    "scheduledPaymentDate": null,
    "status": "WRITTEN_OFF",
    "memo": "this is a test invoice",
    "items": [
        {
            "description": "this is a test item",
            "amount": {
                "currency": "AUD",
                "value": 25.5,
                "type": null
            },
            "tax": {
                "rate": 10
            },
            "id": "268d7cf9-fead-46e9-8c5a-4d328981ed0c",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "AUD",
                "value": 0,
                "type": null
            },
            "accountingCode": "test-1561441342"
        }
    ],
    "amount": {
        "currency": "AUD",
        "value": 25.5,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 25.5,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "AUD",
        "value": 2.32,
        "type": null
    },
    "customerId": "f878f1d9-42cb-4447-9f51-4c405627712e",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "7f9e1ed3-5a23-4201-8401-78d8cc699e4c",
    "autoPayment": false,
    "createdOn": "2019-06-25T05:42:22.008"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Headers

merchant
string
required

Merchant ID

 

Update an invoice

Change the details of an invoice with status past_due such as the payment method token and next scheduled payment date. You can also apply a discount on an invoice item.

 
puthttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId
{  
   "paymentMethodToken":"d178cea3-fdf9-4743-90d8-856af429ab18",
   "items":[  
      {  
         "description":"testing",
         "amount":{  
            "currency":"NZD",
            "value":100
         },
         "accountingCode":null,
         "tax":{  
            "rate":0
         }
      }
   ]
}
A binary file was returned

You couldn't be authenticated

{
    "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
    "documentNumber": "IN0000000000000628",
    "date": "2019-07-01",
    "dueDate": "2019-07-01",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "testing",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "autoPayment": true,
    "createdOn": "2019-07-01T00:33:42.562"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Body Params

paymentMethodToken
string

The payment method token that will replace the invoice's current token.

scheduledPaymentDate
string

Set the next scheduled payment date to have payment automatically attempted in the future. Future date specified must be at least tomorrow's date (one day after today's date) but no more than one year (365 days). If future date is valid, payment will be attempted as autoPayment will always be set to true. Supported format is YYYY-MM-DD. If set to null, no scheduled payment will occur as autoPayment will be set to false. If no value is provided, the current value is retained.

items
array of objects
required

Details of the individual items that are included in the invoice.

Headers

merchant
string
required

Merchant ID

 

Record an external payment for an invoice

Record a payment from a customer that occurred outside the Ezypay billing system (for example an over-the-counter cash transaction) and mark the invoice as paid. Only applicable for invoices with status past_due.

 
posthttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/recordpayment"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
    "documentNumber": "IN0000000000000628",
    "date": "2019-07-01",
    "dueDate": "2019-07-01",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "testing",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "autoPayment": true,
    "createdOn": "2019-07-01T00:33:42.562"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Body Params

paymentMethodType
string

The external payment method used by the customer to pay for the invoice. Supported values are cash, cheque, card, others and bank_transfer.

Headers

merchant
string
required

Merchant ID

 

Refund an invoice

Refund an invoice. An online refund will reuse the same invoice payment method that was used in the original transaction. If the payment method associated with the invoice has been deleted or invalidated an error response will be returned containing an appropriate message.

The refund feature will refund the full invoice amount of the invoice including any customer paid fees collected. Ezypay's transaction fees will be allocated to the Merchant in the event a refund is successfully processed.

 
puthttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/refund"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
    "documentNumber": "IN0000000000000628",
    "date": "2019-07-01",
    "dueDate": "2019-07-01",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "testing",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "autoPayment": true,
    "createdOn": "2019-07-01T00:33:42.562"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Headers

merchant
string
required

Merchant ID

 

Retry a payment on an invoice

Retry a payment on-demand for an invoice with status past_due. Merchant billing must be enabled.

 
posthttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/retrypayment"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "5cfda744-1dc5-4f21-b020-fb648429bce9",
    "documentNumber": "IN0000000000000628",
    "date": "2019-07-01",
    "dueDate": "2019-07-01",
    "scheduledPaymentDate": null,
    "status": "PROCESSING",
    "memo": null,
    "items": [
        {
            "description": "testing",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "id": "110944ba-4f14-4ccf-bd72-9c5522ab5399",
            "type": "on_demand_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 100,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "subscriptionId": null,
    "subscriptionName": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "autoPayment": true,
    "createdOn": "2019-07-01T00:33:42.562"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Body Params

oneOff
string

Specify if the invoice will re-use the existing payment method token or use a different token as a one-off payment. Supported values are: false - The default value. Use the existing payment method token associated with this invoice. You do not need to provide a new payment method token. true - Use a different payment method token for this one-off payment. Specify the token in paymentMethodToken.

paymentMethodToken
string

Specify the payment method token that will be used for this payment. Only needs to be provided if oneOff is true. Future invoices will not be affected.

Headers

merchant
string
required

Merchant ID

 

Write off an invoice

Write-off an invoice on-demand for an invoice with status past_due. The invoice status will be set to writen_off and no billing retries will be attempted for that specific invoice.

 
posthttps://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/invoiceId/writeoff"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "3749a82a-7d11-4be2-9ad9-4f76590e5af5",
    "documentNumber": "420423",
    "date": "2017-12-02",
    "dueDate": "2017-12-02",
    "scheduledPaymentDate": null,
    "status": "WRITTEN_OFF",
    "memo": null,
    "items": [
        {
            "description": "Failed Payment Fee",
            "amount": {
                "currency": "NZD",
                "value": 8.5,
                "type": null
            },
            "tax": {
                "rate": 0.1
            },
            "id": "b9d62cd9-ce1e-4732-9449-446cbcfa3cb4",
            "type": "failed_payment_fee",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Standard Master/Visa Fee",
            "amount": {
                "currency": "NZD",
                "value": 11,
                "type": null
            },
            "tax": {
                "rate": 10
            },
            "id": "d3f696cc-2c00-4ca6-8090-f92804bda45f",
            "type": "transaction_fee",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": null
        },
        {
            "description": "Migration Subscription 2",
            "amount": {
                "currency": "NZD",
                "value": 100,
                "type": null
            },
            "tax": {
                "rate": 10
            },
            "id": "1042cc5e-edf4-4f4d-8bee-7e246d1a9534",
            "type": "subscription_payment",
            "discounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "accountingCode": "Membership"
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 119.5,
        "type": null
    },
    "amountWithoutDiscount": {
        "currency": "NZD",
        "value": 119.5,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalRefunded": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 10.1,
        "type": null
    },
    "customerId": "c00770d2-9547-4b5d-a00a-db3d9627e706",
    "subscriptionId": "68e17208-b70a-4588-880b-803ad85d1d11",
    "subscriptionName": "Migration Subscription 2",
    "paymentMethodToken": "ef0a2cbc-95d9-4877-abcd-d900acc38930",
    "autoPayment": false,
    "createdOn": "2017-11-27T06:47:07.860"
}

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Headers

merchant
string
required

Merchant ID

 

Credit Notes

 

List credit notes

Retrieve a list of credit notes. The results can be filtered using the available filter options. Must provide at least the customerId, subscriptionId or invoiceId.

 
gethttps://api-sandbox.ezypay.com/v2/billing/creditnotes
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/creditnotes \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/creditnotes',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/creditnotes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/creditnotes");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/creditnotes"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "adfd27f3-1443-44d7-a343-62802131dd21",
            "invoiceId": "d3b774c5-13b3-4461-935d-00abc26c0e8c",
            "documentNumber": "CN0000000000000001",
            "date": "2019-04-01",
            "status": "PAID",
            "items": [
                {
                    "description": "",
                    "amount": {
                        "currency": "NZD",
                        "value": 1.24,
                        "type": null
                    },
                    "tax": {
                        "rate": 0.1
                    },
                    "id": "4c59b609-8e8f-4685-8f76-30492c865f4c",
                    "type": "transaction_fee",
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 1.24,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "reason": "REFUND",
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18"
        },
        {
            "id": "07e0900b-aa12-4a7e-b52c-b976b9a0a50c",
            "invoiceId": "28265e52-d3de-44be-85a3-73e5fd980088",
            "documentNumber": "CN0000000000000002",
            "date": "2019-04-01",
            "status": "PAID",
            "items": [
                {
                    "description": "",
                    "amount": {
                        "currency": "NZD",
                        "value": 0.54,
                        "type": null
                    },
                    "tax": {
                        "rate": 0.1
                    },
                    "id": "7b9bc529-2716-40a8-821a-08ee51455060",
                    "type": "transaction_fee",
                    "accountingCode": null
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 0.54,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "reason": "REFUND",
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18"
        },
        
    ],
    "paging": {
        "nextUrl": "https://api-staging.ezypay.com/v2/billing/creditnotes?customerId=4c999653-9473-472e-b478-d56d2a7572a9&limit=10&cursor=10",
        "nextCursor": 10,
        "limit": 10,
        "totalCount": 2
    }
}

Query Params

customerId
string

Filter by unique identifier of the customer.

subscriptionId
string

Filter by unique identifier of the subscription.

invoiceId
string

Filter by unique identifier of the invoice.

status
string

Filter by credit notes status. Supported values are paid, processing, and failed.

reason
string

Filter by action taken on the invoice associated to the credit note. Supported values are chargeback and refund.

from
string

Start date for range of credit notes to view. Filter by date defined in creditNoteDate.

until
string

End date for range of credit notes to view. Filter by date defined in creditNoteDate.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
string

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Retrieve a credit note

Get the full details of a credit note

 
gethttps://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/creditnotes/creditNoteId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "adfd27f3-1443-44d7-a343-62802131dd21",
    "invoiceId": "d3b774c5-13b3-4461-935d-00abc26c0e8c",
    "documentNumber": "CN0000000000000001",
    "date": "2019-04-01",
    "status": "PAID",
    "items": [
        {
            "description": "",
            "amount": {
                "currency": "NZD",
                "value": 1.24,
                "type": null
            },
            "tax": {
                "rate": 0.1
            },
            "id": "4c59b609-8e8f-4685-8f76-30492c865f4c",
            "type": "transaction_fee",
            "accountingCode": null
        }
    ],
    "amount": {
        "currency": "NZD",
        "value": 1.24,
        "type": null
    },
    "totalTax": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "reason": "REFUND",
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18"
}

Path Params

creditNoteId
string
required

Auto-generated identifier of the credit note.

Headers

merchant
string
required

Merchant ID

 

Contact Email Address

 

Add email address for merchant contact

Add email for merchant contact

 
posthttps://api-sandbox.ezypay.com/v2/email
{
	"address": "John.Doe@gmail.com",
	"contactId":"67863a3a-0333-4b87-ba3b-af1b0d26d405",
	"isActive": "true"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "ac8da5f5-853b-470d-9463-3c3cfa198d7c",
    "address": "John.Doe@gmail.com",
    "contactId": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "isActive": true,
    "createdBy": "test@ezypay.com"
}

Body Params

address
string
required

Email address of the merchant

contactId
string
required

Auto generated identifier of merchant contact id

isActive
boolean

Determines whether contact is active or not.

 

Get email addresses by merchant contact id

Returns email addresses by merchant contact ID

 
gethttps://api-sandbox.ezypay.com/v2/email/merchantContactId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/email/merchantContactId
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/email/merchantContactId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/email/merchantContactId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/email/merchantContactId");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/email/merchantContactId"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "ac8da5f5-853b-470d-9463-3c3cfa198d7c",
    "address": "John.Doe@gmail.com",
    "contactId": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "isActive": true,
    "createdBy": "test@ezypay.com"
}

Path Params

merchantContactId
string
required

Auto generated identifier of merchant contact

 

Update an existing email address

Update an existing email address of merchant

 
puthttps://api-sandbox.ezypay.com/v2/email/emailAddressId
{
	"address": "John.Doe1@gmail.com",
	"contactId":"67863a3a-0333-4b87-ba3b-af1b0d26d405",
	"isActive": "true"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "d9c07857-a681-474b-97da-ecc860faccea",
    "address": "John.Doe1@gmail.com",
    "contactId": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "isActive": true,
    "createdBy": "test@ezypay.com"
}

Path Params

emailAddressId
string
required

Auto generated identifier of merchant contact

Body Params

address
string
required

Email address of the merchant

contactId
string
required

Auto generated identifier of merchant contact

isActive
boolean

Determines whether contact is active or not.

 

Future Invoices

 

List future invoices

Retrieve a list of future invoices. The results can then be filtered using the available filter options. Must provide at least the customerId or subscriptionId.

 
gethttps://api-sandbox.ezypay.com/v2/billing/futureinvoices
curl --request GET \
  --url 'https://api-sandbox.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until' \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/futureinvoices',
  qs:
   { subscriptionId: 'subscriptionId',
     customerId: 'customerId',
     from: 'from',
     until: 'until' },
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/futureinvoices"

querystring = {"subscriptionId":"subscriptionId","customerId":"customerId","from":"from","until":"until"}

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "subscriptionId": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "date": "2019-07-01",
            "cycleStartDate": "2019-07-01",
            "cycleEndDate": "2019-07-31",
            "items": [
                {
                    "description": "high_st_monthly_plan",
                    "amount": {
                        "currency": "NZD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "type": "subscription_payment",
                    "accountingCode": "customer_plan"
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            }
        },
        {
            "subscriptionId": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "date": "2019-08-01",
            "cycleStartDate": "2019-08-01",
            "cycleEndDate": "2019-08-31",
            "items": [
                {
                    "description": "high_st_monthly_plan",
                    "amount": {
                        "currency": "NZD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "type": "subscription_payment",
                    "accountingCode": "customer_plan"
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            }
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 2
    }
}

Query Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

customerId
string
required

Auto-generated unique identifier of the customer.

limit
int32

Maximum records to return per pagination call. Limit can range between 1 to 100 records.

from
string
required

Start date for range of future invoices to view. Supported format is YYYY-MM-DD.

until
string
required

End date for range of future invoices to view. Supported format is YYYY-MM-DD.

Headers

merchant
string
required

Merchant ID

 

Update a future invoice

Update the future invoice.

 
puthttps://api-sandbox.ezypay.com/v2/billing/futureinvoices
{
    "subscriptionId":"8be622ab-126a-4b99-85af-da6ff6007c90",
    "cycleStartDate":"2019-06-05",
    "date":"2019-06-07",
    "items" :[
    	{
        "description": "high_st_monthly_plan",
        "amount": {
          "currency": "NZD",
          "value": 200,
          "type": null
        },
        "tax": {
          "rate": 0
        },
        "type": "subscription_payment",
        "accountingCode": "customer_plan"
      }
    ]
}
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "subscriptionId": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "date": "2019-07-01",
            "cycleStartDate": "2019-07-01",
            "cycleEndDate": "2019-07-31",
            "items": [
                {
                    "description": "high_st_monthly_plan",
                    "amount": {
                        "currency": "NZD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "type": "subscription_payment",
                    "accountingCode": "customer_plan"
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            }
        },
        {
            "subscriptionId": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "date": "2019-08-01",
            "cycleStartDate": "2019-08-01",
            "cycleEndDate": "2019-08-31",
            "items": [
                {
                    "description": "high_st_monthly_plan",
                    "amount": {
                        "currency": "NZD",
                        "value": 200,
                        "type": null
                    },
                    "tax": {
                        "rate": 0
                    },
                    "type": "subscription_payment",
                    "accountingCode": "customer_plan"
                }
            ],
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "totalTax": {
                "currency": "NZD",
                "value": 0,
                "type": null
            }
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 2
    }
}

Body Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

cycleStartDate
string
required

The billing cycle start date. Supported format is YYYY-MM-DD.

date
string
required

The date the invoice will be issued to the customer. New date must be within cycleStartDate and cycleEndDate but cannot be today's date or more than one year (365 days) after the cycleStartDate. Supported format is YYYY-MM-DD.

items
array of objects

Details of the individual items that are included in the future invoice. Max of 255 characters.

Headers

merchant
string
required

Merchant ID

 

Delete a future invoice

Delete the future invoice.

 
deletehttps://api-sandbox.ezypay.com/v2/billing/futureinvoices
curl --request DELETE \
  --url https://api-sandbox.ezypay.com/v2/billing/futureinvoices \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api-sandbox.ezypay.com/v2/billing/futureinvoices',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/futureinvoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api-sandbox.ezypay.com/v2/billing/futureinvoices");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/futureinvoices"

headers = {'merchant': 'merchant'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "entityId":"6a72b162-f5f2-461a-be5f-4cdb3c37b553",
  "delete":"true"
}

Query Params

subscriptionId
string

Auto-generated unique identifier of the subscription.

cycleStartDate
string

The start date of the future invoice.

Headers

merchant
string
required

Merchant ID

 

Record an external payment for a future invoice

Record payment from a customer that occurred outside the Ezypay system (for example an over-the-counter cash transaction) on a future invoice of a subscription.
Ensures payments collected in advance externally from Ezypay can be reconciled and marked as paid. The future invoice will be issued immediately in advance as a paid invoice, with an external payment type recorded against it.

 
posthttps://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/futureinvoices/recordpayment"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

cycleStartDate
string
required

The billing cycle start date of the future invoice. Supported format is YYYY-MM-DD.

paymentMethodType
string
required

The external payment method used by the customer to pay for the invoice. Supported values are cash, cheque, card, others and bank_transfer.

Headers

merchant
string
required

Merchant ID

 

InvoiceBatches

 

List invoice batches

Get a list of invoice batches for a specific merchant. The invoice batches are returned sorted by creation date, with the most recently created invoice appearing first.

 
gethttps://api-sandbox.ezypay.com/v2/billing/invoices/batches
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/batches \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/invoices/batches',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/invoices/batches");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/batches"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "5c8e8f06-8d59-4957-8761-61b5fb85274b",
            "batchReference": "96025dfa-80e8-40aa-a8a4-4a4b71ad42e4",
            "createdOn": "2019-03-10T20:14:03.928",
            "status": "SUCCESS"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Query Params

status
string

Filter by invoice batch status. Supported values are SUBMITTED

batchReference
string

Filter by invoice batch reference.

from
string

Start date for range of invoices to view. Filter by date defined in the invoice date.

until
string

Apply a limit to the number of objects to be returned. Supported limit range is 1 to 100. Defaults to 10.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
string

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Create an invoice batch

Create a batch of ad-hoc invoices to bill one or more customers on an on-demand basis. Invoices created from this end point are not associated to any subscriptions.

 
posthttps://api-sandbox.ezypay.com/v2/billing/invoices/batches
{  
   "batchReference":"96025dfa-80e8-40aa-a8a4-4a4b71ad42e4",
   "invoices":[  
      {  
         "customerId":"929aca27-6097-4f43-bf5c-4733284b79e1",
         "paymentMethodToken":"064e08e8-e2bf-444e-8098-a527e0d16733",
         "externalInvoiceId":"1c6fd855-b665-4853-a23e-ee52d6efce52",
         "memo":"this is invoice #1",
         "items":[  
            {  
               "amount":{  
                  "currency":"NZD",
                  "value":20,
                  "type":null
               },
               "tax":{  
                  "rate":10
               },
               "description":"this is a test item",
               "accountingCode":"testinvoicecode",
               "type":null
            }
         ],
         "autoPayment":true
      },
      {  
         "customerId":"929aca27-6097-4f43-bf5c-4733284b79e1",
         "paymentMethodToken":"064e08e8-e2bf-444e-8098-a527e0d16733",
         "externalInvoiceId":"e8a3da86-8b3d-4332-a883-51785cedb605",
         "memo":"this is invoice #2",
         "items":[  
            {  
               "amount":{  
                  "currency":"NZD",
                  "value":20,
                  "type":null
               },
               "tax":{  
                  "rate":10
               },
               "description":"this is a test item",
               "accountingCode":"testinvoicecode",
               "type":null
            }
         ],
         "autoPayment":true
      },
      {  
         "customerId":"929aca27-6097-4f43-bf5c-4733284b79e1",
         "paymentMethodToken":"064e08e8-e2bf-444e-8098-a527e0d16733",
         "externalInvoiceId":"e3c1f5d5-9741-41d1-a287-2ec3cc3826ed",
         "memo":"this is invoice #3",
         "items":[  
            {  
               "amount":{  
                  "currency":"NZD",
                  "value":20,
                  "type":null
               },
               "tax":{  
                  "rate":10
               },
               "description":"this is a test item",
               "accountingCode":"testinvoicecode",
               "type":null
            }
         ],
         "autoPayment":true
      }
   ]
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"5c8e8f06-8d59-4957-8761-61b5fb85274b",
   "batchReference":"96025dfa-80e8-40aa-a8a4-4a4b71ad42e4",
   "createdOn":"2019-03-10T20:14:03.928",
   "status":"SUBMITTED"
}

Body Params

batchReference
string
required

The merchant reference for the invoice batch. This must be unique. It is recommended that this is alphanumeric only with the exception of hyphen (-) and underscore (_)

invoices
array of objects
required

Details of the individual invoices that are included in the batch.

Headers

merchant
string
required

Merchant ID

 

Retrieve an invoice batch

Get the full details of an invoice batch.

 
gethttps://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/invoices/batches/invoiceBatchId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "5c8e8f06-8d59-4957-8761-61b5fb85274b",
    "batchReference": "96025dfa-80e8-40aa-a8a4-4a4b71ad42e4",
    "createdOn": "2019-03-10T20:14:03.928",
    "status": "SUCCESS",
    "invoiceBatchItemList": {
        "data": [
            {
                "id": "67d6a27d-7783-450b-8848-bf033f62ac14",
                "externalInvoiceId": "355b5139-78f4-436e-b7f3-4b04ac7bafec",
                "invoiceId": "8928cd56-6331-405d-aef7-ff4ad2becea6",
                "status": "SUCCESS",
                "processingResult": "Invoice successfully created",
                "createdOn": "2019-03-10T20:14:04.000"
            },
            {
                "id": "1b924a47-8462-4304-ac1a-d6e95695644f",
                "externalInvoiceId": "e8f06728-c7e4-4d05-98ad-355af494402d",
                "invoiceId": "2429b23f-0ef6-463c-a196-c22f95cea1a3",
                "status": "SUCCESS",
                "processingResult": "Invoice successfully created",
                "createdOn": "2019-03-10T20:14:04.000"
            },
            {
                "id": "b5b81ce7-58cf-4cf7-8b0f-bc6f5fec769d",
                "externalInvoiceId": "44c9de44-eb5d-4e64-9868-23433165c8b6",
                "invoiceId": "b1b35539-35a4-4c2a-bd7b-793723bbcfd9",
                "status": "SUCCESS",
                "processingResult": "Invoice successfully created",
                "createdOn": "2019-03-10T20:14:04.000"
            },
            {
                "id": "297a2416-3f67-4e3f-9989-2032e7288e9b",
                "externalInvoiceId": "e8a3da86-8b3d-4332-a883-51785cedb605",
                "invoiceId": "d4ba0a72-75e7-4a0d-9450-1a822b909851",
                "status": "SUCCESS",
                "processingResult": "Invoice successfully created",
                "createdOn": "2019-03-10T20:14:04.000"
            },
            {
                "id": "dcdad21b-206f-4039-b2cd-b5f9bad25836",
                "externalInvoiceId": "72ff7159-9071-4673-a81f-e695bf263ba0",
                "invoiceId": "e997c54d-8fb5-4a53-9d97-96eb6c6ac594",
                "status": "SUCCESS",
                "processingResult": "Invoice successfully created",
                "createdOn": "2019-03-10T20:14:04.000"
            }
        ],
        "paging": {
            "nextUrl": null,
            "nextCursor": 0,
            "limit": 0,
            "totalCount": 5
        }
    }
}

Path Params

invoiceBatchId
string
required

Auto-generated identifier of the invoice batch.

Query Params

status
string

Filter by invoice batch item status. Supported values are PENDING, PROCESSING, SUCCESS, FAILED.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

Headers

merchant
string
required

Merchant ID

 

Merchants

 

Retrieve a merchant

Retrieve the business and address details of the respective merchant.

 
gethttps://api-sandbox.ezypay.com/v2/billing/merchant
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/merchant
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/merchant' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/merchant")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/merchant"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "c556d40f-87b5-49f9-90e8-07a610dac1a7",
    "number": "57899",
    "legalName": "high_st LegalNameNZ",
    "name": "high_st NameNZ",
    "address": null,
    "countryCode": "NZ",
    "email": "success+NZ+merchant+bf905c27-b03b-4529-a5d1-3beef14a03e3@simulator.amazonses.com",
    "phoneNumber": null,
    "billing": true,
    "settlement": true,
    "status": "ACTIVE",
    "businessRegistrationNumber": null,
    "taxId": null,
    "categoryCode": null,
    "website": null,
    "description": null,
    "referenceCode": null,
    "settlementSchedule": {
        "intervalUnit": "DAY",
        "interval": 1,
        "settlementDay": null,
        "nextSettlementDate": "2019-05-19",
        "intervalDayType": "calendar"
    },
    "settlementPayoutMethod": {
        "id": "c556d40f-87b5-49f9-90e8-07a610dac1a7",
        "paymentMethodToken": "cc0101ef-4bed-468a-8f0e-97449bba0edc",
        "bank": {
            "accountHolderName": "Automation Test NEW_ZEALAND",
            "last4": "0000",
            "bankNumber": "03",
            "branchNumber": "1587",
            "suffixNumber": "00"
        }
    },
    "acceptedPaymentMethods": [
        "BANK",
        "MASTERCARD",
        "VISA"
    ],
    "failedPaymentHandling": {
        "initialAction": "STOP",
        "autoRetry": true,
        "retryInDays": 3,
        "maximumFailedAttempts": 4
    },
    "paymentReactivationHandling": "activate_payments_across_customer",
    "tax": {
        "rate": 0
    },
    "notifications": {
        "customerEmail": {
            "subscriptionCreation": true,
            "paymentMethodCreation": true,
            "pastDueInvoice": true,
            "settlementReports": false
        }
    },
    "metadata": {
        "ezypay_internal_payment_simulator": "false"
    },
    "type": "business",
    "feePricingId": "a67eca1d-0c37-4fc9-b9c5-03b2dc8aefc7",
    "documentNumberSettings": [
        {
            "documentType": "invoice",
            "prefix": "IN"
        },
        {
            "documentType": "credit_note",
            "prefix": "CN"
        }
    ]
}
 

Update a merchant's failed payment handling

Update the settings that control automatic payment retry when a customer failed payment occurs.

 
puthttps://api-sandbox.ezypay.com/v2/billing/merchant/failedpaymenthandling
{
	"autoRetry": "true",
	"retryInDays": 2,
	"maximumFailedAttempts": 4
}
A binary file was returned

You couldn't be authenticated

{
    "id": "c556d40f-87b5-49f9-90e8-07a610dac1a7",
    "number": "57899",
    "legalName": "high_st LegalNameNZ",
    "name": "high_st NameNZ",
    "address": null,
    "countryCode": "NZ",
    "email": "success+NZ+merchant+bf905c27-b03b-4529-a5d1-3beef14a03e3@simulator.amazonses.com",
    "phoneNumber": null,
    "billing": true,
    "settlement": true,
    "status": "ACTIVE",
    "businessRegistrationNumber": null,
    "taxId": null,
    "categoryCode": null,
    "website": null,
    "description": null,
    "referenceCode": null,
    "settlementSchedule": {
        "intervalUnit": "DAY",
        "interval": 1,
        "settlementDay": null,
        "nextSettlementDate": "2019-05-19",
        "intervalDayType": "calendar"
    },
    "settlementPayoutMethod": {
        "id": "c556d40f-87b5-49f9-90e8-07a610dac1a7",
        "paymentMethodToken": "cc0101ef-4bed-468a-8f0e-97449bba0edc",
        "bank": {
            "accountHolderName": "Automation Test NEW_ZEALAND",
            "last4": "0000",
            "bankNumber": "03",
            "branchNumber": "1587",
            "suffixNumber": "00"
        }
    },
    "acceptedPaymentMethods": [
        "BANK",
        "MASTERCARD",
        "VISA"
    ],
    "failedPaymentHandling": {
        "initialAction": "CONTINUE",
        "autoRetry": true,
        "retryInDays": 2,
        "maximumFailedAttempts": 4
    },
    "paymentReactivationHandling": "activate_payments_across_customer",
    "tax": {
        "rate": 0
    },
    "notifications": {
        "customerEmail": {
            "subscriptionCreation": true,
            "paymentMethodCreation": true,
            "pastDueInvoice": true,
            "settlementReports": false
        }
    },
    "metadata": {
        "ezypay_internal_payment_simulator": "false"
    },
    "type": "business",
    "feePricingId": "a67eca1d-0c37-4fc9-b9c5-03b2dc8aefc7",
    "documentNumberSettings": [
        {
            "documentType": "invoice",
            "prefix": "IN"
        },
        {
            "documentType": "credit_note",
            "prefix": "CN"
        }
    ]
}

Body Params

initialAction
string

The initial action taken when a failed payment occurs. Supported values are: stop - Do not attempt any further payment processing for the failed invoice. continue - Continue to attempt payment recovery for the failed invoice.

autoRetry
boolean

Determines if automatic payment retry will occur on the failed invoice. Supported values are true and false.

retryInDays
int32

Specifies the number of days to wait before next retry for payment. Supported values are between 2 - 14. Default value is 7.

maximumFailedAttempts
int32

Specifies the maximum number of failed attempts allowed before stopping payment retries. Supported values are between 2 - 5. Default value is 2.

applyTo
string

Specifies the scope when updating the failed payment settings. Supported values are: merchant - Apply updated settings to all new plans and on-demand invoices created. Existing plans, subscriptions, and invoices are not affected.

Headers

merchant
string
required

Merchant ID

 

Retrieve collected next settlement amount

Retrieves the collected amount till date.

 
gethttps://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/merchant/nextSettlement/merchantId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "d88a4910-072e-4228-8e92-8e93dbbc6732",
    "number": "65698",
    "legalName": "mfe NameNZ",
    "name": "mfe EVAtest1",
    "settlementScheduleDTO": {
        "intervalUnit": "DAY",
        "interval": 1,
        "nextSettlementDate": "2019-05-18",
        "lastSettlementDate": "2019-05-17"
    },
    "amount": {
        "currency": "NZD",
        "value": 483.4,
        "type": "FIXED_AMOUNT"
    }
}

Path Params

merchantId
string
required

Merchant ID

Headers

merchant
string
required

Merchant ID

 

Update a merchant's notification settings

Update a merchant's notification settings.

 
puthttps://api-sandbox.ezypay.com/v2/billing/merchant/notificationsettings
{  
   "customerEmail":{  
      "subscriptionCreation":"true",
      "paymentMethodCreation":"true",
      "pastDueInvoice":"true",
      "settlementReports":"true"
   }
}
A binary file was returned

You couldn't be authenticated

{
    "customerEmail": {
        "subscriptionCreation": true,
        "paymentMethodCreation": true,
        "pastDueInvoice": true,
        "settlementReports": true
    }
}

Body Params

customerEmail
object

Customer email notification settings

customerEmail.pastDueInvoice
boolean

Flag to turn on notification for Past due invoice

customerEmail.paymentMethodCreation
boolean

Flag to turn on notification for Payment method creation

customerEmail.settlementReports
boolean

Flag to turn on notification for merchant settlement reports

customerEmail.subscriptionCreation
boolean

Flag to turn on notification for Subscription creation

Headers

merchant
string
required

Merchant ID

 

Retrieve a schedule of customer paid fees for Merchant

Retrieves a list of all customer allocated fees configured for the current merchant. Information returned by this service resource includes: the type of each fee, the payment method to which the fee applies, the accounting code associated with the fee, and the method used to calculate the fee amount (e.g. fixed amount, percentage, or both).

 
gethttps://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/merchant/pricing/fees"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "pricingCode": "failed_payment_fee",
            "description": "Failed Payment Fee",
            "appliesTo": [],
            "accountingCode": null,
            "chargingOption": "AMOUNT",
            "amount": 8.50,
            "percentage": 0.00
        },
        {
            "pricingCode": "transaction_fee",
            "description": "Card Fee",
            "appliesTo": [
                "MASTERCARD",
                "VISA"
            ],
            "accountingCode": null,
            "chargingOption": "BOTH",
            "amount": 0.50,
            "percentage": 0.37
        },
        {
            "pricingCode": "transaction_fee",
            "description": "Bank Fee",
            "appliesTo": [
                "BANK"
            ],
            "accountingCode": null,
            "chargingOption": "BOTH",
            "amount": 0.35,
            "percentage": 0.15
        },
        {
            "pricingCode": "load_fee",
            "description": "Load Fee",
            "appliesTo": [],
            "accountingCode": null,
            "chargingOption": "AMOUNT",
            "amount": 2.00,
            "percentage": 0.00
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 4,
        "totalCount": 4
    }
}

Headers

merchant
string
required

Merchant ID

 

Merchant Connections

 

List merchant connections

Retrieve a list of merchant connections that belong to the merchant.

 
gethttps://api-sandbox.ezypay.com/v2/merchantconnections
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/merchantconnections \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/merchantconnections',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/merchantconnections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/merchantconnections");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/merchantconnections"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Query Params

status
string

Filter by the status of the merchant connection. Supported values are: pending - The merchant connection is still pending acceptance. active - The merchant connection has been accepted and is active. cancelled - The merchant connection has been cancelled.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Retrieve a merchant connection

Get the full details of a merchant connection.

 
gethttps://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/merchantconnections/merchantConnectionId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

merchantConnectionId
string
required

Auto-generated unique identifier of the merchant connection.

Headers

merchant
string
required

Merchant ID

 

Merchant Contact

 

Create merchant's contact by type

Create merchant's contact by type

 
posthttps://api-sandbox.ezypay.com/v2/merchantcontact
{
"type":"EMAIL",
"merchantId":"1aefbba9-263a-484f-8ba1-1b074b8c1493"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "type": "EMAIL",
    "merchantId": "1aefbba9-263a-484f-8ba1-1b074b8c1493",
    "createdBy": "test.test@ezypay.com"
}

Body Params

type
string

Type of contact to be created for mechant. Supported values are EMAIL, ADDRESS.

merchantId
string

Merchant ID

Headers

merchant
string
required

Merchant ID

 

.

Get merchant contact by merchant contact id

Returns the merchant's contact by its ID

 
gethttps://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "type": "EMAIL",
    "merchantId": "c556d40f-87b5-49f9-90e8-07a610dac1a7",
    "createdBy": "test.test@ezypay.com"
}

Path Params

merchantContactId
string
required

Merchant Contact ID

Headers

merchant
string
required

Merchant ID

 

.

Update merchant contact by merchant contact Id

Create merchant's contact by type

 
puthttps://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId
{
"type":"EMAIL",
"merchantId":"1aefbba9-263a-484f-8ba1-1b074b8c1493"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "67863a3a-0333-4b87-ba3b-af1b0d26d405",
    "type": "EMAIL",
    "merchantId": "1aefbba9-263a-484f-8ba1-1b074b8c1493",
    "createdBy": "test.test@ezypay.com"
}

Path Params

merchantContactId
string
required

Merchant Contact ID

Body Params

type
string

Type of contact to be created for mechant. Supported values are EMAIL, ADDRESS.

merchantId
string

Merchant ID

Headers

merchant
string
required

Merchant ID

 

.

Delete merchant contact by merchant contact id

Returns the merchant's contact by its ID

 
deletehttps://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId
curl --request DELETE \
  --url https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'DELETE',
  url:
   'https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/merchantcontact/merchantContactId"

headers = {'merchant': 'merchant'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

merchantContactId
string
required

Merchant Contact ID

Headers

merchant
string
required

Merchant ID

 

.

Plans

 

List plans

Get a list of plans.

 
gethttps://api-sandbox.ezypay.com/v2/billing/plans
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/plans \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/plans',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/plans")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/plans");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/plans"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
            "status": "ACTIVE",
            "name": "high_st_monthly_plan",
            "memo": null,
            "accountingCode": "customer_plan",
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "setupPayments": null,
            "intervalUnit": "MONTH",
            "interval": 1,
            "billingStart": "DAY_OF_MONTH",
            "billingStartValue": "1",
            "billingEnd": "ONGOING",
            "billingEndValue": null,
            "firstBilling": "FULL_AMOUNT",
            "recurringBillingDay": null,
            "failedPaymentHandling": {
                "initialAction": "STOP",
                "autoRetry": true,
                "retryInDays": 3,
                "maximumFailedAttempts": 4
            },
            "metadata": null,
            "createdOn": "2019-04-01T12:55:04.245"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Query Params

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

name
string

Filter list of returned plans by name. Partial world search supported. For example, when name=mem, all plans with "mem" as part of the name will be returned.

status
string

Filter list of returned plans by status. Supported values are active or inactive.

Headers

merchant
string
required

Merchant ID

 

Create a plan

Plans can be easily created in the Plans section of the Merchant Site, or by using this API to have plans created on the fly.

 
posthttps://api-sandbox.ezypay.com/v2/billing/plans
{  
   "setupPayments":null,
   "interval":"1",
   "name":"high_st_monthly_plan",
   "firstBilling":null,
   "failedPaymentSetting":null,
   "memo":null,
   "tax":null,
   "intervalUnit":"month",
   "recurringBillingDay":null,
   "billingStartValue":"1",
   "amount":{  
      "currency":"NZD",
      "value":"200",
      "type":null
   },
   "billingStart":"day_of_month",
   "billingEndValue":null,
   "taxExempted":null,
   "billingEnd":null,
   "accountingCode":"customer_plan",
   "incomeType":null
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"8ff2e3ea-aaa9-4978-8e2a-319d67e8f302",
   "status":"ACTIVE",
   "name":"high_st_monthly_plan",
   "memo":null,
   "accountingCode":"customer_plan",
   "amount":{  
      "currency":"NZD",
      "value":200.00,
      "type":null
   },
   "tax":{  
      "rate":0.00
   },
   "setupPayments":null,
   "intervalUnit":"MONTH",
   "interval":1,
   "billingStart":"DAY_OF_MONTH",
   "billingStartValue":"1",
   "billingEnd":"ONGOING",
   "billingEndValue":null,
   "firstBilling":"FULL_AMOUNT",
   "recurringBillingDay":null,
   "failedPaymentHandling":{  
      "initialAction":"STOP",
      "autoRetry":true,
      "retryInDays":3,
      "maximumFailedAttempts":4
   },
   "metadata":null,
   "createdOn":"2019-03-11T09:10:53.771"
}

Body Params

name
string
required

Plan name. Max of 50 characters.

memo
string

Brief memo of the plan. Max of 50 characters.

accountingCode
string

Specify an accounting code to categorise revenue collected from the plan's subscription payment. Max of 50 characters.

amount
object

The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.

amount.currency
string
required

Three letter ISO 4217 currency code for the amount.

amount.value
double
required

The value of the amount. Must be positive value greater than zero.

amount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

tax
object

The tax rate applied to the plan's amount. If left blank, uses the tax rate specified in the merchant settings by default.

tax.rate
double

Rate of the specified tax in percentage. Supported values are from 0 to 99.99.

setupPayments
array of objects

Setup payment settings.

intervalUnit
string

Specifies frequency of billing. Valid values are day, week or month. If no value is provided, the default value is week.

interval
int32

Number to be specified as interval to manipulate billing frequency. For example interval=2 and intervalUnit=week would means billing every 2 weeks. If no value is provided, the default value is 1.

billingStart
string

Specifies the default day the billing schedule starts for customers subscribed to the plan. Supported values are: immediate - Default value. Subscriptions will start on the same day. day_of_week - Subscriptions will start on a specific day as defined in billingStartValue. day_of_month - Subscriptions will start on specific day in the month as defined in billingStartValue.

billingEnd
string

Specifies the rules to automate when a subscription ends. Supported values are: ongoing - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). amount_collected - Subscriptions will end when a specified amount is collected as defined in billingEndValue. billing_cycles - Subscriptions will end after a specified number of billing cycles as defined in billingEndValue. end_date - Subscriptions will end on specific date. Specify this date when you create a subscription in billingEndValue.

firstBilling
string

Specifies the rules to auto-calculate the billing charges for the first scheduled billing. Supported values are: full_amount - Default value. The first billing will charge the full amount on the subscription as defined in the plan's amount. prorate - Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.

metadata
object

Store additional data about the customer object using key/value pairs format.

Headers

merchant
string
required

Merchant ID

 

Retrieve a plan

Gets the full details of a plan.

 
gethttps://api-sandbox.ezypay.com/v2/billing/plans/planId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/plans/planId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/plans/planId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/plans/planId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/plans/planId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/plans/planId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "id":"d35f6384-e5af-4eaf-b4c9-d08511a21921",
   "status":"ACTIVE",
   "name":"high_st_monthly_plan",
   "memo":null,
   "accountingCode":"customer_plan",
   "amount":{  
      "currency":"NZD",
      "value":200,
      "type":null
   },
   "tax":{  
      "rate":0
   },
   "setupPayments":null,
   "intervalUnit":"MONTH",
   "interval":1,
   "billingStart":"DAY_OF_MONTH",
   "billingStartValue":"1",
   "billingEnd":"ONGOING",
   "billingEndValue":null,
   "firstBilling":"FULL_AMOUNT",
   "recurringBillingDay":null,
   "failedPaymentHandling":{  
      "initialAction":"STOP",
      "autoRetry":true,
      "retryInDays":3,
      "maximumFailedAttempts":4
   },
   "metadata":null,
   "createdOn":"2019-04-01T12:55:04.245"
}
    

Path Params

planId
string
required

Identifier of the plan to retrieve.

Headers

merchant
string
required

Merchant ID

 

Update a plan

Update details of a plan. Changes will be effective for subscriptions created after the update. Existing subscriptions will not be affected and remain grandfathered at terms agreed previously when subscribing to the plan.

 
puthttps://api-sandbox.ezypay.com/v2/billing/plans/planId
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/billing/plans/planId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/plans/planId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/plans/planId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/billing/plans/planId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/plans/planId"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "id":"d35f6384-e5af-4eaf-b4c9-d08511a21921",
   "status":"ACTIVE",
   "name":"high_st_monthly_plan",
   "memo":null,
   "accountingCode":"customer_plan",
   "amount":{  
      "currency":"NZD",
      "value":200,
      "type":null
   },
   "tax":{  
      "rate":0
   },
   "setupPayments":null,
   "intervalUnit":"MONTH",
   "interval":1,
   "billingStart":"DAY_OF_MONTH",
   "billingStartValue":"1",
   "billingEnd":"ONGOING",
   "billingEndValue":null,
   "firstBilling":"FULL_AMOUNT",
   "recurringBillingDay":null,
   "failedPaymentHandling":{  
      "initialAction":"STOP",
      "autoRetry":true,
      "retryInDays":3,
      "maximumFailedAttempts":4
   },
   "metadata":null,
   "createdOn":"2019-04-01T12:55:04.245"
}

Path Params

planId
string
required

Identifier of the plan to update.

Body Params

name
string

Plan name. Max of 50 characters.

memo
string

Brief memo of the plan. Max of 50 characters.

amount
object

The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.

amount.currency
string
required

Three letter ISO 4217 currency code for the amount.

amount.value
double
required

The value of the amount. Must be positive value greater than zero.

amount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

status
string

Current state of the plan. Supported values are: active - Customers can subscribe to the plan. inactive - Customers are unable to subscribe to the plan.

setupPayments
object

Setup payment settings.

setupPayments.amount
object

Setup payment amount.

setupPayments.tax
object

The tax that is applicable to the setup payment, if the amount is taxable.

setupPayments.description
string

Description. Max of 255 characters.

setupPayments.accountingCode
string

Specify an accounting code to categorise revenue collected from the setup payment. Max of 50 characters.

intervalUnit
string

Specifies frequency of billing. Can be day, week or month. If no value is provided, the default value is week.

tax
object

The tax rate that will be applied to the plan's amount. If left blank, uses the tax rate specified in the Merchant Object by default.

tax.rate
double

Rate of the specified tax in percentage. Supported values are from 0 to 99.99.

interval
int32

Number to be specified as interval to manipulate billing frequency. For example interval=2 and intervalUnit=week would means billing every 2 weeks. If no value is provided, the default value is 1.

billingStart
string

Specify the rules to auto-calculate default billing start dates for customers subscribed to the plan. Supported values are weekday, day_of_month, and subscription_date. Must be specified with a corresponding billingStartValue. The default value is subscription_date. This means, by default, schedules created from this plan will start on the start date defined in the customer’s subscription. However, if the scheduled start date and today’s date are the same, then the subscription is marked as starting today but schedules are generated the next day.

billingEnd
string

Specifies the rules to automate when a subscription ends. Supported values are: ongoing - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). amount_collected - Subscriptions will end when a specified amount is collected as defined in billingEndValue. billing_cycles - Subscriptions will end after a specified number of billing cycles as defined in billingEndValue. end_date - Subscriptions will end on specific date. Specify this date when you create a subscription in billingEndValue

firstBilling
string

Specifies the rules to auto-calculate the billing charges for the first scheduled billing. Supported values are: If full_amount = Default value. The first billing will charge the full amount on the subscription as defined in the plan's amount. If prorate = Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.

accountingCode
string

Specify an accounting code to categorise revenue collected from the plan's subscription payment. Max of 50 characters.

Headers

merchant
string
required

Merchant ID

 

Partner Invoices

 

List partner invoices

Retrieve a list of partner invoices that occurred between two merchants.

 
gethttps://api-sandbox.ezypay.com/v2/partnerinvoices
curl --request GET \
  --url 'https://api-sandbox.ezypay.com/v2/partnerinvoices?issuerMerchantId=issuerMerchantId&recipientMerchantId=recipientMerchantId'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/partnerinvoices',
  qs:
   { issuerMerchantId: 'issuerMerchantId',
     recipientMerchantId: 'recipientMerchantId' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnerinvoices?issuerMerchantId=issuerMerchantId&recipientMerchantId=recipientMerchantId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/partnerinvoices?issuerMerchantId=issuerMerchantId&recipientMerchantId=recipientMerchantId");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnerinvoices"

querystring = {"issuerMerchantId":"issuerMerchantId","recipientMerchantId":"recipientMerchantId"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "data":[  
      {  
         "id":"a1c3f193-678f-4068-9411-5d0af0a29853",
         "documentNumber":"IN0000000000000001",
         "date":"2019-04-04",
         "dueDate":"2019-04-04",
         "status":"PAID",
         "memo":null,
         "items":[  
            {  
               "description":"PNB_IBJL_Equipment_Leasing",
               "amount":{  
                  "currency":"NZD",
                  "value":20074.25,
                  "type":null
               },
               "tax":{  
                  "rate":0.00
               },
               "id":"d0c8f41c-4c3e-48f7-a0d6-d5914dfb05a2",
               "type":"partner_subscription",
               "accountingCode":"EquipmentLeasing",
               "additionalDetail":null
            }
         ],
         "amount":{  
            "currency":"NZD",
            "value":20074.25,
            "type":null
         },
         "totalTax":{  
            "currency":"NZD",
            "value":0.00,
            "type":null
         },
         "issuerMerchant":{  
            "id":"eab7bfc6-113a-4e51-aedd-f6a807420656",
            "name":"pnb_ibjl NameNZ",
            "legalName":"pnb_ibjl LegalNameNZ"
         },
         "recipientMerchant":{  
            "id":"c74437ba-e204-46fc-9b16-0062f896e01e",
            "name":"high_st NameNZ",
            "legalName":"high_st LegalNameNZ"
         },
         "createdOn":"2019-03-10T20:23:35.160",
         "countryCode":"NZ",
         "partnerSubscriptionId":"315107b6-e341-45c6-ad47-8d0bce9e0b25"
      }
   ],
   "paging":{  
      "nextUrl":null,
      "nextCursor":0,
      "limit":0,
      "totalCount":1
   }
}

Query Params

issuerMerchantId
string
required

Auto-generated identifier of the merchant who issued the partner invoice.

recipientMerchantId
string
required

Auto-generated identifier of the merchant who received the partner invoice.

status
string

Filter by the status of the partner invoice. Supported values are: paid - Payment transaction for invoice completed successfully. past_due - Payment transaction for invoice failed or was unsuccessful.

from
date

Start date for range of partner invoices to view. Filter by date defined in the invoice date. Supported format is YYYY-MM-DD.

until
date

End date for range of partner invoices to view. Filter by date defined in the invoice date. Supported format is YYYY-MM-DD.

countryCode
string

Filter by two letter ISO 3166-1 alpha-2 country code of the issuing merchant.

partnerSubscriptionId
string

Auto-generated identifier of the partner subscription associated to the invoice.

limit
string

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
string

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

 

Create a partner invoice

A partner invoice is issued by a partner merchant to collect payment from another merchant.Partner invoices provide a full breakdown of the individual invoice items in detail.Invoices can be automatically generated from partner subscriptions at each billing cycle or issued as an ad-hoc, on-demand invoice. Before creating a partner invoice, you must have a merchant connection with the merchant that will receive the partner invoice.

 
posthttps://api-sandbox.ezypay.com/v2/partnerinvoices
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/partnerinvoices
var request = require("request");

var options = { method: 'POST',
  url: 'https://api-sandbox.ezypay.com/v2/partnerinvoices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnerinvoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/partnerinvoices");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnerinvoices"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

issuerMerchantId
string
required

Auto-generated identifier of the merchant who will issue the partner invoice.

recipientMerchantId
string
required

Auto-generated identifier of the merchant will receive the partner invoice and make payment.

memo
string

Brief description of the partner invoice. Max of 100 characters.

items
array of objects
required

Details of the individual items that are included in the invoice

 

Attempt payment on a partner invoice

Manually attempt to collect payment for a past due partner invoice

 
posthttps://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

partnerInvoiceId
string
required

Auto-generated identifier of the partner invoice id

Headers

merchant
string
required

Merchant ID

 

Partner Subscriptions

 

List partner subscriptions

Retrieve a list of partner subscriptions using the available filter options.

 
gethttps://api-sandbox.ezypay.com/v2/partnersubscriptions
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/partnersubscriptions \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/partnersubscriptions',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnersubscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/partnersubscriptions");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnersubscriptions"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "315107b6-e341-45c6-ad47-8d0bce9e0b25",
            "partnerPlanId": "26b4bb23-e6cd-401b-8014-5b20093ac7ee",
            "issuer": {
                "id": "eab7bfc6-113a-4e51-aedd-f6a807420656",
                "name": "pnb_ibjl NameNZ",
                "legalName": "pnb_ibjl LegalNameNZ"
            },
            "recipient": {
                "id": "c74437ba-e204-46fc-9b16-0062f896e01e",
                "name": "high_st NameNZ",
                "legalName": "high_st LegalNameNZ"
            },
            "name": "PNB_IBJL_Equipment_Leasing",
            "status": "ACTIVE",
            "amount": {
                "currency": "NZD",
                "value": 10,
                "type": "PERCENTAGE"
            },
            "tax": {
                "rate": 0
            },
            "accountingCode": "EquipmentLeasing",
            "intervalUnit": "MONTH",
            "interval": 1,
            "intervalDayType": "business",
            "endType": "ONGOING",
            "startDate": "2019-04-04",
            "endDate": null,
            "nextBillingDate": "2019-06-06",
            "merchantConnectionId": "dae89c35-246c-4551-83b6-addd94853afb",
            "endTargetBillingCycles": 0,
            "totalBillingCycles": 0,
            "remainingBillingCycles": 0,
            "createdOn": "2019-03-11T07:23:33.851",
            "cancellationDate": null,
            "setupPayments": null
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Query Params

recipientId
string

Auto-generated unique identifier of the merchant that will subscribe and make payments to the subscription.

status
string

The status of the partner subscription. Supported values are: active - Merchants can subscribe to the plan. Default value. inactive - Merchants are unable to subscribe to the plan

name
string

The name of the partner plan that was subscribed.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Create a partner subscription

Partner subscriptions provides the means for partner merchants to collect payments from another merchant on a recurring basis. Before creating a partner subscription, you must have a merchant connection with the merchant that will subscribe to the partner subscription.

 
posthttps://api-sandbox.ezypay.com/v2/partnersubscriptions
{  
   "partnerPlanId":"26b4bb23-e6cd-401b-8014-5b20093ac7ee",
   "recipientId":"c74437ba-e204-46fc-9b16-0062f896e01e",
   "startDate":null,
   "metadata":null
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"315107b6-e341-45c6-ad47-8d0bce9e0b25",
   "partnerPlanId":"26b4bb23-e6cd-401b-8014-5b20093ac7ee",
   "issuer":{  
      "id":"eab7bfc6-113a-4e51-aedd-f6a807420656",
      "name":"pnb_ibjl NameNZ",
      "legalName":"pnb_ibjl LegalNameNZ"
   },
   "recipient":{  
      "id":"c74437ba-e204-46fc-9b16-0062f896e01e",
      "name":"high_st NameNZ",
      "legalName":"high_st LegalNameNZ"
   },
   "name":"PNB_IBJL_Equipment_Leasing",
   "status":"FUTURE",
   "amount":{  
      "currency":"NZD",
      "value":10.00,
      "type":"PERCENTAGE"
   },
   "tax":{  
      "rate":0.00
   },
   "accountingCode":"EquipmentLeasing",
   "intervalUnit":"MONTH",
   "interval":1,
   "intervalDayType":"business",
   "endType":"ONGOING",
   "startDate":"2019-04-04",
   "endDate":null,
   "nextBillingDate":"2019-04-04",
   "merchantConnectionId":"dae89c35-246c-4551-83b6-addd94853afb",
   "endTargetBillingCycles":0,
   "totalBillingCycles":0,
   "remainingBillingCycles":0,
   "createdOn":"2019-03-10T20:23:33.838",
   "cancellationDate":null,
   "setupPayments":null
}

Body Params

partnerPlanId
string
required

Auto-generated unique identifier of the partner plan.

recipientId
string
required

Auto-generated unique identifier of the merchant that will subscribe and make payments to the subscription.

startDate
string

The preferred start date of the partner subscription. The partner subscription start date cannot be back-dated. The default value follows the partner plan's start date. Supported format is YYYY-MM-DD.

metadata
object

Store additional data about the partner subscription object using key/value pairs format. Max of 40 characters for key name and 255 characters for key value.

Headers

merchant
string
required

Merchant ID

 

List partner subscription add on usage

Retrieve a list of partner subscription add on usages and filter the results using the available options.

 
gethttps://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

partnerSubscriptionId
string
required

Auto-generated unique identifier of the partner subscription.

partnerSubscriptionAddOnCode
string
required

Existing partner subscription add on code associated to the partner subscription.

Query Params

referenceCode
string

Specify the custom, external ID used to identify this usage entry for an external system.

recordingTimestampFrom
string

Specify the start for range of objects to view based on date defined in recordingTimestamp. Supported format is yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS.

recordingTimestampUntil
string

Specify the end for range of object to view based on date defined in recordingTimestamp. Supported format is yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS.

createdFrom
string

Specify the start for range of object to view based on auto-generated date in createdOn. Supported format is yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS.

createdUntil
string

Specify the end for range of object to view based on auto-generated date in createdOn. Supported format is yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Record a partner subscription add on usage

Record the active member count for each partner subscription to bill a merchant according to member usage.

 
posthttps://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/addons/partnerSubscriptionAddOnCode/recordusage"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

partnerSubscriptionId
string
required

Auto-generated unique identifier of the partner subscription.

partnerSubscriptionAddOnCode
string
required

Existing partner subscription add on code associated to the partner subscription. Partner subscription add on type must be set to amount_per_usage.

Body Params

value
string
required

Specify a positive integer inclusive of 0.

displayMeasurementUnit
string

Specify a unit of measurement to describe the value. Max of 100 characters.

referenceCode
string

Specify the custom, external ID used to identify this usage entry for an external system.

recordingTimestamp
string

Specify the start for range of objects to view based on date defined in recordingTimestamp. Supported format is yyyy-MM-ddTHH:mm:ss or yyyy-MM-ddTHH:mm:ss.SSS.

Headers

merchant
string
required

Merchant ID

 

Cancel a partner subscription

Cancel an existing partner subscription.

 
puthttps://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/partnersubscriptions/partnerSubscriptionId/cancel"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "315107b6-e341-45c6-ad47-8d0bce9e0b25",
    "partnerPlanId": "26b4bb23-e6cd-401b-8014-5b20093ac7ee",
    "issuer": {
        "id": "eab7bfc6-113a-4e51-aedd-f6a807420656",
        "name": "pnb_ibjl NameNZ",
        "legalName": "pnb_ibjl LegalNameNZ"
    },
    "recipient": {
        "id": "c74437ba-e204-46fc-9b16-0062f896e01e",
        "name": "high_st NameNZ",
        "legalName": "high_st LegalNameNZ"
    },
    "name": "PNB_IBJL_Equipment_Leasing",
    "status": "CANCELLED",
    "amount": {
        "currency": "NZD",
        "value": 10,
        "type": "PERCENTAGE"
    },
    "tax": {
        "rate": 0
    },
    "accountingCode": "EquipmentLeasing",
    "intervalUnit": "MONTH",
    "interval": 1,
    "intervalDayType": "business",
    "endType": "ONGOING",
    "startDate": "2019-04-04",
    "endDate": null,
    "nextBillingDate": null,
    "merchantConnectionId": "dae89c35-246c-4551-83b6-addd94853afb",
    "endTargetBillingCycles": 0,
    "totalBillingCycles": 0,
    "remainingBillingCycles": 0,
    "createdOn": "2019-03-11T07:23:33.851",
    "cancellationDate": "2019-07-01",
    "setupPayments": null
}

Path Params

partnerSubscriptionId
string
required

Auto-generated unique identifier of the partner subscription.

Headers

merchant
string
required

Merchant ID

 

Reports

 

Generate Outstanding Collections Report

Generate Outstanding Collections Report

 
posthttps://api-sandbox.ezypay.com/v2/billing/reports/outstandingcollectionsreport
{
  "reportFormat": "CSV",
  "daysOutstanding": "THIRTY",
  "sortField": "EZYPAY_NUMBER",
  "reportFilters": [
    "FAILED_WITHOUT_FURTHER_RETRY"
  ]
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

reportFormat
string

Allows the report to be generated in either the .CSV format or the .PDF format. By default, it is PDF.

daysOutstanding
string

Number of days outstanding, Supported values are ALL, THIRTY, SIXTY, NINETY. By default, it is THIRTY.

reportFilters
array of strings
required

Results will be filtered by this field. Supported values are FAILED_WITHOUT_FURTHER_RETRY, FAILED_BUT_WILL_ATTEMPT_RETRY, DUE_BUT_NOT_ATTEMPTED_YET, NOT_YET_DUE.

sortField
string
required

Results will be sorted by this field. Supported values are CUSTOMER_NAME, CUSTOMER_NUMBER, EZYPAY_NUMBER, TOTAL_OUTSTANDING_AMOUNT.

Headers

merchant
string
required

Merchant ID

 

Generate Merchant Transactions Report

API is used to retrieve list of transactions in a csv file which are issued by a merchant in a given time range.

 
posthttps://api-sandbox.ezypay.com/v2/billing/reports/merchanttransactions
{
  "from" : "2019-10-29",
	"to": "2019-11-29"
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

from
string
required

Transactions which are created on or after this date will be included in the report. Format of the date: yyyy-MM-dd

to
string
required

Transactions which are created on or before this date will be included in reports. Format of the date: yyyy-MM-dd

Headers

merchant
string
required

Merchant ID

 

Settlements

 

List settlements

Retrieve a list of settlements and filter the results using the available options.

 
gethttps://api-sandbox.ezypay.com/v2/billing/settlements
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/settlements
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/settlements' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/settlements")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/settlements");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/settlements"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "number": "140637",
            "date": "2019-09-19",
            "revenue": {
                "currency": "AUD",
                "value": 212.24,
                "type": null
            },
            "deduction": {
                "currency": "AUD",
                "value": 115.11,
                "type": null
            },
            "amount": {
                "currency": "AUD",
                "value": 97.13,
                "type": null
            },
            "settlementPayoutMethod": {
                "id": null,
                "paymentMethodToken": "f36b0f16-d7c4-4937-9886-34f828596a3b",
                "bank": {
                    "accountHolderName": "Automation Test AUSTRALIA",
                    "last4": "6789",
                    "bankNumber": "402052",
                    "branchNumber": null,
                    "suffixNumber": null
                }
            },
            "status": "success",
            "failedSettlementReason": null,
            "createdOn": "2019-09-19T07:34:50.310"
        },
        {
            "number": "140443",
            "date": "2019-09-18",
            "revenue": {
                "currency": "AUD",
                "value": 406.48,
                "type": null
            },
            "deduction": {
                "currency": "AUD",
                "value": 206.48,
                "type": null
            },
            "amount": {
                "currency": "AUD",
                "value": 200.00,
                "type": null
            },
            "settlementPayoutMethod": {
                "id": null,
                "paymentMethodToken": "f36b0f16-d7c4-4937-9886-34f828596a3b",
                "bank": {
                    "accountHolderName": "Automation Test AUSTRALIA",
                    "last4": "6789",
                    "bankNumber": "402052",
                    "branchNumber": null,
                    "suffixNumber": null
                }
            },
            "status": "success",
            "failedSettlementReason": null,
            "createdOn": "2019-09-17T23:53:12.579"
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 2
    }
}

Query Params

from
string

Start date for range of settlements to view. Filter by settlement run date defined in settlementDate.

until
string

End date for range of settlements to view. Filter by settlement run date defined in settlementDate.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
string

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Body Params

merchant
string
required

Merchant ID

 

Generate a settlement document

Generate a document report on your settlement. Returns a file ID for the specified document type. Provide this ID to the file download service API, which will return a URL to download the report. Please append the header called Accepted-Language, the locale values currently supported are en and zh_TW.

 
posthttps://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/settlements/settlementNumber/file"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

settlementNumber
string
required

Auto-generated settlement run batch number

Body Params

sendEmail
boolean

Set sendEmail to true if you want to receive an automated email with this report attached to it.

locale
object

Locale of the report

documentType
string

The type of document generated from the settlement. Supported values are: tax_invoice: Generates a settlement tax invoice PDF. credit_note: Generates credit note PDF. detail_report: Generates a full report (in .csv format) on the settlement status of payment collections from customers.

merchantId
string

Merchant ID

Headers

merchant
string
required

Merchant ID

 

Subscriptions

 

List subscriptions

List all subscriptions that belongs to a customer.

 
gethttps://api-sandbox.ezypay.com/v2/billing/subscriptions
curl --request GET \
  --url 'https://api-sandbox.ezypay.com/v2/billing/subscriptions?customerId=customerId' \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/subscriptions',
  qs: { customerId: 'customerId' },
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/subscriptions?customerId=customerId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/subscriptions?customerId=customerId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/subscriptions"

querystring = {"customerId":"customerId"}

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
            "name": "high_st_monthly_plan",
            "status": "ACTIVE",
            "startDate": "2019-04-01",
            "endDate": null,
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
            "accountingCode": "customer_plan",
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "nextBillingDate": "2019-06-01",
            "nextFutureInvoice": null,
            "interval": 1,
            "intervalUnit": "MONTH",
            "totalPaid": {
                "currency": "NZD",
                "value": 400,
                "type": null
            },
            "totalBillingCycles": 2,
            "remainingToPay": null,
            "remainingBillingCycles": null,
            "endTargetAmount": null,
            "endTargetBillingCycles": null,
            "cancelledDate": null,
            "failedPaymentHandling": null,
            "failedAttemptsCount": 0,
            "totalPastDue": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "totalDiscounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "metadata": null,
            "createdOn": "2019-03-31T23:55:11.708",
            "autoPayment": true,
            "setupPayments": null
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Query Params

customerId
string
required

Auto-generated identifier of the customer.

limit
int32

To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, limit = 10 shows results 1-10. The default returned result would be 100.

cursor
int32

An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.

Headers

merchant
string
required

Merchant ID

 

Create a subscription

Creates a new subscription for a customer. By default, Subscriptions will inherit values from the Plan template. Specify new values in the Subscription to override values inherited from the Plan.

 
posthttps://api-sandbox.ezypay.com/v2/billing/subscriptions
{  
   "customerId":"55220ffc-bc5a-4f50-adaf-fa58c061ebd1",
   "planId":"8ff2e3ea-aaa9-4978-8e2a-319d67e8f302",
   "paymentMethodToken":"8dbf38bf-81c6-40d6-be1f-6aa80736d5bb",
   "accountingCode":null,
   "billingEndValue":null,
   "startDate":"2019-03-11"
}
A binary file was returned

You couldn't be authenticated

{  
   "id":"f1de945f-df84-4108-9dee-e8fd8508fa2e",
   "customerId":"55220ffc-bc5a-4f50-adaf-fa58c061ebd1",
   "planId":"8ff2e3ea-aaa9-4978-8e2a-319d67e8f302",
   "name":"high_st_monthly_plan",
   "status":"ACTIVE",
   "startDate":"2019-03-11",
   "endDate":null,
   "paymentMethodToken":"8dbf38bf-81c6-40d6-be1f-6aa80736d5bb",
   "accountingCode":"customer_plan",
   "amount":{  
      "currency":"NZD",
      "value":200.00,
      "type":null
   },
   "tax":{  
      "rate":0.00
   },
   "nextBillingDate":"2019-05-01",
   "nextFutureInvoice":{  
      "subscriptionId":"f1de945f-df84-4108-9dee-e8fd8508fa2e",
      "date":"2019-05-01",
      "cycleStartDate":"2019-05-01",
      "cycleEndDate":"2019-05-31",
      "items":[  
         {  
            "description":"high_st_monthly_plan",
            "amount":{  
               "currency":"NZD",
               "value":200.00,
               "type":null
            },
            "tax":{  
               "rate":0.00
            },
            "type":"subscription_payment",
            "accountingCode":"customer_plan"
         },
         {  
            "description":"Standard Master/Visa Fee",
            "amount":{  
               "currency":"NZD",
               "value":1.24,
               "type":null
            },
            "tax":{  
               "rate":0.10
            },
            "type":"transaction_fee",
            "accountingCode":null
         }
      ],
      "amount":{  
         "currency":"NZD",
         "value":201.24,
         "type":null
      },
      "totalTax":{  
         "currency":"NZD",
         "value":0.00,
         "type":null
      }
   },
   "interval":1,
   "intervalUnit":"MONTH",
   "totalPaid":{  
      "currency":"NZD",
      "value":200.00,
      "type":null
   },
   "totalBillingCycles":1,
   "remainingToPay":null,
   "remainingBillingCycles":null,
   "endTargetAmount":null,
   "endTargetBillingCycles":null,
   "cancelledDate":null,
   "failedPaymentHandling":null,
   "failedAttemptsCount":0,
   "totalPastDue":{  
      "currency":"NZD",
      "value":0.00,
      "type":null
   },
   "totalDiscounted":{  
      "currency":"NZD",
      "value":0.00,
      "type":null
   },
   "metadata":null,
   "createdOn":"2019-03-10T20:11:08.192",
   "autoPayment":true,
   "setupPayments":null
}

Body Params

customerId
string
required

Auto-generated identifier of the customer.

planId
string
required

Auto-generated identifier of the plan.

paymentMethodToken
string

The payment method token generated by the vault.

markAsPending
boolean

Default value is false. If set to true, creates a subscription with a Pending status. A pending subscription will ignore the subscription's startDate and no schedules will be created. The status can be changed to Active using the Activate a subscription API.

startDate
string

The preferred start date of the subscription. The subscription start date cannot be back-dated. The default value follows the plan's start date. Supported format is YYYY-MM-DD.

name
string

The name of the plan to subscribe the customer to. Max of 50 characters.

accountingCode
string

Specify an accounting code to categorise revenue collected from the subscription's payment. Max of 50 characters.

amount
object

The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.

amount.currency
string
required

Three letter ISO 4217 currency code for the amount.

amount.value
double
required

The value of the amount. Must be positive value greater than zero.

amount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

tax
object

If provided, each invoice generated for this subscription will include a tax rate.

tax.rate
double

Rate of the specified tax in percentage. Supported values are from 0 to 99.99.

setupPayments
object

One-time setup payment applied to the subscription.

setupPayments.amount
object

Setup payment amount.

setupPayments.tax
object

The tax that is applicable to the setup payment, if the amount is taxable.

setupPayments.description
string

Description. Max of 255 characters.

setupPayments.accountingCode
string

Specify an accounting code to categorise revenue collected from the setup payment. Max of 50 characters.

interval
string

Number to be specified as interval to manipulate billing frequency. For example interval=2 and intervalUnit=week would means billing every 2 weeks. If no value is provided, the default value is 1.

intervalUnit
string

Specifies frequency of billing. Valid values are day, week or month. If no value is provided, the default value is week.

billingStart
string

Specifies the default day the billing schedule starts for customers subscribed to the plan. Supported values are: immediate - Default value. Subscriptions will start on the same day. day_of_week - Subscriptions will start on a specific day as defined in billingStartValue. Only supported if interval = week day_of_month - Subscriptions will start on specific day in the month as defined in billingStartValue. Only supported if interval = month

billingEnd
string

Specifies the rules to automate when a subscription ends. Supported values are: ongoing - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). amount_collected - Subscriptions will end when a specified amount is collected as defined in billingEndValue. billing_cycles - Subscriptions will end after a specified number of billing cycles as defined in billingEndValue. end_date - Subscriptions will end on date defined in billingEndValue.

firstBilling
string

Specifies the rules to auto-calculate the billing charges for the first scheduled billing. The default value follows the plan's firstBilling. Supported values are: full_amount - The first billing will charge the full amount on the subscription as defined in the plan's amount. prorate - Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.

firstBillingAmount
object

The amount to pay for the subscription's first scheduled billing.

firstBillingAmount.currency
string
required

Three letter ISO 4217 currency code for the amount.

firstBillingAmount.value
double
required

The value of the amount. Must be positive value greater than zero.

firstBillingAmount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

metadata
object

Store additional data about the subscription object using key/value pairs format. Max of 40 characters for key name and 255 characters for key value

autoPayment
boolean

Specify if auto payment processing occurs for invoices generated from the subscription. Supported value are: true - Default value. Invoices generated will automatically proceed to payment processing. false - Invoices are generated but will not automatically proceed to payment processing.

customerEmailNotification
boolean

Specify if an email notification is sent to the customer informing them that the subscription was created or activated. Supported values are: true - An email notification will be sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. false - No email notification is sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. If not specified, follows what was defined in the merchant notification settings.

Headers

merchant
string
required

Merchant ID

 

Preview a subscription

Before creating a subscription, you can preview a subscription first to double-check that details inherited from the plan object are correct.

 
posthttps://api-sandbox.ezypay.com/v2/billing/subscriptions/preview
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/subscriptions/preview \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/subscriptions/preview',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/subscriptions/preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/subscriptions/preview");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/subscriptions/preview"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
            "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
            "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
            "name": "high_st_monthly_plan",
            "status": "ACTIVE",
            "startDate": "2019-04-01",
            "endDate": null,
            "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
            "accountingCode": "customer_plan",
            "amount": {
                "currency": "NZD",
                "value": 200,
                "type": null
            },
            "tax": {
                "rate": 0
            },
            "nextBillingDate": "2019-06-01",
            "nextFutureInvoice": null,
            "interval": 1,
            "intervalUnit": "MONTH",
            "totalPaid": {
                "currency": "NZD",
                "value": 400,
                "type": null
            },
            "totalBillingCycles": 2,
            "remainingToPay": null,
            "remainingBillingCycles": null,
            "endTargetAmount": null,
            "endTargetBillingCycles": null,
            "cancelledDate": null,
            "failedPaymentHandling": null,
            "failedAttemptsCount": 0,
            "totalPastDue": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "totalDiscounted": {
                "currency": "NZD",
                "value": 0,
                "type": null
            },
            "metadata": null,
            "createdOn": "2019-03-31T23:55:11.708",
            "autoPayment": true,
            "setupPayments": null
        }
    ],
    "paging": {
        "nextUrl": null,
        "nextCursor": 0,
        "limit": 0,
        "totalCount": 1
    }
}

Body Params

customerId
string
required

Auto-generated identifier of the customer.

planId
string
required

Auto-generated identifier of the plan.

markAsPending
boolean

Default value is false. If set to true, creates a subscription with a Pending status. A pending subscription will ignore the subscription's startDate and no schedules will be created. The status can be changed to Active using the Activate a subscription API.

startDate
string

The preferred start date of the subscription. The subscription start date cannot be back-dated. The default value follows the plan's start date. Supported format is YYYY-MM-DD.

name
string

The name of the plan to subscribe the customer to. Max of 50 characters.

accountingCode
string

Specify an accounting code to categorise revenue collected from the subscription's payment. Max of 50 characters.

amount
object

The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.

amount.currency
string
required

Three letter ISO 4217 currency code for the amount.

amount.value
double
required

The value of the amount. Must be positive value greater than zero.

amount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

tax
object

If provided, each invoice generated for this subscription will include a tax rate.

tax.rate
double

Rate of the specified tax in percentage. Supported values are from 0 to 99.99.

setupPayments
object

One-time setup payment applied to the subscription.

setupPayments.amount
object

Setup payment amount.

setupPayments.tax
object

The tax that is applicable to the setup payment, if the amount is taxable.

setupPayments.description
string

Description. Max of 255 characters.

setupPayments.accountingCode
string

Specify an accounting code to categorise revenue collected from the setup payment. Max of 50 characters.

interval
string

Number to be specified as interval to manipulate billing frequency. For example interval=2 and intervalUnit=week would means billing every 2 weeks. If no value is provided, the default value is 1.

intervalUnit
string

Specifies frequency of billing. Valid values are day, week or month. If no value is provided, the default value is week.

billingStart
string

Specifies the default day the billing schedule starts for customers subscribed to the plan. Supported values are: immediate - Default value. Subscriptions will start on the same day. day_of_week - Subscriptions will start on a specific day as defined in billingStartValue. Only supported if interval = week day_of_month - Subscriptions will start on specific day in the month as defined in billingStartValue. Only supported if interval = month

billingEnd
string

Specifies the rules to automate when a subscription ends. Supported values are: ongoing - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). amount_collected - Subscriptions will end when a specified amount is collected as defined in billingEndValue. billing_cycles - Subscriptions will end after a specified number of billing cycles as defined in billingEndValue. end_date - Subscriptions will end on date defined in billingEndValue.

firstBilling
string

Specifies the rules to auto-calculate the billing charges for the first scheduled billing. The default value follows the plan's firstBilling. Supported values are: full_amount - The first billing will charge the full amount on the subscription as defined in the plan's amount. prorate - Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.

firstBillingAmount
object

The amount to pay for the subscription's first scheduled billing.

firstBillingAmount.currency
string
required

Three letter ISO 4217 currency code for the amount.

firstBillingAmount.value
double
required

The value of the amount. Must be positive value greater than zero.

firstBillingAmount.type
string

The type of the amount value. Supported values are: percentage, fixed_amount

metadata
object

Store additional data about the subscription object using key/value pairs format. Max of 40 characters for key name and 255 characters for key value

autoPayment
boolean

Specify if auto payment processing occurs for invoices generated from the subscription. Supported value are: true - Default value. Invoices generated will automatically proceed to payment processing. false - Invoices are generated but will not automatically proceed to payment processing.

customerEmailNotification
boolean

Specify if an email notification is sent to the customer informing them that the subscription was created or activated. Supported values are: true - An email notification will be sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. false - No email notification is sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. If not specified, follows what was defined in the merchant notification settings.

Headers

merchant
string
required

Merchant ID

 

Retrieve a subscription

Retrieves a customer's subscription details.

 
gethttps://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
    "name": "high_st_monthly_plan",
    "status": "ACTIVE",
    "startDate": "2019-04-01",
    "endDate": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "accountingCode": "customer_plan",
    "amount": {
        "currency": "NZD",
        "value": 200,
        "type": null
    },
    "tax": {
        "rate": 0
    },
    "nextBillingDate": "2019-06-01",
    "nextFutureInvoice": null,
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "NZD",
        "value": 400,
        "type": null
    },
    "totalBillingCycles": 2,
    "remainingToPay": null,
    "remainingBillingCycles": null,
    "endTargetAmount": null,
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-03-31T23:55:11.708",
    "autoPayment": true,
    "setupPayments": null
}

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Headers

merchant
string
required

Merchant ID

 

Activate a subscription

Activate a pending subscription and promote its status from 'Pending' to 'Active'. An active subscription will then have payment instruction created.

 
puthttps://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/activate
{
  	"startDate": "2019-07-01",
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
    "name": "high_st_monthly_plan",
    "status": "ACTIVE",
    "startDate": "2019-07-01",
    "endDate": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "accountingCode": "customer_plan",
    "amount": {
        "currency": "NZD",
        "value": 200,
        "type": null
    },
    "tax": {
        "rate": 0
    },
    "nextBillingDate": "2019-06-01",
    "nextFutureInvoice": null,
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "NZD",
        "value": 400,
        "type": null
    },
    "totalBillingCycles": 2,
    "remainingToPay": null,
    "remainingBillingCycles": null,
    "endTargetAmount": null,
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-03-31T23:55:11.708",
    "autoPayment": true,
    "setupPayments": null
}

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Body Params

startDate
string

The preferred start date of the subscription. The subscription start date cannot be back-dated. If not specified, the subscription will start immediately on the current date (however invoices will be generated the next day).

paymentMethodToken
string

The payment method token that is generated by the vault.

Headers

merchant
string
required

Merchant ID

 

Cancel a subscription

Cancel a subscription. Cancellation stops subsequent billing and payment collections but outstanding payments will remain and need to be resolved separately. Cancellations can be set in the future but default to today.

 
puthttps://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel
{
	"cancellationDate": "2019-08-01"
}
A binary file was returned

You couldn't be authenticated

{
    "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
    "name": "high_st_monthly_plan",
    "status": "CANCELLED",
    "startDate": "2019-04-01",
    "endDate": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "accountingCode": "customer_plan",
    "amount": {
        "currency": "NZD",
        "value": 200,
        "type": null
    },
    "tax": {
        "rate": 0
    },
    "nextBillingDate": null,
    "nextFutureInvoice": null,
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "NZD",
        "value": 400,
        "type": null
    },
    "totalBillingCycles": 2,
    "remainingToPay": null,
    "remainingBillingCycles": null,
    "endTargetAmount": null,
    "endTargetBillingCycles": null,
    "cancelledDate": "2019-07-01",
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-03-31T23:55:11.708",
    "autoPayment": true,
    "setupPayments": null
}

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Body Params

cancellationDate
string

Date when subscription should be cancelled. Supported format is YYYY-MM-DD

Headers

merchant
string
required

Merchant ID

 

Update subscription's payment method

Update a subscription's payment method.

 
puthttps://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken
curl --request PUT \
  --url https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'PUT',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken"

headers = {'merchant': 'merchant'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Body Params

{}
string
required

Headers

merchant
string
required

Merchant ID

 

Undo a subscription cancellation

Undo a subscription cancellation. Only subscriptions with pending cancellation status can be undone. Subscriptions with cancelled status cannot be undone.

 
posthttps://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel
curl --request POST \
  --url https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'POST',
  url:
   'https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/subscriptions/subscriptionId/undo-cancel"

headers = {'merchant': 'merchant'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "fef9bef0-2081-445d-8a4e-b50a5d9eb2b7",
    "customerId": "4c999653-9473-472e-b478-d56d2a7572a9",
    "planId": "d35f6384-e5af-4eaf-b4c9-d08511a21921",
    "name": "high_st_monthly_plan",
    "status": "ACTIVE",
    "startDate": "2019-04-01",
    "endDate": null,
    "paymentMethodToken": "d178cea3-fdf9-4743-90d8-856af429ab18",
    "accountingCode": "customer_plan",
    "amount": {
        "currency": "NZD",
        "value": 200,
        "type": null
    },
    "tax": {
        "rate": 0
    },
    "nextBillingDate": "2019-06-01",
    "nextFutureInvoice": null,
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "NZD",
        "value": 400,
        "type": null
    },
    "totalBillingCycles": 2,
    "remainingToPay": null,
    "remainingBillingCycles": null,
    "endTargetAmount": null,
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "totalDiscounted": {
        "currency": "NZD",
        "value": 0,
        "type": null
    },
    "metadata": null,
    "createdOn": "2019-03-31T23:55:11.708",
    "autoPayment": true,
    "setupPayments": null
}

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Headers

merchant
string
required

Merchant ID

 

Transactions

 

List transactions

Get a list of of transactions for a specific customer or invoice. The transactions are returned sorted by creation date, with the most recently created transactions appearing first.

 
gethttps://api-sandbox.ezypay.com/v2/billing/transactions
curl --request GET \
  --url https://api-sandbox.ezypay.com/v2/billing/transactions \
  --header 'merchant: merchant'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-sandbox.ezypay.com/v2/billing/transactions',
  headers: { merchant: 'merchant' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ezypay.com/v2/billing/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["merchant"] = 'merchant'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-sandbox.ezypay.com/v2/billing/transactions");
xhr.setRequestHeader("merchant", "merchant");

xhr.send(data);
import requests

url = "https://api-sandbox.ezypay.com/v2/billing/transactions"

headers = {'merchant': 'merchant'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "data": [
        {
            "id": "10a59bcf-12fe-4686-b84d-3a53eb7fcea2",
            "number": null,
            "status": "SUCCESS",
            "createdOn": "2019-07-01T03:24:05.555",
            "failedOn": null,
            "amount": {
                "currency": "NZD",
                "value": 0.89,
                "type": "FIXED_AMOUNT"
            },
            "type": "PAYMENT",
            "source": "wallet",
            "paymentMethodType": null,
            "paymentMethodDescription": null,
            "failedPaymentReason": null,
            "paymentProviderResponse": {
                "co