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 Ezypay API to leverage our core services:

  • Set up flexible payment plans across multiple business sites
  • Custom brand online sign-up forms responsive on all devices
  • Schedule automated routine processes to collect recurring payments for a variety of payment methods
  • Intelligent routing system to handle and recover failed payments
  • Instant reporting capabilities with zero preparation time

The Ezypay platform is PCI DSS (Payment Card Industry Data Security Standard) accredited, ensuring all your customer debit and credit card handling, billing and payment 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://iam.ezypay.com/token \
  -H 'Authorization: application/x-www-form-urlencoded' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={username}&password={password}&client_id={client_id}&client_secret={client_secret}'

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://iam.ezypay.com/token \
  -H 'Cache-Control: no-cache' \
  -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

Authentication Error

{
  "type": "authentication_error",
  "code": "unauthorised",
  "message": "Authorization token is required."
}

Sandbox

 

To help you build your integration, we have setup a full sandbox environment for you. You can try our API to test if your code works by following this link: https://developer.ezypay.com/v2.0.1/reference

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

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-global.ezypay.com/v2/billing/creditnotes
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/creditnotes \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/creditnotes")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/creditnotes");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/creditnotes");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/creditnotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Retrieve a credit note

Get the full details of a credit note.

 
gethttps://api-global.ezypay.com/v2/billing/creditnotes/creditNoteId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/creditnotes/creditNoteId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/creditnotes/creditNoteId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/creditnotes/creditNoteId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/creditnotes/creditNoteId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/creditnotes/creditNoteId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

creditNoteId
string
required

Auto-generated identifier of the credit note.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the credit note.

invoiceIdstring

The invoice this credit note belongs to.

documentNumberstring

Auto-generated numeric identifier of the credit note. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the credit note.

statusstring

Current state of the credit note, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Credit note has been paid back to the customer accordingly.
  • processing - Credit note refund transaction is being processed.
  • failed - Attempt at refund transaction on credit note failed. This could be because the credit note gateway transaction failed; or because Ezypay won a customer dispute for a chargeback transaction and thus, the credit note is set to failed as funds are reversed back to the merchant.

itemsarray

Details of the individual items that are included in the credit note.

amountobject

Amount due for the credit note.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the credit note.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

reasonstring

The reason the credit note was created. Supported values are chargeback and refund.

customerIdstring

Identifier of the customer associated to the credit note.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token used for this payment.

Customers

 

List customers

Retrieve a list of customers that belong to the merchant.

 
gethttps://api-global.ezypay.com/v2/billing/customers
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/customers \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Create a customer

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

 
posthttps://api-global.ezypay.com/v2/billing/customers
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/customers \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
required

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

Response

OK

idstring

Auto-generated unique identifier of the customer.

numberstring

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

referenceCodestring

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

firstNamestring

Customer first name. Max of 50 characters.

lastNamestring

Customer last name. Max of 50 characters.

emailstring

Customer email. Max of 255 characters.

companyNamestring

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

mobilePhonestring

Customer mobile phone number. Max of 50 characters.

homePhonestring

Customer home phone number. Max if 50 characters.

genderstring

Customer gender. Supported values are male or female.

dateOfBirthstring

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

createdOnstring

Auto-generated date and timestamp when the object was created.

addressobject

Customer addresses. Customers can have multiple addresses.

address.address1string

First line of address. Max of 100 characters.

address.address2string

Second line of address. Max of 100 characters.

address.citystring

Town or city of address. Max of 100 characters.

address.countryCodestring

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

address.postalCodestring

The postal code of the address. Max of 20 characters

address.statestring

The state of the address. Max of 100 characters

metadataobject

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

Retrieve a customer

Retrieve the personal details of a customer.

 
gethttps://api-global.ezypay.com/v2/billing/customers/customerId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

customerId
string
required

Auto-generated identifier of the customer.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the customer.

numberstring

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

referenceCodestring

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

firstNamestring

Customer first name. Max of 50 characters.

lastNamestring

Customer last name. Max of 50 characters.

emailstring

Customer email. Max of 255 characters.

companyNamestring

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

mobilePhonestring

Customer mobile phone number. Max of 50 characters.

homePhonestring

Customer home phone number. Max if 50 characters.

genderstring

Customer gender. Supported values are male or female.

dateOfBirthstring

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

createdOnstring

Auto-generated date and timestamp when the object was created.

addressobject

Customer addresses. Customers can have multiple addresses.

address.address1string

First line of address. Max of 100 characters.

address.address2string

Second line of address. Max of 100 characters.

address.citystring

Town or city of address. Max of 100 characters.

address.countryCodestring

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

address.postalCodestring

The postal code of the address. Max of 20 characters

address.statestring

The state of the address. Max of 100 characters

metadataobject

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

Update a customer

Update an existing customer's personal details.

 
puthttps://api-global.ezypay.com/v2/billing/customers/customerId
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
required

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

Response

OK

idstring

Auto-generated unique identifier of the customer.

numberstring

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

referenceCodestring

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

firstNamestring

Customer first name. Max of 50 characters.

lastNamestring

Customer last name. Max of 50 characters.

emailstring

Customer email. Max of 255 characters.

companyNamestring

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

mobilePhonestring

Customer mobile phone number. Max of 50 characters.

homePhonestring

Customer home phone number. Max if 50 characters.

genderstring

Customer gender. Supported values are male or female.

dateOfBirthstring

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

createdOnstring

Auto-generated date and timestamp when the object was created.

addressobject

Customer addresses. Customers can have multiple addresses.

address.address1string

First line of address. Max of 100 characters.

address.address2string

Second line of address. Max of 100 characters.

address.citystring

Town or city of address. Max of 100 characters.

address.countryCodestring

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

address.postalCodestring

The postal code of the address. Max of 20 characters

address.statestring

The state of the address. Max of 100 characters

metadataobject

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

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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

paymentMethodTokenstring

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

customerIdstring

Auto-generated unique identifier of the customer that the card token is associated to.

typestring

The payment method type of the token.

bankobject

The bank details of the token.

bank.accountHolderNamestring

The account holder's name . Max 50 characters.

bank.bankNumberstring

Identifying number of the bank. Country specific rules.

bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

cardobject

The card details of the token.

card.accountHolderNamestring

The credit/debit card owner's name which is printed on the card. Max length 50 characters.

card.expiryMonthstring

The credit/debit card expiry month in (MM) format e.g 05

card.expiryYearstring

The credit/debit card expiry year in (YY) format e.g 18

card.first6string

The first 6 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.last4string

The last 4 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.typestring

The card type of the card token.

primaryboolean

Indicate whether the bank account or card is the primary payment method for the customer.

validboolean

Indicate if the bank account or card has become invalid, due to reasons such as bank account closure, expired card or withdrawn debit authority.

invalidReasonobject

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.codestring

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.descriptionstring

The description of the reason a bank account or card is no longer valid for collecting payments from the customer.

lastUsedOnstring

This payment method was last used on.

Retrieve primary payment method

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

 
gethttps://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/primary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

customerId
string
required

Auto-generated unique identifier of the customer.

Headers

Merchant
string
required

Merchant ID

Response

OK

paymentMethodTokenstring

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

customerIdstring

Auto-generated unique identifier of the customer that the card token is associated to.

typestring

The payment method type of the token.

bankobject

The bank details of the token.

bank.accountHolderNamestring

The account holder's name . Max 50 characters.

bank.bankNumberstring

Identifying number of the bank. Country specific rules.

bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

cardobject

The card details of the token.

card.accountHolderNamestring

The credit/debit card owner's name which is printed on the card. Max length 50 characters.

card.expiryMonthstring

The credit/debit card expiry month in (MM) format e.g 05

card.expiryYearstring

The credit/debit card expiry year in (YY) format e.g 18

card.first6string

The first 6 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.last4string

The last 4 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.typestring

The card type of the card token.

primaryboolean

Indicate whether the bank account or card is the primary payment method for the customer.

validboolean

Indicate if the bank account or card has become invalid, due to reasons such as bank account closure, expired card or withdrawn debit authority.

invalidReasonobject

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.codestring

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.descriptionstring

The description of the reason a bank account or card is no longer valid for collecting payments from the customer.

lastUsedOnstring

This payment method was last used on.

Retrieve a payment method

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

 
gethttps://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

paymentMethodTokenstring

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

customerIdstring

Auto-generated unique identifier of the customer that the card token is associated to.

typestring

The payment method type of the token.

bankobject

The bank details of the token.

bank.accountHolderNamestring

The account holder's name . Max 50 characters.

bank.bankNumberstring

Identifying number of the bank. Country specific rules.

bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

cardobject

The card details of the token.

card.accountHolderNamestring

The credit/debit card owner's name which is printed on the card. Max length 50 characters.

card.expiryMonthstring

The credit/debit card expiry month in (MM) format e.g 05

card.expiryYearstring

The credit/debit card expiry year in (YY) format e.g 18

card.first6string

The first 6 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.last4string

The last 4 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.typestring

The card type of the card token.

primaryboolean

Indicate whether the bank account or card is the primary payment method for the customer.

validboolean

Indicate if the bank account or card has become invalid, due to reasons such as bank account closure, expired card or withdrawn debit authority.

invalidReasonobject

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.codestring

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.descriptionstring

The description of the reason a bank account or card is no longer valid for collecting payments from the customer.

lastUsedOnstring

This payment method was last used on.

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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken
curl --request DELETE \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken")
  .delete(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken");
var request = new RestRequest(Method.DELETE);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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
required

Merchant ID

Response

OK

entityIdstring

Auto-generated identifier of the entity.

deletedboolean

Indicate if the entity is successfully deleted.

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.

Replaced payment methods and their linked tokens are then removed from the Vault. However, a payment method with an active subscriptions cannot be removed. Also, if any additional payment methods are still linked to the token, the payment method is removed only from the customer but not from the Vault.

 
puthttps://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/new",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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.

Body Params

newPaymentMethodToken
string
required

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

primary
boolean

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

Headers

Merchant
string
required

Merchant ID

Response

OK

paymentMethodTokenstring

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

customerIdstring

Auto-generated unique identifier of the customer that the card token is associated to.

typestring

The payment method type of the token.

bankobject

The bank details of the token.

bank.accountHolderNamestring

The account holder's name . Max 50 characters.

bank.bankNumberstring

Identifying number of the bank. Country specific rules.

bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

cardobject

The card details of the token.

card.accountHolderNamestring

The credit/debit card owner's name which is printed on the card. Max length 50 characters.

card.expiryMonthstring

The credit/debit card expiry month in (MM) format e.g 05

card.expiryYearstring

The credit/debit card expiry year in (YY) format e.g 18

card.first6string

The first 6 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.last4string

The last 4 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.typestring

The card type of the card token.

primaryboolean

Indicate whether the bank account or card is the primary payment method for the customer.

validboolean

Indicate if the bank account or card has become invalid, due to reasons such as bank account closure, expired card or withdrawn debit authority.

invalidReasonobject

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.codestring

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.descriptionstring

The description of the reason a bank account or card is no longer valid for collecting payments from the customer.

lastUsedOnstring

This payment method was last used on.

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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/customers/customerId/paymentmethods/paymentMethodToken/primary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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
required

Merchant ID

Response

OK

paymentMethodTokenstring

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

customerIdstring

Auto-generated unique identifier of the customer that the card token is associated to.

typestring

The payment method type of the token.

bankobject

The bank details of the token.

bank.accountHolderNamestring

The account holder's name . Max 50 characters.

bank.bankNumberstring

Identifying number of the bank. Country specific rules.

bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

cardobject

The card details of the token.

card.accountHolderNamestring

The credit/debit card owner's name which is printed on the card. Max length 50 characters.

card.expiryMonthstring

The credit/debit card expiry month in (MM) format e.g 05

card.expiryYearstring

The credit/debit card expiry year in (YY) format e.g 18

card.first6string

The first 6 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.last4string

The last 4 digits of the credit/debit card number. Full card number is not displayed for security reasons.

card.typestring

The card type of the card token.

primaryboolean

Indicate whether the bank account or card is the primary payment method for the customer.

validboolean

Indicate if the bank account or card has become invalid, due to reasons such as bank account closure, expired card or withdrawn debit authority.

invalidReasonobject

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.codestring

The reason a bank account or card is no longer valid for collecting payments from the customer.

invalidReason.descriptionstring

The description of the reason a bank account or card is no longer valid for collecting payments from the customer.

lastUsedOnstring

This payment method was last used on.

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-global.ezypay.com/v2/billing/futureinvoices
curl --request GET \
  --url 'https://api-global.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until' \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/futureinvoices?subscriptionId=subscriptionId&customerId=customerId&from=from&until=until",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Update a future invoice

Update the future invoice.

 
puthttps://api-global.ezypay.com/v2/billing/futureinvoices
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/futureinvoices \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/futureinvoices")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/futureinvoices");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/futureinvoices");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/futureinvoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

subscriptionIdstring

Auto-generated unique identifier of the subscription.

datestring

The date that the invoice will be generated.

cycleStartDatestring

The start date of the cycle.

cycleEndDatestring

The end date of the cycle.

itemsarray

List of invoice item result.

amountobject

Total amount of all items in the invoice.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

totalTaxobject

Total tax of all items in the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

Delete a future invoice

Delete the future invoice.

 
deletehttps://api-global.ezypay.com/v2/billing/futureinvoices
curl --request DELETE \
  --url https://api-global.ezypay.com/v2/billing/futureinvoices \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/futureinvoices")
  .delete(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/futureinvoices");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/futureinvoices");
var request = new RestRequest(Method.DELETE);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/futureinvoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

entityIdstring

Auto-generated identifier of the entity.

deletedboolean

Indicate if the entity is successfully deleted.

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-global.ezypay.com/v2/billing/futureinvoices/recordpayment
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/futureinvoices/recordpayment \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/futureinvoices/recordpayment")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/futureinvoices/recordpayment");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/futureinvoices/recordpayment");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/futureinvoices/recordpayment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

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-global.ezypay.com/v2/billing/invoices
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/invoices \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Query Params

customerId
string

Filter by unique identifier of the customer.

subscriptionId
string

Filter by unique identifier of the subscription.

status
string

Filter by invoice status. Supported values are paid, processing, past_due, 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
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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/billing/invoices
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/invoices \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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, sets this field to null with invoice status 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
boolean

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.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

Retrieve an invoice

Get the full details of an invoice.

 
gethttps://api-global.ezypay.com/v2/billing/invoices/invoiceId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

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-global.ezypay.com/v2/billing/invoices/invoiceId
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
object

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

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

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-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId/recordpayment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

Refund an invoice

Refund an invoice. An online refund will reuse the same invoice payment method that was used in the original transaction.

 
puthttps://api-global.ezypay.com/v2/billing/invoices/invoiceId/refund
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId/refund \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/refund")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId/refund");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/refund");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Body Params

amount
object
amount.currency
string
required

Three letter ISO 4217 currency code for the amount.

amount.value
number
required

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

items
array of objects

List of invoice line items to refund

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

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-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId/retrypayment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Body Params

oneOff
boolean

Specify if the invoice will reuse the same 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 to 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 used for this on-demand payment. The token will not replace the existing token associated to the invoice.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

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-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/invoices/invoiceId/writeoff",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

invoiceId
string
required

Auto-generated identifier of the invoice.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the invoice.

documentNumberstring

Auto-generated numeric identifier of the invoice. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the invoice. Supported format is YYYY-MM-DD.

scheduledPaymentDatestring

Next scheduled payment date in the future when payments are automatically attempted. Supported format is YYYY-MM-DD and cannot exceed more than one year (365 days). Can also be null, which means no payments are scheduled for this invoice. Payment processing will only be attempted if autoPayment = true.

statusstring

Current state of the invoice, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Paid up through automated collection, manual invoicing, or marked as paid.
  • processing - Invoice has payment being processed.
  • past_due - Attempt at payment collection on invoice failed.
  • refunded - Invoice is refunded.
  • written_off - Invoice has been written off and no billings will be attempted.

memostring

Memo of the invoice. Max of 100 characters.

itemsarray

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

amountobject

Total amount due for the invoice, inclusive of tax. If applicable, discount has also been deducted from this amount.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

amountWithoutDiscountobject

Gross total amount due for the invoice before discount applied. The sum of amount + totalDiscounted.

amountWithoutDiscount.currencystring

Three letter ISO 4217 currency code for the amount.

amountWithoutDiscount.valuenumber

The value of amount.

totalDiscountedobject

Discounted amount for the invoice.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

totalRefundedobject

Total refunded amount due for the invoice. Should not exceed total amount paid for the invoice.

totalRefunded.currencystring

Three letter ISO 4217 currency code for the amount.

totalRefunded.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

customerIdstring

Identifier of the customer the invoice is associated to.

subscriptionIdstring

Identifier of the subscription the invoice is associated to.

subscriptionNamestring

Name of the subscription the invoice is generated for.

paymentMethodTokenstring

An existing payment method token that was generated by the Ezypay Vault. If no value is provided, sets this field to null with invoice status past_due.

autoPaymentboolean

Determines if auto payment processing occurs for invoices generated from the subscription. Supported value are:

  • true - Invoices generated will automatically proceed to payment processing.
  • false - Invoices are generated but will not automatically proceed to payment processing.

createdOnstring

Auto-generated date and timestamp when the object was created.

failedPaymentReasonobject

The reason why the payment has failed.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response from payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

Merchants

 

Retrieve a merchant

Retrieve the business and address details of the respective merchant.

 
gethttps://api-global.ezypay.com/v2/billing/merchant
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/merchant
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/merchant")
  .get()
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/merchant");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/merchant",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Response

OK

idstring

Auto-generated unique identifier of the merchant.

numberstring

Auto-generated numeric identifier of the merchant. This identifier is merchant facing and is usually included in all communications to the merchant.

typestring

The type of the merchant. Supported values are business or partner.

legalNamestring

The merchant's official and legally registered name.

namestring

The merchant's trading name that is usually displayed at the business's physical property.

addressobject

Merchant's address.

address.address1string

First line of address. Max of 100 characters.

address.address2string

Second line of address. Max of 100 characters.

address.citystring

Town or city of address. Max of 100 characters.

address.countryCodestring

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

address.postalCodestring

The postal code of the address. Max of 20 characters

address.statestring

The state of the address. Max of 100 characters

countryCodestring

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

emailstring

The correspondence email of the merchant.

referenceCodestring

The merchant's reference code.

phoneNumberstring

The contact number of the merchant that can be a mobile or landline number.

billingboolean

The billing status of the merchant. Supported values are:

  • true - Merchant billing runs are enabled. Payment transactions on invoices will be processed every billing cycle.
  • false - Merchant billing runs are disabled. No payment transactions will occur.

categoryCodestring

The merchant category classification code (MCC). A four-digit number assigned to a business by credit card companies when the business first starts accepting one of these cards as a form of payment.

settlementboolean

The settlement status of the merchant. Supported values are:

  • true - Merchant settlement runs are enabled. Settlment transactions will be processed every settlement cycle.
  • false - Merchant settlement runs are disabled. No settlement transactions will occur.

statusstring

The status of the merchant. Supported values are:

  • inactive - Merchant has been created but has not been verified by risk checking.
  • pending_risk_check - Merchant is currently undergoing risk checking.
  • active - Merchant has successfully passed risk checking and has full access to all functionality.

settlementScheduleobject

The merchant's settlements schedule details.

settlementSchedule.intervalUnitstring

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

settlementSchedule.intervalinteger

Specifies the number of intervals in settlement frequency. For example interval=2 and intervalUnit="week" would means billing every 2 weeks. If no value is provided, the default value is 1.

settlementSchedule.settlementDaystring

Specifies the day the settlement schedule runs for the merchant.

  • if intervalUnit = "day", then no value required.
  • if intervalUnit = "week", then supported values are monday, tuesday, wednesday, thursday, or friday.
  • if intervalUnit = "month", then supported values are numbers between 1 to 31. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.
Note: Settlement schedules can run on weekends but, depending on the payment provider, settlements may only get processed on the next working day.

settlementSchedule.nextSettlementDatestring

Auto-generated date for next settlement date.

settlementSchedule.intervalDayTypestring

Specifies whether the next settlement date is calculated based on on calendar day or business day. This takes effect only if the intervalUnit is day. Valid values are business, calendar. If no value is provided, the default value is calendar

businessRegistrationNumberstring

The merchant's official business registration number.

settlementPayoutMethodobject

The merchant's payment method details that receives the settlement payout.

settlementPayoutMethod.idstring

Auto-generated unique identifier of the merchant that the card token is associated to.

settlementPayoutMethod.paymentMethodTokenstring

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

settlementPayoutMethod.bankobject

The bank details of the token.

settlementPayoutMethod.bank.accountHolderNamestring

The account holder's name . Max 50 characters.

settlementPayoutMethod.bank.bankNumberstring

Identifying number of the bank. Country specific rules.

settlementPayoutMethod.bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

settlementPayoutMethod.bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

settlementPayoutMethod.bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

acceptedPaymentMethodsarray

The list of accepted payment methods supported. Supported values are bank, mastercard, visa and amex.

taxIdstring

The merchant's tax identification used for tax reporting purposes.

failedPaymentHandlingobject

The failed payment settings that are applied to past due invoices.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

websitestring

The merchant's website address.

descriptionstring

Brief additional description of the merchant such as their slogan.

paymentReactivationHandlingstring

The reactivation settings applied to a merchant.

taxobject

Tax applied to all tax options under the merchant such as within invoices and plans.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

feePricingIdstring

The merchant's fee pricing plan id

notificationsobject

Notification setting of the merchant.

notifications.customerEmailobject

Customer email notification settings

notifications.customerEmail.pastDueInvoiceboolean

Flag to turn on notification for Past due invoice

notifications.customerEmail.paymentMethodCreationboolean

Flag to turn on notification for Payment method creation

notifications.customerEmail.subscriptionCreationboolean

Flag to turn on notification for Subscription creation

documentNumberSettingsarray
metadataobject

Additional data about the merchant object using key/value pairs format.

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-global.ezypay.com/v2/billing/merchant/creditnotes
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/merchant/creditnotes \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/merchant/creditnotes")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/merchant/creditnotes");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/merchant/creditnotes");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/merchant/creditnotes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Query Params

from
string

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

until
string

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

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Retrieve a credit note

Get the full details of a credit note.

 
gethttps://api-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/merchant/creditnotes/creditNoteId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

creditNoteId
string
required

Auto-generated identifier of the credit note.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the credit note.

documentNumberstring

Auto-generated numeric identifier of the credit note. This identifier is customer facing and included in all invoicing related communications with the customer.

datestring

Issue date of the credit note.

statusstring

Current state of the credit note, automated based on the associated payments or manually by merchant actions. Supported values are:

  • paid - Credit note has been paid back to the customer accordingly.
  • due - Credit note refund transaction is being processed.

itemsarray

Details of the individual items that are included in the credit note.

amountobject

Amount due for the credit note.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the credit note.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

Update a merchant's failed payment handling

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

 
puthttps://api-global.ezypay.com/v2/billing/merchant/failedpaymenthandling
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/merchant/failedpaymenthandling \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/merchant/failedpaymenthandling")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/merchant/failedpaymenthandling");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/merchant/failedpaymenthandling");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/merchant/failedpaymenthandling",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

idstring

Auto-generated unique identifier of the merchant.

numberstring

Auto-generated numeric identifier of the merchant. This identifier is merchant facing and is usually included in all communications to the merchant.

typestring

The type of the merchant. Supported values are business or partner.

legalNamestring

The merchant's official and legally registered name.

namestring

The merchant's trading name that is usually displayed at the business's physical property.

addressobject

Merchant's address.

address.address1string

First line of address. Max of 100 characters.

address.address2string

Second line of address. Max of 100 characters.

address.citystring

Town or city of address. Max of 100 characters.

address.countryCodestring

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

address.postalCodestring

The postal code of the address. Max of 20 characters

address.statestring

The state of the address. Max of 100 characters

countryCodestring

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

emailstring

The correspondence email of the merchant.

referenceCodestring

The merchant's reference code.

phoneNumberstring

The contact number of the merchant that can be a mobile or landline number.

billingboolean

The billing status of the merchant. Supported values are:

  • true - Merchant billing runs are enabled. Payment transactions on invoices will be processed every billing cycle.
  • false - Merchant billing runs are disabled. No payment transactions will occur.

categoryCodestring

The merchant category classification code (MCC). A four-digit number assigned to a business by credit card companies when the business first starts accepting one of these cards as a form of payment.

settlementboolean

The settlement status of the merchant. Supported values are:

  • true - Merchant settlement runs are enabled. Settlment transactions will be processed every settlement cycle.
  • false - Merchant settlement runs are disabled. No settlement transactions will occur.

statusstring

The status of the merchant. Supported values are:

  • inactive - Merchant has been created but has not been verified by risk checking.
  • pending_risk_check - Merchant is currently undergoing risk checking.
  • active - Merchant has successfully passed risk checking and has full access to all functionality.

settlementScheduleobject

The merchant's settlements schedule details.

settlementSchedule.intervalUnitstring

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

settlementSchedule.intervalinteger

Specifies the number of intervals in settlement frequency. For example interval=2 and intervalUnit="week" would means billing every 2 weeks. If no value is provided, the default value is 1.

settlementSchedule.settlementDaystring

Specifies the day the settlement schedule runs for the merchant.

  • if intervalUnit = "day", then no value required.
  • if intervalUnit = "week", then supported values are monday, tuesday, wednesday, thursday, or friday.
  • if intervalUnit = "month", then supported values are numbers between 1 to 31. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.
Note: Settlement schedules can run on weekends but, depending on the payment provider, settlements may only get processed on the next working day.

settlementSchedule.nextSettlementDatestring

Auto-generated date for next settlement date.

settlementSchedule.intervalDayTypestring

Specifies whether the next settlement date is calculated based on on calendar day or business day. This takes effect only if the intervalUnit is day. Valid values are business, calendar. If no value is provided, the default value is calendar

businessRegistrationNumberstring

The merchant's official business registration number.

settlementPayoutMethodobject

The merchant's payment method details that receives the settlement payout.

settlementPayoutMethod.idstring

Auto-generated unique identifier of the merchant that the card token is associated to.

settlementPayoutMethod.paymentMethodTokenstring

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

settlementPayoutMethod.bankobject

The bank details of the token.

settlementPayoutMethod.bank.accountHolderNamestring

The account holder's name . Max 50 characters.

settlementPayoutMethod.bank.bankNumberstring

Identifying number of the bank. Country specific rules.

settlementPayoutMethod.bank.branchNumberstring

Identifying number for a bank branch. Max of 4 digits for New Zealand.

settlementPayoutMethod.bank.last4string

The last 4 digits of the bank account number. Full account number is not displayed for security reasons.

settlementPayoutMethod.bank.suffixNumberstring

Only required by New Zealand Banks. Must be between 2-3 digits.

acceptedPaymentMethodsarray

The list of accepted payment methods supported. Supported values are bank, mastercard, visa and amex.

taxIdstring

The merchant's tax identification used for tax reporting purposes.

failedPaymentHandlingobject

The failed payment settings that are applied to past due invoices.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

websitestring

The merchant's website address.

descriptionstring

Brief additional description of the merchant such as their slogan.

paymentReactivationHandlingstring

The reactivation settings applied to a merchant.

taxobject

Tax applied to all tax options under the merchant such as within invoices and plans.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

feePricingIdstring

The merchant's fee pricing plan id

notificationsobject

Notification setting of the merchant.

notifications.customerEmailobject

Customer email notification settings

notifications.customerEmail.pastDueInvoiceboolean

Flag to turn on notification for Past due invoice

notifications.customerEmail.paymentMethodCreationboolean

Flag to turn on notification for Payment method creation

notifications.customerEmail.subscriptionCreationboolean

Flag to turn on notification for Subscription creation

documentNumberSettingsarray
metadataobject

Additional data about the merchant object using key/value pairs format.

Update a merchant's notification settings

Update a merchant's notification settings.

 
puthttps://api-global.ezypay.com/v2/billing/merchant/notificationsettings
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/merchant/notificationsettings \
  --header 'merchant: Merchant' \
  --header 'merchantid: merchantId'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/merchant/notificationsettings")
  .put(null)
  .addHeader("merchantid", "merchantId")
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/merchant/notificationsettings");
xhr.setRequestHeader("merchantid", "merchantId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/merchant/notificationsettings");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
request.AddHeader("merchantid", "merchantId");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/merchant/notificationsettings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant",
    "merchantid: merchantId"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Body Params

merchantId
string
customerEmail
object

Customer email notification settings

customerEmail.pastDueInvoice
object

Flag to turn on notification for Past due invoice

customerEmail.paymentMethodCreation
object

Flag to turn on notification for Payment method creation

customerEmail.subscriptionCreation
object

Flag to turn on notification for Subscription creation

Headers

merchantId
string
required

Identifier of the merchant to update.

Merchant
string
required

Merchant ID

Response

OK

customerEmailobject

Customer email notification settings

customerEmail.pastDueInvoiceboolean

Flag to turn on notification for Past due invoice

customerEmail.paymentMethodCreationboolean

Flag to turn on notification for Payment method creation

customerEmail.subscriptionCreationboolean

Flag to turn on notification for Subscription creation

Plans

 

List plans

Get a list of plans.

 
gethttps://api-global.ezypay.com/v2/billing/plans
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/plans \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/plans")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/plans");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/plans");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/plans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/billing/plans
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/plans \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/plans")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/plans");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/plans");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/plans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
number
required

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

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
number

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

Response

OK

idstring

Auto-generated identifier of the plan.

statusstring

Current state of the plan. Supported values are:

  • active - Customers can subscribe to the plan.
  • inactive - Customers are unable to subscribe to the plan.

namestring

Plan name. Max of 50 characters.

memostring

Brief memo of the plan.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The amount charged for the plan schedule.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

The tax that is applicable for the plan.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

The set up payments

intervalUnitstring

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

intervalinteger

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.

billingStartstring

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.

billingStartValuestring

Specifies the value corresponding to billingStart. If using immediate, no value is required and default value is null.

  • If billingStart = day_of_week then supported values are monday, tuesday, wednesday, thursday, friday, saturday or sunday. Default value is monday and the billing schedule will start on the first up-coming Monday
  • If billingStart = day_of_month then supported values are numbers between 1 to 31. Default value is 1 and the billing schedule will start on the upcoming 1st of the month. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

createdOnstring

DateTime the plan was created. Supported format is YYYY-MM-DD.

billingEndstring

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.

billingEndValuestring

Specifies the value corresponding to billingEnd. If using ongoing, no value is required and default value is null.

  • If billingEnd = amount_collected then provide an amount to be collected.
  • If billingEnd = billing_cycles then provide a number of billing cycles. If it is a one-off plan, set billingEndValue = 1.

firstBillingstring

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.

recurringBillingDaystring

Only usable when billingStart is set to immediate. Specifies the day recurring billing will occur after the first billing cycle.

  • If interval = week then supported values are monday, tueday, wednesday, thursday, friday, saturday or sunday. Default value is monday.
  • If interval = month then supported values are numbers between 1 and 31. Default value is 1. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the merchant settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

metadataobject

Additional data about the plan object using key/value pairs format.

Retrieve a plan

Gets the full details of a plan.

 
gethttps://api-global.ezypay.com/v2/billing/plans/planId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/plans/planId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/plans/planId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/plans/planId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/plans/planId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/plans/planId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

planId
string
required

Identifier of the plan to retrieve.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the plan.

statusstring

Current state of the plan. Supported values are:

  • active - Customers can subscribe to the plan.
  • inactive - Customers are unable to subscribe to the plan.

namestring

Plan name. Max of 50 characters.

memostring

Brief memo of the plan.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The amount charged for the plan schedule.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

The tax that is applicable for the plan.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

The set up payments

intervalUnitstring

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

intervalinteger

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.

billingStartstring

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.

billingStartValuestring

Specifies the value corresponding to billingStart. If using immediate, no value is required and default value is null.

  • If billingStart = day_of_week then supported values are monday, tuesday, wednesday, thursday, friday, saturday or sunday. Default value is monday and the billing schedule will start on the first up-coming Monday
  • If billingStart = day_of_month then supported values are numbers between 1 to 31. Default value is 1 and the billing schedule will start on the upcoming 1st of the month. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

createdOnstring

DateTime the plan was created. Supported format is YYYY-MM-DD.

billingEndstring

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.

billingEndValuestring

Specifies the value corresponding to billingEnd. If using ongoing, no value is required and default value is null.

  • If billingEnd = amount_collected then provide an amount to be collected.
  • If billingEnd = billing_cycles then provide a number of billing cycles. If it is a one-off plan, set billingEndValue = 1.

firstBillingstring

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.

recurringBillingDaystring

Only usable when billingStart is set to immediate. Specifies the day recurring billing will occur after the first billing cycle.

  • If interval = week then supported values are monday, tueday, wednesday, thursday, friday, saturday or sunday. Default value is monday.
  • If interval = month then supported values are numbers between 1 and 31. Default value is 1. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the merchant settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

metadataobject

Additional data about the plan object using key/value pairs format.

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-global.ezypay.com/v2/billing/plans/planId
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/plans/planId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/plans/planId")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/plans/planId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/plans/planId");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/plans/planId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
number
required

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

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.

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
number

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
object

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

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the plan.

statusstring

Current state of the plan. Supported values are:

  • active - Customers can subscribe to the plan.
  • inactive - Customers are unable to subscribe to the plan.

namestring

Plan name. Max of 50 characters.

memostring

Brief memo of the plan.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The amount charged for the plan schedule.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

The tax that is applicable for the plan.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

The set up payments

intervalUnitstring

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

intervalinteger

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.

billingStartstring

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.

billingStartValuestring

Specifies the value corresponding to billingStart. If using immediate, no value is required and default value is null.

  • If billingStart = day_of_week then supported values are monday, tuesday, wednesday, thursday, friday, saturday or sunday. Default value is monday and the billing schedule will start on the first up-coming Monday
  • If billingStart = day_of_month then supported values are numbers between 1 to 31. Default value is 1 and the billing schedule will start on the upcoming 1st of the month. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

createdOnstring

DateTime the plan was created. Supported format is YYYY-MM-DD.

billingEndstring

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.

billingEndValuestring

Specifies the value corresponding to billingEnd. If using ongoing, no value is required and default value is null.

  • If billingEnd = amount_collected then provide an amount to be collected.
  • If billingEnd = billing_cycles then provide a number of billing cycles. If it is a one-off plan, set billingEndValue = 1.

firstBillingstring

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.

recurringBillingDaystring

Only usable when billingStart is set to immediate. Specifies the day recurring billing will occur after the first billing cycle.

  • If interval = week then supported values are monday, tueday, wednesday, thursday, friday, saturday or sunday. Default value is monday.
  • If interval = month then supported values are numbers between 1 and 31. Default value is 1. If the value specified is 29, 30 or 31 and the next month does not have these dates, it will automatically be rounded to the last day of the month.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the merchant settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

metadataobject

Additional data about the plan object using key/value pairs format.

Settlements

 

List settlements

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

 
gethttps://api-global.ezypay.com/v2/billing/settlements
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/settlements \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/settlements")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/settlements");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/settlements");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/settlements",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Generate group settlement report by accounting code

Generate a group settlement report by accounting code.

 
posthttps://api-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/settlements/groupedbyaccountingcode/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Body Params

dateFrom
string

Start date (inclusive) that the Group Settlement Report should cover, in format YYYY-MM-DD.

dateTo
string

End date (inclusive) that the Group Settlement Report should cover, in format YYYY-MM-DD.

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.

merchantIds
array of strings

Restrict the Group Settlement Report to a specified set of Merchants.

Headers

Merchant
string
required

Merchant ID

Response

OK

fileIdstring

Auto-generated identifier of the file.

createdOnstring

Auto-generated date and time of file generation.

documentTypestring

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.
summary_report: Generates a summary report (in .pdf format) on the settlement status of payment collections from customers.

Generate group settlement report by transaction status

Generate a group settlement report by transaction status.

 
posthttps://api-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/settlements/groupedbytransactionstatus/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Body Params

dateFrom
string

Start date (inclusive) that the Group Settlement Report should cover, in format YYYY-MM-DD.

dateTo
string

End date (inclusive) that the Group Settlement Report should cover, in format YYYY-MM-DD.

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.

merchantIds
array of strings

Restrict the Group Settlement Report to a specified set of Merchants.

Headers

Merchant
string
required

Merchant ID

Response

OK

fileIdstring

Auto-generated identifier of the file.

createdOnstring

Auto-generated date and time of file generation.

documentTypestring

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.
summary_report: Generates a summary report (in .pdf format) on the settlement status of payment collections from customers.

Subscriptions

 

List subscriptions

List all subscriptions belonging to a customer.

 
gethttps://api-global.ezypay.com/v2/billing/subscriptions
curl --request GET \
  --url 'https://api-global.ezypay.com/v2/billing/subscriptions?customerId=customerId' \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions?customerId=customerId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions?customerId=customerId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions?customerId=customerId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions?customerId=customerId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/billing/subscriptions
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/subscriptions \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
number
required

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

tax
object

If provided, each invoice generated for this subscription will include a tax rate.

tax.rate
number

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.

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
number
required

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

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

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

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-global.ezypay.com/v2/billing/subscriptions/preview
curl --request POST \
  --url https://api-global.ezypay.com/v2/billing/subscriptions/preview \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions/preview")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions/preview");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions/preview");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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
number
required

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

tax
object

If provided, each invoice generated for this subscription will include a tax rate.

tax.rate
number

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.

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
number
required

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

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

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

Retrieve a subscription

Retrieves a customer's subscription details.

 
gethttps://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions/subscriptionId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

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-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/activate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

Cancel a subscription

Cancel a subscription. Cancellation stops subsequent billing and payment collections but outstanding payments will remain and need to be resolved separately.

 
puthttps://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

Update subscription's payment method

Update a subscription's payment method.

 
puthttps://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken
curl --request PUT \
  --url https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/subscriptions/subscriptionId/paymentmethod/paymentMethodToken",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

subscriptionId
string
required

Auto-generated unique identifier of the subscription.

paymentMethodToken
string
required

Payment method token.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the subscription.

customerIdstring

Auto-generated unique identifier of the customer that the subscription is associated to.

planIdstring

Auto-generated identifier of the plan where this subscription was instantiated from.

namestring

The name of the subscription, which is copied over from the plan's name.

statusstring

Current state of the subscription. Supported values are:

  • pending - The subscription has not yet been activated and has no start date set.
  • future - The subscription start date is on a future date.
  • active - The subscription is actively being billed.
  • past_due The subscription has an invoice with a status that is past_due.
  • completed - The subscription has ended and reached the end billing requirements as defined in billingEnd.
  • cancelled - The subscription was cancelled by the merchant, before completing its course.

startDatestring

The subscription's start date.

endDatestring

The subscription's end date.

paymentMethodTokenstring

Auto-generated unique identifier of the payment method token for this billing schedule.

accountingCodestring

The category for revenue streams for finance reconciliation purposes.

amountobject

The schedule's amount to be charge for each interval.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

taxobject

If provided, each invoice generated for this subscription will include a tax rate, but the amount charged to the customer will not be increased.

tax.ratenumber

Tax rate in percentage format. Supported values are from 0 to 99.99.

setupPaymentsarray

One-time setup payment applied to the subscription.

nextBillingDatestring

The upcoming date where the customer will be charged for this subscription.

nextFutureInvoiceobject

Details of the next upcoming invoice.

nextFutureInvoice.subscriptionIdstring

Auto-generated unique identifier of the subscription.

nextFutureInvoice.datestring

The date that the invoice will be generated.

nextFutureInvoice.cycleStartDatestring

The start date of the cycle.

nextFutureInvoice.cycleEndDatestring

The end date of the cycle.

nextFutureInvoice.itemsarray

List of invoice item result.

nextFutureInvoice.amountobject

Total amount of all items in the invoice.

nextFutureInvoice.amount.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.amount.valuenumber

The value of amount.

nextFutureInvoice.totalTaxobject

Total tax of all items in the invoice.

nextFutureInvoice.totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

nextFutureInvoice.totalTax.valuenumber

The value of amount.

intervalinteger

The schedule's intervals.

intervalUnitstring

The schedule's interval unit.

totalPaidobject

Total payment collected for this subscription so far.

totalPaid.currencystring

Three letter ISO 4217 currency code for the amount.

totalPaid.valuenumber

The value of amount.

totalBillingCyclesinteger

Total payment cycle processed for this subscription far.

remainingToPayobject

Total remaining payments to be collected for this subscription, if it is a recurring.

remainingToPay.currencystring

Three letter ISO 4217 currency code for the amount.

remainingToPay.valuenumber

The value of amount.

remainingBillingCyclesinteger

Total remaining payment cycles to be processed for this subscription.

endTargetAmountobject

The schedule's total amount to be collected.

endTargetAmount.currencystring

Three letter ISO 4217 currency code for the amount.

endTargetAmount.valuenumber

The value of amount.

endTargetBillingCyclesinteger

The schedule's total cycles to be collected.

cancelledDatestring

The date that the cancellation will be effective on.

failedPaymentHandlingobject

The actions taken when a failed payment occurs. If not specified, settings are inherited from the plan settings.

failedPaymentHandling.initialActionstring

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.

failedPaymentHandling.autoRetryboolean

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

failedPaymentHandling.retryInDaysinteger

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

failedPaymentHandling.maximumFailedAttemptsinteger

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

failedAttemptsCountinteger

The total number of subscription's failed attempts

totalPastDueobject

Total amount from all past due invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalPastDue.currencystring

Three letter ISO 4217 currency code for the amount.

totalPastDue.valuenumber

The value of amount.

totalDiscountedobject

Total discounted amount from all invoices associated to this subscription. Includes only invoice items with type for merchant revenue (i.e. subscription_payment, on_demand_payment, addon_payment, setup_payment) and not platform fee revenue.

totalDiscounted.currencystring

Three letter ISO 4217 currency code for the amount.

totalDiscounted.valuenumber

The value of amount.

metadataobject

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

createdOnstring

Created date of subscription

autoPaymentboolean

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.

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-global.ezypay.com/v2/billing/transactions
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/transactions \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/transactions")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/transactions");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/transactions");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Query Params

transactionNumber
string

Transaction identifier generated by the payment processor.

senderId
string

Identifier of the sender who sent the funds.

receiverId
string

Identifier of the recipient who received the funds.

documentId
string

Identifier of the document that triggered this transaction.

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.

from
string

Start date for range of transactions to view. Filter by date defined in createdOn. Supported format is YYYY-MM-DD.

until
string

End date for range of transactions to view. Filter by date defined in createdOn. Supported format is YYYY-MM-DD.

status
string

State of the transaction attempt. Supported values are success, processing, failed or settled.

Headers

Merchant
string
required

Merchant ID

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Retrieve a transaction

Retrieves the full details of a transaction.

 
gethttps://api-global.ezypay.com/v2/billing/transactions/transactionId
curl --request GET \
  --url https://api-global.ezypay.com/v2/billing/transactions/transactionId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/billing/transactions/transactionId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/billing/transactions/transactionId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/billing/transactions/transactionId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/billing/transactions/transactionId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

transactionId
string
required

Auto-generated unique identifier of the transaction.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the payment.

numberstring

Transaction identifier generated by the payment processor.

statusstring

State of the transaction attempt. Supported values are success, processing, failed or settled.

createdOnstring

Date and timestamp when the transaction occurred.

failedOnstring

Date and timestamp if a failed transaction occurred.

amountobject

Amount transacted in the payment.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

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

typestring

Identifies the transaction type. Supported values are:

  • payment - Transaction was processing a payment.
  • refund - Transaction was processing a refund.
  • partner_payment - Transaction was processing a partner merchant related payment.
  • fee_revenue_share - Transaction was processing a fee revenue share.

sourcestring

Identifies the payment source. Supported values are:

  • payment_processor - Transaction was processed by payment processors such as banks, credit or debit cards, or direct debits.
  • wallet - Transaction occurred within the Ezypay system between merchant escrow accounts.
  • external - Transaction occurred outside the Ezypay system and was not processed by Ezypay.

paymentMethodTypestring

Payment method type used in the transaction.

paymentMethodDescriptionstring

Payment method description used in the transaction.

failedPaymentReasonobject

Failed payment reason explaining reason for transaction failure if available.

failedPaymentReason.codestring

Error code for failed payment.

failedPaymentReason.descriptionstring

Description of reason for failed payment.

paymentProviderResponseobject

The response of payment provider.

paymentProviderResponse.codestring

Response code from the payment provider.

paymentProviderResponse.descriptionstring

Description of reason from the payment provider.

documentobject

Details of the document that triggered the transaction.

document.idstring

Identifier of the document that triggered this transaction.

document.numberstring

Auto-generated numeric identified of the document that triggered this transaction.

document.typestring

Specifies the document type. Supported values are: transfer, credit_note, invoice, and settlement.

senderobject

Details of the sender.

sender.idstring

Identifier of the party associated to this transaction.

sender.namestring

Name of the party involved in the transaction.

sender.typestring

Specifies the type. Supported values are: customer, merchant, and Ezypay.

receiverobject

Details of the receiver.

receiver.idstring

Identifier of the party associated to this transaction.

receiver.namestring

Name of the party involved in the transaction.

receiver.typestring

Specifies the type. Supported values are: customer, merchant, and Ezypay.

channelstring

The channel used to invoke the invoice transaction. Supported values are api and online_payment_recovery.

Merchant Connections

 

List merchant connections

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

 
gethttps://api-global.ezypay.com/v2/merchantconnections
curl --request GET \
  --url https://api-global.ezypay.com/v2/merchantconnections \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/merchantconnections")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/merchantconnections");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/merchantconnections");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/merchantconnections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

Create a merchant connection

Create a merchant connection.

 
posthttps://api-global.ezypay.com/v2/merchantconnections
curl --request POST \
  --url https://api-global.ezypay.com/v2/merchantconnections \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/merchantconnections")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/merchantconnections");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/merchantconnections");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/merchantconnections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Body Params

requesterId
string
required

Auto-generated unique identifier of the merchant that is requesting the connection.

requesterDetails
string

Details of the requester merchant.

accepterId
string
required

Auto-generated unique identifier of the merchant that is accepting the connection.

accepterDetails
string

Details of the requester merchant.

permissions
array of strings
required

The type of connection allowed between the two merchants. You can specify multiple values. Supported values are:

  • partner_invoice - The requester merchant can issue on-demand partner invoices to the accepter merchant.
  • partner_invoice_inter_merchant - The requester merchant can issue on-demand partner invoices on behalf of the accepter merchant to another merchant. The requester merchant must have a connection with both merchants.
  • partner_subscription - The accepter merchant can subscribe to partner subscriptions created by the requester merchant.
  • partner_revenue_share - The requester merchant can collect a portion of funds from the accepter merchant using revenue share.

description
string

Brief description of the merchant connection that can be merchant facing.

termsAndConditionsURL
string

Terms and Conditions URL.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the merchant connection.

statusstring

Current status of the 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.

requesterobject

Details of the requester merchant.

requester.idstring

Auto-generated unique identifier of the merchant.

requester.namestring

The merchant's trading name that is usually displayed at the business's physical property.

requester.legalNamestring

The merchant's official and legally registered name.

requesterDetailsstring

Description of the requester merchant.

accepterobject

Details of the accepter merchant.

accepter.idstring

Auto-generated unique identifier of the merchant.

accepter.namestring

The merchant's trading name that is usually displayed at the business's physical property.

accepter.legalNamestring

The merchant's official and legally registered name.

accepterDetailsstring

Description of the accepter merchant.

createdBystring

The user that created the merchant connection.

createdOnstring

Auto-generated date and timestamp when the object was created.

approvedBystring

The user that approved the merchant connection.

approvedOnstring

Auto-generated date and timestamp when the merchant connection was approved.

permissionsarray

List of permissions allowed for this merchant connection.

descriptionstring

Brief description of this merchant connection that can be merchant facing.

termsAndConditionsURLstring

Terms and Conditions URL

Retrieve a merchant connection

Get the full details of a merchant connection.

 
gethttps://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId
curl --request GET \
  --url https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/merchantconnections/merchantConnectionId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

merchantConnectionId
string
required

Auto-generated unique identifier of the merchant connection.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the merchant connection.

statusstring

Current status of the 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.

requesterobject

Details of the requester merchant.

requester.idstring

Auto-generated unique identifier of the merchant.

requester.namestring

The merchant's trading name that is usually displayed at the business's physical property.

requester.legalNamestring

The merchant's official and legally registered name.

requesterDetailsstring

Description of the requester merchant.

accepterobject

Details of the accepter merchant.

accepter.idstring

Auto-generated unique identifier of the merchant.

accepter.namestring

The merchant's trading name that is usually displayed at the business's physical property.

accepter.legalNamestring

The merchant's official and legally registered name.

accepterDetailsstring

Description of the accepter merchant.

createdBystring

The user that created the merchant connection.

createdOnstring

Auto-generated date and timestamp when the object was created.

approvedBystring

The user that approved the merchant connection.

approvedOnstring

Auto-generated date and timestamp when the merchant connection was approved.

permissionsarray

List of permissions allowed for this merchant connection.

descriptionstring

Brief description of this merchant connection that can be merchant facing.

termsAndConditionsURLstring

Terms and Conditions URL

Activate a merchant connection

Activate a merchant connection.

 
puthttps://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate
curl --request PUT \
  --url https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/activate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

merchantConnectionId
string
required

Auto-generated unique identifier of the merchant connection.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the merchant connection.

statusstring

Current status of the 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.

requesterobject

Details of the requester merchant.

requester.idstring

Auto-generated unique identifier of the merchant.

requester.namestring

The merchant's trading name that is usually displayed at the business's physical property.

requester.legalNamestring

The merchant's official and legally registered name.

requesterDetailsstring

Description of the requester merchant.

accepterobject

Details of the accepter merchant.

accepter.idstring

Auto-generated unique identifier of the merchant.

accepter.namestring

The merchant's trading name that is usually displayed at the business's physical property.

accepter.legalNamestring

The merchant's official and legally registered name.

accepterDetailsstring

Description of the accepter merchant.

createdBystring

The user that created the merchant connection.

createdOnstring

Auto-generated date and timestamp when the object was created.

approvedBystring

The user that approved the merchant connection.

approvedOnstring

Auto-generated date and timestamp when the merchant connection was approved.

permissionsarray

List of permissions allowed for this merchant connection.

descriptionstring

Brief description of this merchant connection that can be merchant facing.

termsAndConditionsURLstring

Terms and Conditions URL

Cancel a merchant connection

Cancel a merchant connection. All ongoing partner subscriptions associated with this merchant connection are also cancelled.

 
puthttps://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel
curl --request PUT \
  --url https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel")
  .put(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel");
var request = new RestRequest(Method.PUT);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/merchantconnections/merchantConnectionId/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

merchantConnectionId
string
required

Auto-generated unique identifier of the merchant connection.

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated unique identifier of the merchant connection.

statusstring

Current status of the 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.

requesterobject

Details of the requester merchant.

requester.idstring

Auto-generated unique identifier of the merchant.

requester.namestring

The merchant's trading name that is usually displayed at the business's physical property.

requester.legalNamestring

The merchant's official and legally registered name.

requesterDetailsstring

Description of the requester merchant.

accepterobject

Details of the accepter merchant.

accepter.idstring

Auto-generated unique identifier of the merchant.

accepter.namestring

The merchant's trading name that is usually displayed at the business's physical property.

accepter.legalNamestring

The merchant's official and legally registered name.

accepterDetailsstring

Description of the accepter merchant.

createdBystring

The user that created the merchant connection.

createdOnstring

Auto-generated date and timestamp when the object was created.

approvedBystring

The user that approved the merchant connection.

approvedOnstring

Auto-generated date and timestamp when the merchant connection was approved.

permissionsarray

List of permissions allowed for this merchant connection.

descriptionstring

Brief description of this merchant connection that can be merchant facing.

termsAndConditionsURLstring

Terms and Conditions URL

Partner Invoices

 

List partner invoices

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

 
gethttps://api-global.ezypay.com/v2/partnerinvoices
curl --request GET \
  --url https://api-global.ezypay.com/v2/partnerinvoices
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/partnerinvoices")
  .get()
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/partnerinvoices");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/partnerinvoices");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/partnerinvoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Query Params

issuerMerchantId
string

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

recipientMerchantId
string

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
string

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

until
string

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/partnerinvoices
curl --request POST \
  --url https://api-global.ezypay.com/v2/partnerinvoices
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/partnerinvoices")
  .post(null)
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/partnerinvoices");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/partnerinvoices");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/partnerinvoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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

Response

OK

idstring

Auto-generated identifier of the partner invoice.

documentNumberstring

Auto-generated numeric identifier of the partner invoice. This identifier is included in all invoicing related reports and communications with the merchant.

datestring

Issue date of the partner invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the partner invoice. Supported format is YYYY-MM-DD.

statusstring

Current state of the partner invoice. Supported values are:

  • paid - Payment transaction for invoice completed successfully.
  • failed - Payment transaction for invoice failed or was unsuccessful.

memostring

Memo of the invoice.

itemsarray

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

amountobject

Gross amount due for the invoice.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

issuerMerchantobject

Details of the merchant that issued the invoice.

issuerMerchant.idstring

Auto-generated unique identifier of the merchant.

issuerMerchant.legalNamestring

The merchant's official and legally registered name.

issuerMerchant.namestring

The merchant's trading name that is usually displayed at the business's physical property.

recipientMerchantobject

Details of the merchant that received the invoice.

recipientMerchant.idstring

Auto-generated unique identifier of the merchant.

recipientMerchant.legalNamestring

The merchant's official and legally registered name.

recipientMerchant.namestring

The merchant's trading name that is usually displayed at the business's physical property.

createdOnstring

Auto-generated date and timestamp when the object was created.

countryCodestring

Two letter ISO 3166-1 alpha-2 country code of the issuing merchant.

partnerSubscriptionIdstring

Auto-generated identifier of the partner subscription.

Attempt payment on a partner invoice

Manually attempt to collect payment for a past due partner invoice.

 
posthttps://api-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId
curl --request POST \
  --url https://api-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId")
  .post(null)
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId");
var request = new RestRequest(Method.POST);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/retrypartnerinvoices/partnerInvoiceId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Path Params

partnerInvoiceId
string
required

Partner invoice id

Headers

Merchant
string
required

Merchant ID

Response

OK

idstring

Auto-generated identifier of the partner invoice.

documentNumberstring

Auto-generated numeric identifier of the partner invoice. This identifier is included in all invoicing related reports and communications with the merchant.

datestring

Issue date of the partner invoice. Supported format is YYYY-MM-DD.

dueDatestring

Due date of the partner invoice. Supported format is YYYY-MM-DD.

statusstring

Current state of the partner invoice. Supported values are:

  • paid - Payment transaction for invoice completed successfully.
  • failed - Payment transaction for invoice failed or was unsuccessful.

memostring

Memo of the invoice.

itemsarray

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

amountobject

Gross amount due for the invoice.

amount.currencystring

Three letter ISO 4217 currency code for the amount.

amount.valuenumber

The value of amount.

totalTaxobject

Total tax amount due for the invoice.

totalTax.currencystring

Three letter ISO 4217 currency code for the amount.

totalTax.valuenumber

The value of amount.

issuerMerchantobject

Details of the merchant that issued the invoice.

issuerMerchant.idstring

Auto-generated unique identifier of the merchant.

issuerMerchant.legalNamestring

The merchant's official and legally registered name.

issuerMerchant.namestring

The merchant's trading name that is usually displayed at the business's physical property.

recipientMerchantobject

Details of the merchant that received the invoice.

recipientMerchant.idstring

Auto-generated unique identifier of the merchant.

recipientMerchant.legalNamestring

The merchant's official and legally registered name.

recipientMerchant.namestring

The merchant's trading name that is usually displayed at the business's physical property.

createdOnstring

Auto-generated date and timestamp when the object was created.

countryCodestring

Two letter ISO 3166-1 alpha-2 country code of the issuing merchant.

partnerSubscriptionIdstring

Auto-generated identifier of the partner subscription.

Partner Subscriptions

 

List partner subscriptions

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

 
gethttps://api-global.ezypay.com/v2/partnersubscriptions
curl --request GET \
  --url https://api-global.ezypay.com/v2/partnersubscriptions \
  --header 'merchant: Merchant'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-global.ezypay.com/v2/partnersubscriptions")
  .get()
  .addHeader("merchant", "Merchant")
  .build();

Response response = client.newCall(request).execute();
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-global.ezypay.com/v2/partnersubscriptions");
xhr.setRequestHeader("merchant", "Merchant");

xhr.send(data);
var client = new RestClient("https://api-global.ezypay.com/v2/partnersubscriptions");
var request = new RestRequest(Method.GET);
request.AddHeader("merchant", "Merchant");
IRestResponse response = client.Execute(request);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-global.ezypay.com/v2/partnersubscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "merchant: Merchant"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

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

Response

OK

dataarray

List of search results returned.

pagingobject

Paging information.

paging.nextUrlstring

URL to retrieve the next set of records.

paging.nextCursorinteger

Unique identifier indicating the current state in pagination and where to resume the within search results. Using a cursor instead of page numbers avoids returning duplicate records should additional resources be added between pagination calls.

paging.limitinteger

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

paging.totalCountinteger

Total records that fulfil the search criteria.

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-global.ezypay.com/v2/partnersubscriptions